1 Model

1.1 Configuration Parameter Definition

A configuration parameter definition is part of the content model development work done using Intershop Studio. The following content model artifacts can contain such elements:

Unlike other content model elements (e.g. Slot Definition) a configuration parameter definition is not referable. This means that you cannot create such definitions in one .pagelet2 file and refer to the definitions from a different content model file. The definition is always created in the context of one of the above-mentioned model artifacts.

Remember: a configuration parameter represents a leaf in the content composition tree. The meaning of a configuration parameter definition depends on how you use it in other Intershop development artifacts (like ISML templates & pipelines). It can either represent the actual content in the CMS, such as text, images, links and so on, or determine the behavior embodied by a pipeline.

Attributes

• localizable: Imagine a consumer channel that must support more than one language. Since configuration parameters can be presented as content to the consumer visiting the storefront, the parameters can also have a language-dependent value. Part of the model work is therefore to define which configuration parameter definition is language-depending and which ones are neutral.

• multiple: If a configuration parameter can have more than one value, this attribute must be set to true on the corresponding configuration parameter definition. When managing values for such a "multi-value" configuration parameter, the back office can include HTML markup to show a list element instead of a single line of text.

• optional: If the presence of a configuration parameter value is not required at rendering time, this attribute must be set to true. It must be set to false if you want to enforce a configuration parameter to contain a value.

• typeReference (alias Parameter Type Definition): Contains a qualified name that refers to a configuration parameter type instance defined in the same content model file or some place else.

• visible: Influences the visibility of the configuration parameter inside the management application (i.e. back office). An invisible configuration parameter can get a default value by its defining configuration parameter definition. If set to true, the management application renders management artifacts to show the configuration parameter. If set to false, no parameter is shown. true is the default.

1.2 Configuration Parameter Type

One might ask: why is it necessary to have a model element (i.e., configuration parameter type) only for describing another model element (i.e., configuration parameter definition)?
First, by doing so you can create new configuration parameter types for the features you need without changing existing code. Second, by using an instance of or type semantic you can make assertions that all configuration parameter definitions including their instances (configuration parameter) must fulfill.

Attributes

• valueHandler (alias Value Handler): This string value must contain a fully qualified name of a Java class implementing c.i.c.pmc.capi.definition.pagelet.ParameterValueHandler. It therefore defines the way how a configuration parameter that is based on a configuration parameter definition referring to a configuration parameter type will encode or decode its value.

1.2.1 UI

In addition to that, binding of back office UI elements is based upon configuration parameter types. An assertion like that makes it possible to build a generic back office UI for managing configuration parameter(s) of content instances. All that is possible without fully implementing the management page of each individual content instance.
Such a UI element assignment is done using another EMF model instance called UIDefinitionModel. That model is clearly made for configuration parameter UI definition only. It should not be used for any other purpose.

<uidefinition:UIDefinitionModel xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:uidefinition="http://www.intershop.de/uidefinition/2010" name="MyConfigurationParameterTypeUIDefinition">
  <configurationParameterTypeUIDefinitions
       referencedType="parametertype.pagevariationmeta.pagelet2-PageVariationMeta"
       editingTemplate="content/parameters/MetaConfigParameterInc"
       webForm="CookbookParameterTypes-MetaConfigForm" />
</uidefinition:UIDefinitionModel>

The above example has been taken from the Cookbook . It shows the binding of an editing template resource and a webform resource with the configuration parameter type parametertype.pagevariationmeta.pagelet2-PageVariationMeta. If such a binding for a configuration parameter type is missing or contains invalid resource references, an error message like UI definition error for [] is shown.

1.2.2 Parameter Value Handler

A parameter value handler is the implementation of interface c.i.c.pmc.capi.definition.pagelet.ParameterValueHandler<T>. It hides the complexity on how to transform value(s) of a ConfigurationParameter for further processing. This processing includes updating configuration parameter database objects (see next chapter), the import/export framework, and rendering.

1.3 Additional Parameters

Additional parameters can be used to provide further metadata describing a configuration parameter definition. For instance, it can be useful to further describe a configuration parameter definition for storing a reference to a file from the shared file system using the file extension the selected file must have.

<?xml version="1.0" encoding="UTF-8"?>
<pagelet:PageletModel xmlns:pagelet="http://www.intershop.de/pagelet/2010" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:core="http://www.intershop.de/core/2010" name="comp.common.SomeExample.pagelet2">
  <pageletDefinitions name="comp.common.SomeExample">
    <configurationParameterDefinitions optional="true" name="js_reference" typeReference="types.pagelet2-FileRef">
      <parameterBindings xsi:type="core:ParameterValueBinding" name="FileExtension" value=".js" />
    </configurationParameterDefinitions>
  </pageletDefinitions>
</pagelet:PageletModel>

In the example, the configuration parameter definition named js_reference contains the value .js for parameter FileExtension. The CMS framework allows only string-based values for additional parameters. There is no parameter value handler responsible for that kind of parameter.

Evaluation of a parameter value can be done anywhere the configuration parameter definition is accessible: that is, in the back office UI, during rendering and so on.

2 PO

Only configuration parameter definitions have a database representation of type c.i.c.p.capi.pagelet.ConfigurationParameter. New configuration parameter database objects (from now on just called configuration parameters) will be created lazily as soon as owning content instances are updated. This is done for every configuration parameter definition contained in the corresponding content model artifact. Check the table above (configuration parameter definition) to see to which content instances this rule applies.

Technically, all Java types extending c.i.c.p.capi.pagelet.ConfigurationParameterCtnr are able to hold configuration parameters. The back office responsible for managing configuration parameters provides the necessary checks to support lazy parameter creation.

The above picture completes this tableby showing which type of content instances extend ConfigurationParameterCtnr. Removing one of them also removes the contained configuration parameters.

3 Rendering

When rendering a ConfigurationParameterCtnr the CMS framework ensures that a java.util.Map object will be placed inside the pipeline dictionary. The map contains key-to-value mappings that enable the ISML render template to access expected configuration parameters by name. From within the render template it is legal to access the value by name since the template is part of the model instance just like the configuration parameter definition.

Example from FreeStyle.isml:

<div<isif condition="#isDefined(PageletConfigurationParameters:cssClass) AND (PageletConfigurationParameters:cssClass NE '')#"> class="<isprint value="#PageletConfigurationParameters:cssClass#">"</isif>>
<isHtmlPrint value="#PageletConfigurationParameters:text#" mode="storefront">
</div>

The configuration parameters map provided by the CMS framework can be accessed using the pipeline dictionary key PageletConfigurationParameters. On the result you can directly use the parameter name to get a hold of the parameter value. Implicitly, the responsible parameter value handler (taken from the configuration parameter type) has been invoked to decode the string-based value into whatever object is expected. The example above only shows access to string objects. Complex types like MetaTagInfo(see recipe Creating a Configuration Parameter Type ) allow further access.

<meta name="title" content="<isprint value="#PageletConfigurationParameters:metaInfo:Title#">" />