Page variants are composites according to the composite pattern. As such, page variants cannot be used as sub-elements of other components or page variants. However, page variants are conceptually the same as components since they share the same structure and properties. For that reason, both are implemented by the same technical concept called pagelets.
Pagelets embody real content and have a visual representation in the storefront. The content structure of a pagelet is made up of
The blueprint for this content structure is described by a pagelet definition. This definition is the counterpart of the pagelet at content model level, which also refers to a so-called render template. This template is an ISML template acting as link between the content structure and the storefront.
Pagelet definitions are the model elements for pagelet instances. The corresponding XML element in content model files is
pageletDefinitions and the Java interface is
configurationParameterDefinitions: The pagelet definition provides a configuration parameter definition for each configuration parameter of a pagelet instance.
callParameterDefinitions: A pagelet instance may need certain parameters in its execution environment, mainly information that can only be obtained at rendering time. Such information cannot be stored in configuration parameters. Each of these parameters has to be declared by a
slotInclusionDefinitions: A pagelet instance may provide a sub-structure consisting of further pagelet instances. The entry points for the childs are slots. A slot needs to be included by the pagelet definition of the pagelet instance. This is done by referencing an already existing slot definition which describes the requirements the slots have to match. Slot definitions are not defined within pagelet definitions since they are meant to be re-usable. A
slotInclusionDefinitions is a container element for the actual slot which is encoded by a
slotDefinition element. A
slotInclusionDefinition can contain only a single
slotDefinition. In other terms, each
slotDefinition has to be wrapped by its own
slotDefinition element has a mandatory attribute
referencedName referring to the slot definition to be included. Possible values are the qualified names of slot definitions.
<slotInclusionDefinitions> <slotDefinition referencedName="slot.common.group.Content.pagelet2-Slot" /> </slotInclusionDefinitions>
renderTemplate: Pagelets are meant to cover certain areas in the storefront visually. Pagelets hold data to be displayed in these areas. The dedicated ISML templates define how these data and the structure are to be formatted and arranged. Each of these templates has to render pagelets of a certain type, i.e., pagelets based on the same pagelet definition. Hence, the templates are called render templates. They are referred to by the element
renderTemplate with the mandatory attribute
referenceName holding the template name including its path:
renderPipeline: If the rendering of a pagelet needs more information than given by the pagelet's configuration parameters and call parameters this data can be calculated or collected based on the configuration parameters and/or call parameters. To do so, the pagelet definition has to be augmented with a so-called render pipeline. This pipeline functions as a data collector pipeline. It is not involved in the actual pagelet rendering. If specified, the render pipeline will be invoked before the pagelet is rendered with its render template. The result of the render pipeline is copied to the execution environment of the pagelet and is therefore accessible during render template execution. The start node of the pipeline is supplied with the following dictionary entries:
The current request.
The current session.
The current user.
The current execution site.
The current application context.
The pagelet about to be rendered.
All call parameters as defined by the
The pipeline reference is held by the attribute
referencedName and must consist of the pipeline name followed by the start node:
name: The name of the model element. It has to be unique within the enclosing pagelet model.
page: This attribute indicates whether the pagelet definition is meant for page variants or components.
remoteInclude: Indicates whether the pagelets derived from the definition have to be rendered as Web Adapter includes or local includes. The attribute is only evaluated for components; the render template referenced in the pagelet definition determines how a page variant is to be handled by the Web Adapter.
container: This attribute is related to the call parameter handling when a pagelet is rendered. If set to
true, the pagelets based on the definition are transparent to the call parameter handling, i.e., all values from the outer environment will be passed on to inner slots of the pagelets. In other words, the attribute may be considered as an on/off switch for the call parameter handling.
If set to
container will override
remoteInclude, i.e., the pagelets are never rendered as Web Adapter includes. This is useful for layout components that are not relevant to page caching and would otherwise reduce the Web Adapter's performance.
<?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" name="comp.common.group.pagelet2"> <pageletDefinitions name="comp.common.group" container="true"> <configurationParameterDefinitions optional="true" name="cssClass" localizable="false" visible="true" typeReference="types.pagelet2-Text" /> <configurationParameterDefinitions optional="true" name="grid" localizable="false" visible="true" typeReference="parametertype.gridsystem.pagelet2-960GridSystem" /> <configurationParameterDefinitions optional="true" name="hoverState" visible="true" typeReference="types.pagelet2-Boolean" /> <configurationParameterDefinitions optional="true" name="customHoverClass" localizable="false" visible="true" typeReference="types.pagelet2-Text" /> <configurationParameterDefinitions localizable="false" name="trackingCode" optional="true" typeReference="types.pagelet2-Text" /> <renderTemplate referencedName="comp/common/Group" /> <slotInclusionDefinitions> <slotDefinition referencedName="slot.common.group.Content.pagelet2-Slot" /> </slotInclusionDefinitions> ... </pageletDefinitions> </pagelet:PageletModel>
The public interface for pagelets is
Pagelet inherits from
com.intershop.component.pmc.capi.pagelet.ConfigurationParameterCtnr, i.e., instances of
Pagelet may have configuration parameters. The entry points to the sub-structure of pagelets are instances of
com.intershop.component.pmc.capi.pagelet.Sot. Slot instances cannot exist without a parent pagelet; their lifecycle is bound to the parent pagelet. On pagelet creation, a slot instance is created for each slot definition included by the pagelet definition the pagelet is based on. So, the content structure represented by a pagelet is quite similar to the structure of the definition of the pagelet.
The actual rendering of pagelets is done by executing their render templates. The configuration parameters of a pagelet are passed to the render template as a map with the names of configuration parameters(as specified in the pagelet defintion) as keys, and the respective configuration parameter instances as values. The dictionary key for the map is
PageletConfigurationParameters. The pagelet itself can be obtained by the dictionary key
Page variants, i.e., pagelets derived from a pagelet definition with the page flag set to
true, cannot be rendered directly. Page variants are meant to be attached to pages and, therefore, are rendered when pages are rendered. Pages are brought to the storefront by invoking view pipelines. Such a view pipeline is required to call
ViewPage-Start at the end of its execution thread. The logic in
ViewPage-Start selects the currently active page variant of the specified page and adds the render result of the page variant to the server response.
Components, i.e., pagelets derived from a pagelet definition with the page flag set to
false, can be either rendered directly by using the ISML module
ISPagelet or automatically when assigned to a slot and this slot is rendered (see slot section).
ISPagelet is a strict module and has only one parameter
Pagelet, i.e., the pagelet to be rendered. The call parameters as required by the definition of the pagelet is mapped automatically from the dictionary currently active in the environment the module is embedded to the execution environment of the module. The render template of the pagelet is either included locally, when the flag
remoteInclude of the pagelet definition is set to
false, or as Web Adapter include, when the flag is set to
ISPagelet tag does not perform any checks for visibility- or date/time-constraints. It just prepares the pipeline dictionary and renders the given pagelet. Use a system-managed page -or a system-managed include if the evaluation of these constraints are important. The provided means for rendering entry points are described here.
Although it is possible to determine pagelets to be rendered as Web Adapter includes, the caching of the render results of pagelets must still be managed within the involved ISML templates by using appropriately configured cache tags. If caching is active for a pagelet, the CMS takes care that the CMS cache time is always in sync with its publishing period and its visibility period within the context of a slot or pagelet entry point.