Introduction

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

• configuration parameters and
• slots where further pagelets might be plugged in.

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.

Model

Pagelet definitions are the model elements for pagelet instances. The corresponding XML element in content model files is pageletDefinitions and the Java interface is com.intershop.component.pmc.capi.pagelet.definition.PageletDefinition.

Elements

• 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 callParameterDefinitions element.

• 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 slotInclusionDefinitions. A 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:

  <renderTemplate referencedName="comp/MyComponent.isml"/>
  

• 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:

  Dictionary Key	Type	Description
  CurrentRequest	com.intershop.beehive.core.capi.request.Request	The current request.
  CurrentSession	com.intershop.beehive.core.capi.request.Seesion	The current session.
  CurrentUser	com.intershop.beehive.core.capi.user.User	The current user.
  CurrentDomain	com.intershop.beehive.core.capi.domain.Domain	The current execution site.
  CurrentAppContext	com.intershop.beehive.app.capi.AppContext	The current application context.
  Pagelet	com.intershop.component.pmc.capi.pagelet.Pagelet	The pagelet about to be rendered.
  <CallParameter>*	*	All call parameters as defined by the callParameterDefinitions elements and only if there is a respective value in the outer execution environment.

  The pipeline reference is held by the attribute referencedName and must consist of the pipeline name followed by the start node:

  <renderPipeline referencedName="ViewPagelet_comp-MyComponent"/>
  

Attributes

• 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.

  Note

  If set to true, 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.

Example

<?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>

PO

The public interface for pagelets is com.intershop.component.pmc.capi.pagelet.Pagelet. 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.

Rendering

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 Pagelet.

Page Variants

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

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

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 true.

Caching

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.