NAME

Krang::ElementLibrary - the element class loader and indexer

SYNOPSIS

  use Krang::ClassLoader 'ElementLibrary';

  # load an element set by name
  pkg('ElementLibary')->load_set(set => "Flex");

  # get a list of available top level elements
  @top_levels = pkg('ElementLibary')->top_levels());

  # get the object for the top level called "article" from the current set
  $class = pkg('ElementLibary')->top_level(name => "article");

  # find a class within the current set
  $class = pkg('ElementLibrary')->find_class(name => "deck")

  # get a list of all element names, anywhere in the element library
  @names = pkg('ElementLibrary')->element_names();

  # get the list of other elements that "paragraph" can be changed into
  @classes = pkg('ElementLibrary')->changeable_classes('paragraph');

DESCRIPTION

This module is responsible for loading the Krang Element Library and allowing access to the classes contained within it. Each instance is configured with an element set in krang.conf:

  <Instance test>
     InstanceElementSet Flex
  </Instance>

This library is responsible for loading the configured element sets and responding to requests to find individual element classes.

Element Sets

An element set consists of a configuration file, set.conf, and a series of Perl modules implementing the element classes. The configuration file is in Apache format and may contain the following directives:

• Version (required)
  
The version number of element set. Should be a floating point number.
• KrangVersion (optional)
  
The version of Krang required by this element set. This should be incremented when features are used that are not available in all versions of Krang.
• ParentSets (optional)
  
Set this option to a list of element sets to inherit from. Parent element sets will be searched in the listed order for element classes. For example, to allow access to the Default set, use:

  ParentSets Default

Note that you will still need to enumerate the TopLevels available in the parent sets to make them available. This allows you to decide which toplevel elements to inherit from the parent set.

• TopLevels (required)
  
Set this option to a list of top-level elements that should be made available for Story creation. These must be modules in the element set, or in one of the inherited element sets. For example, if you specify in Flex/set.conf:

  ParentSets Default
  TopLevels article cover category_archive author_archive category

Then either Flex/article.pm or Default/article.pm must exist (and so on for each item in TopLevels).

INTERFACE

• Krang::ElementLibrary->load_set(set => $set_name)
  
Loads the element set with a given name. Will die on error. Returns true on success.

If the environment variable KRANG_NO_ELEMENTLIBS then nothing will actually be loaded. This is useful to use in scripts that won't actually use element libraries but through some chain of use statements ends up requiring that in it's chain of dependencies uses Krang::Element, but we know we aren't actually going to use any elements.

• @toplevels = Krang::ElementLibrary->top_levels()
  
Returns a list of top-level class names supported by the configured element set for the active instance. Use the type parameter to select only story or category elements. These names can be used in calls to top_level().

Note that the top level element name 'category' is special. You must filter out this name to use the list for possible story types.

• $class = Krang::ElementLibrary->top_level(name => "article")
  
Returns the class for a given type and name, as returned by top_levels(). Will die if the given name is not a valid top-level element.
• @names = Krang::ElementLibrary->element_names()
  
Returns a list of element names in the current InstanceElementSet. This list is uniqued (since the same name may be used in different places in the set) and sorted.
• $class = Krang::ElementLibrary->find_class(name => "deck")
  
• $class = Krang::ElementLibrary->find_class(name => "deck", set => "Flex")
  
Finds an element class by name, looking in the configured InstanceElementSet for the current instance unless as set argument is passed. If the InstanceElementSet has ParentSets configured, will look there too. Returns an object descended from Krang::ElementClass or undef on failure.

This call only finds classes that are declared as separate packages, not those declared inline.

For testing purposes, set $Krang::ElementLibrary::TESTING_SET and find_class() will look there rather than the current InstanceElementSet.

• @classes = Krang::ElementLibrary->changeable_classes("paragraph")
  
Returns the names of other element classes that the given element class can be inter-changed with.

TODO

Implement KrangVersion checking.