Assignments

To achieve the composition of pagelets a data structure must be present to connect a content entry point (on one side) with a pagelet (on the other side). In addition all kinds of settings that the content manager can change must be aggregated in that structure. Generally speaking this structure is called Assignment. The CMS framework has specialized Assignment to PageletAssignment manifesting characteristics like time-based activation, order and owner relationship.

Model

The introduction to assignments above is only referring to the content instance layer. On content model level there is also a possibility to express a legitimate association between a pagelet definition and a content entry point definition. Such a model element is called Content Entry Point Extension Definition and can only be used within a pagelet definition. That means, only the pagelet definition can define to which content entry point definition instances of itself are assignable (not vice versa).

Content Entry Point Extension Definition:

Elements

• contentEntryPointDefinition is a model reference to a content entry point definition. A definition qualified name is expected as value.

Attributes

• None

This explicit mention of a content entry point definition in a pagelet definition is quite inflexible. Reason for that is, you have to create new extension definitions for every new content entry point definition you would like to support. A lot of model maintenance work would be the result. That short-come is the reason for another content model element called Call Parameter Interfaces. They are a more flexible model approach because you only have to make sure your pagelet definition provides a call parameter interface model instance. If so, then all pagelet instances based on that pagelet definition automatically fit into content entry point definitions that fulfill the contract of the referred call parameter interface.

PO

All pagelet assignments share a common set of attributes.

• validFrom: Date
• validTo: Date
• online: boolean
• position: double

Which means they can be valid for a certain time ( validFrom, validTo), they can be completely deactivated ( online) regardless of their time and they can be prioritized in a set of other pagelet assignments ( position). This process is sometimes also just called pagelet scheduling.

The UML diagram shows all extensions of PageletAssignment important for this chapter about content entry points. These subtypes of pagelet assignment make it possible to connect a pagelet with a placeholder, a pagelet entry point and a slot on the content (instance) layer. Only when including the rules expressed on content model level, it will become clear that not all pagelet assignments are necessarily legal. Otherwise it would be possible to, e.g., insert a footer component into a header slot. The CMS back office UI for managing pagelet assignments has to obey the rules contained in the content model instances of the participating content instances.

Rendering

In short, rendering a pagelet assignment means selecting pagelet(s) to be displayed from a set of different assignments. Rules that apply to the selection logic are fixed. Customization can be done only to some extent. Out of the box the fixed order in which rules are evaluated is like this:

• Time based activation: Based on a rendering time value, select pagelet assignments whose activation time frame (see PO above) holds true and which are activated. Same applies to the pagelet behind each pagelet assignment.
• VisibiltyFilter(UserGroup): Based on a set of active user groups (= consumer groups), select pagelet assignments whose pagelets are personalized. Such pagelets must match at least one user group out of the provided set. None-personalized pagelets are shown to everybody by default. A personalized pagelet consists of at least one PageletUserGroupAssignment.
• VisibiltyFilter(AB Test Group): Based on a set of active AB Test groups, select pagelet assignments whose pagelets are assigned to some AB Test Group. Such pagelets must match at least one AB Test Group of the provided set.
• VisibiltyFilter(Promotion): Select pagelets with promotions assigned. These promotion must be active in terms of time, target group and application (business requirement of promotion). Is the pagelet assigned to an active promotion, the pagelet will be displayed. In the other case (pagelet is assigned to an inactive promotion), the pagelet will not be displayed.
• VisibilityFilter(Custom): Insert custom logic here, or replace any other standard VisiblityFilter from above. Please note, VisibilityFilter is short for (com.intershop.component.pmc.capi.pagelet.assignment.PageletVisibilityFilter)

Slots

Model

A slot is defined using a Slot Definition that is always part of a content model file. The Java interface representing such a slot definition is called com.intershop.component.pmc.capi.definition.pagelet.SlotDefinition. In a pagelet2 model file a slot definition can be found behind the xml element slotDefinitions. The model editor in Intershop Studio calls it also just Slot Definition.

Elements

• configurationParameterDefinitions: contains configuration parameter definitions that apply to this slot definition. As a result, the slot instance (PO) will contain a configuration parameter for every included definition. See chapter about "Configuration Parameter".
• callParameterInterfaces: by referring to a call parameter interface a slot definition declares itself to fulfill the contract behind the call parameter interface. As a result all pagelets that provide all mandatory call parameters of this contract will fit into the slot.
• callParameterDefinitions: adds a new call parameter definition to the contract of this slot definition.
• pageletPipeline: gives you the possibility to refer to a pipeline start node. Depending on the setting of pageletAssignmentsEnabled(alias Component Assignments Enabled) this either means: true) the pipeline is a filter pipeline that decides which pagelet assignments should be processed out of all contained pagelet assignments, false) the pipeline will determine pagelet assignments fully dynamically.

Attributes

• multiplicity: only some of the available values are important for the CMS framework. 1..n, 0..n, for multiple assignments to be rendered. 0..1, 1, for only a single assignment. All cases that imply to have at least one assignment available are important if you want to make sure that the slot is never empty. Although, a constraint like that will not be enforced by the CMS - meaning there is no check implemented (yet).
• upperBound: lets you specify a boundary of how many pagelet assignments will be processed during rendering. That boundary can only make sense if you've specified a multiplicity value that allows multiple assignments (>1) to be processed.
• lowerBound: is not evaluated within the CMS framework.
• pageletAssignmentsEnabled(alias Component Assignments Enabled): this setting lets you allow or deny that a back office user can create new pagelet assignments to a slot that is based on this slot definition. Denying means setting pageletAssignmentsEnabled to false. In consequence, the slot can only return pagelets determined by a pagelet pipeline. When assignment creation is allowed and a pagelet pipeline has been specified this means the slot is actually a "filter"-slot. More about filter slots will be explained later on in the rendering section of this chapter.
• remoteInclude: a boolean flag that specifies all assignments contained in this slot must be rendered using a web adapter include (in case remoteInclude=true). If a web adapter include should not be used, then all pagelet assignments are rendered synchronously. This setting has influence on the overall performance of the consumer storefront, as well as the web adapters caching behavior.

PO

The content instance layer of a slot definition is represented by the interface c.i.c.pmc.capi.pagelet.Slot. A slot is a constituent part of a pagelet (being a component or a page variant). This explains why creating a pagelet also includes the creation of slots for every slotDefinition referred inside a slotInclusionDefinitions of the pagelet definition.

Rendering

isslot

A tag called isslot has been provided to request the contents ( technically meaning all PageletAssignment objects) of a slot from within the pagelets render template. This implies that the Java code behind the tag uses information that is provided by some slot definition:

1. Is a pagelet pipeline given?
   1. Yes, then are "Component Assignments Enabled"?
      1. Yes, then carry on as if the Slot object is a filter slot.
      2. No, then carry on as if the Slot object is a dynamic slot.
   2. No, then ask the Slot object to return all PageletAssignments as per description in chapter "Assignments / Rendering"
2. Apply upper boundary constraints

The result from above will be an ordered set of PageletAssignments that are rendered one at a time.

<body <isif condition="#(isDefined(PageletConfigurationParameters:bodyId))#">id="<isprint value="#PageletConfigurationParameters:bodyId#">"</isif>
    <isif condition="#(isDefined(PageletConfigurationParameters:bodyClass))#"> class="<isprint value="#PageletConfigurationParameters:bodyClass#">"</isif>>

    <isslot slot="app_sf_responsive_cm:slot.footer.content.pagelet2-Slot">

</body>

The isslot tag has a mandatory attribute named slot. A qualified name that refers to the slot definition is expected to be used as value for that attribute. In the example above the HTML markup produced by the contents of the slot slot.main.Content.pagelet2-Slot will be inserted at the tags position.

Again, rendering a pagelet is done by executing their render templates. The isslot tag implementation will do the same thing with all PageletAssignment objects that have been determined for further rendering. The only question is, will the rendering result in creating a new application server request (web adapter include) or will it be processed in the same request context? As mentioned in the "Model" chapter this decision is influenced by the remoteInclude attribute of either a slot definition or a constituent pagelet definition.

isslotiterator

Sometimes there is the need to receive the contents of a slot wrapped as iterator-object for further processing. That way the caller of the isslotiterator tag can include additional markup around each iterator-value; making the rendering of the contained pagelet more explicit. On the contrary, when using the isslot tag from above all selected PageletAssignment are rendered implicitly with the module's invocation.

Page Entry Points

Page Entry Points are representing content entry points where complete pages can be plugged in. Such page entry points cannot be composed into further content elements since, when rendered at run-time, they always result in complete pages. In the beginning of this Concept - CMS an attempt to classify pages has been made:

1. Dynamic Pages (e.g., Category pages, Product page)
2. Functional Pages (e.g., My Account Section, Checkout, Cart)
3. Content Pages (e.g., FAQ, Terms & Conditions, News)

This chapter about Page Entry Points will touch these different kinds of pages and will elaborate how they can be used to build a CMS managed storefront.

Model

Page Entry Point Definition

Elements

• configurationParameterDefinitions: contains configuration parameter definitions that apply to this page entry point definition. As a result, the page instance will contain a configuration parameter for every included definition. See chapter about "Configuration Parameter".
• callParameterInterfaces: by referring to a call parameter interface a page entry point definition declares itself to fulfill the contract behind the call parameter interface. As a result all pagelets that provide all mandatory call parameters of this contract can be used as page variants for this page instance.
• callParameterDefinitions: adds a new call parameter definition to the contract of this page entry point definition.
• pageletPipeline: as described for Slot Definition content model artifact from above, this element can contain a reference to a pipeline start node. For page entry point definition this element is also available, but it will be ignored when rendering a page that is based on that definition.

Attributes

• pageletAssignmentsEnabled(alias Component Assignments Enabled): this setting is only reasonable in combination with the pageletPipeline element from above. Since the pageletPipeline element of a page entry point definition will be ignored during rendering, this attribute is also ignored by the CMS framework.
• systemManaged: this attribute determines how the life-cycle management of page entry point definition instances will take place. If its value is true, this means page creation and deletion is completely managed by the system and not by a back office user. A system-managed page entry point definition must be referable during development time as their instance (or instances, see chapter below) denotes certain points in the storefront, just as the interaction end nodes of pipelines.

Dynamic Pages

They should be modeled as systemManaged=false, because their instance is not directly referred from a view pipeline. Instead, a different CMS model artifact comes into place when talking about Dynamic Pages, that is the so called Context Object Relation. From such a model instance a Page Entry Point Definition can be included to express that e.g., a page for a category or a page for a product will be an instance of the included Page Entry Point Definition. Later when a category details page is requested by the storefront user, the page instance will be found and can be rendered by means provided through the CMS (see below). A more detailed description on the model artifact Context Object Relation and their instances see Concept - CMS - View Contexts (valid to 7.5).

Functional Pages

They denote points within a storefront (functional block) where a content editor wants to control the render result by plugging in a page entry point. The gap between such a functional block and the CMS is filled by the possibility to refer a Functional Page from a viewing pipline at development time. It should be clear by now that this reference can only point to a Page Entry Point Definition with systemManaged=true. Remember: With system-managed page entry points it is impossible to refer to a deleted page unless the model instance has been removed without updating the reference.

Content Pages

They are not system-managed, because a back office user must be allowed to freely create and delete them at any point in time. A Page Entry Point Definition that leads to a content page is very much like a dynamic page with one exception that makes it just a content page: The definition is not included in a Context Object Relation. Instead a Page Entry Point Definition for a content page just stands for itself without being included or referred to by some other development artifact.

PO

The representation of a page entry point on content instance level is called PageletEntryPoint. The CAPI interface is c.i.c.pmc.capi.pagelet.PageletEntryPoint. This section just talks about Page Entry Points which always represent complete pages shown to the storefront user. Next section will introduce Component Entry Points that are also represented by the PageletEntryPoint interface. As a distinction between Page Entry Points and Component Entry Points the boolean attribute page can be used. The term page in this section will be used as synonym for a Page Entry Point.

Creation

A system-managed pagelet entry point is created:

1. On system startup (on DBPrepare since 7.10.38.1), or
2. On organization & channel creation, or
3. By running job Synchronize Page Model and Pagelet Instances from the Server Management Console

On the contrary, a non-system-managed pagelet entry point is created using the back office. Such pages can be structured to form a page hierarchy which can be used for navigation or grouping. Both kinds of pagelet entry points (system-managed and non-system-managed) are identified by the value of attribute dynamic.

System-managed pages carry an ID that is equal to the QualifiedName of their defining Page Entry Point Definition. As per pagelet entry point's data model the ID of such an instance must be unique within a given domain. Therefore system-managed pages (as well as includes that are described below) exist not only once but n-times: where n is the number of master and channel repositories where the defining model instance is visible.

Deletion

System-managed pagelet entry point gets removed as soon as their model instance (i.e., Page Entry Point Definition) becomes unavailable in the context of their site. Obviously, a non-system-managed pagelet entry point (i.e., a Content Page) will be removed using the back office.

Navigation Structure

The PageletEntryPoint interface allows you to access the hierarchical structure of (content) pages.

public PageletEntryPoint getParentPageletEntryPoint(Domain domain);
public boolean hasParent(Domain domain);
public boolean hasSubPageletEntryPoints(Domain domain);
public Collection<? extends PageletEntryPoint> getSubPageletEntryPoints(Domain domain);

Rendering

Conceptually, a page entry point itself is empty and cannot be rendered. It is the set of intra-page artifacts that will embody a certain appearance of a page entry point at the given circumstances (i.e., request time, personalization etc). For all the different kinds of pages rendering starts with the selection of a PageletAssignment like described in the Assignment section above. The selection of the page entry point is depending on what kind of page needs to be rendered.

Overview

All pieces of code that are mentioned here are available to be used by the application developer to render a somehow determined PageletEntryPoint object.

Pipeline

Old mechanism (deprecated since IS 7.6)

The CMS provides a pipeline named ViewPage-Start that can be used to start the render process for pages. Developers of a view pipeline can use it by placing a jump node to it at the end of their pipeline. ViewPage-Start cannot be strict because of the necessary evaluation of Call Parameters when rendering any page. Moreover, when calling this render pipeline the CMS is expecting ONE of the following parameters:

The priority in the table above denotes the sequence in which CMS will ask the pipeline dictionary to return a value for the corresponding key - i.e., the existence of a PageletEntryPoint overrides an existing ID value.

New mechanism

The generic interaction end node RenderSystemPage in cartridge sld_pmc is meant to ease the pain of unnecessary dictionary key aliasing. Because pipeline ViewPage-Start was incapable of in-place call parameter mapping to conform to the expected rendering dictionary. Now using generic pipeline nodes this can be done easily. All you have to do is refer to the system-managed page entry point definition with a fully qualified name, e.g., app_sf_responsive:systempage.homepage.pagelet2-Page. Intershop Studio's Pipeline Editor will display the expected call parameters for further editing.

In pipelines it is expected that only qualified names denoting a system-managed page entry point definition will be used along with the above mentioned nodes. ViewPage-Start is still in place for (though discouraged) none system-managed item rendering.

ISML Tag

1 - ResourceSet parameter contains the cartridge id of the page entry point definition that uniquely identifies a system-managed page object. If ID is not denoting such an object, use the cartridge ID displayed in the Pages list hover shown in the Commerce Management application. However, it is strongly recommended to only refer to system-managed items from code artifacts like ISML.

Functional Pages

A functional page can be referenced at development time as pointed out above. At the interaction end of any given storefront viewing pipeline that implements a certain functional block, the corresponding functional page can be inserted.

Dynamic Pages

Pages that fall into this class (as in classification) are entirely handled by view contexts. See chapter View Contexts for details on how they get rendered. In short, the main difference between the rendering of a dynamic page and a functional page is the way how theses pages are being found. Functional pages can be referred to at development time. Dynamic pages are determined by a) referring to a View Context and b) the pipeline dictionary at rendering time.

Content Pages

Like Functional Pages, a content page is rendered by pipeline ViewPage-Start (sld_pmc) or by ISML module <ISPageletEntryPoint>. It is completely up to the storefront application how the different instances of content pages are to be found when browsing the storefront. It could be a special link component (Pagelet) that refers to a content page instance via configuration parameter value. Another possible way is to produce a list of links to content page instances by looping over sub-pages (see Navigation Structure) of a known Functional Page referenced by ID or PageletEntryPointID.

Important to know is that there is nothing that prevents an application developer from inserting a hard coded link to a content page into an ISML template. When doing so, the difference between a content page and a functional page gets blurred as content pages are also identified by their ID.

Permissions

CMS explicitly does not provide means to prevent pages from being rendered when using its public render API (e.g., ViewPage-Start, ISML modules). It falls into the responsibilities of the application to make sure that view pipelines available to the web browser are performing permission checks to resolve the correct CMS managed page. One could say now, that pipeline ViewPage-Start is always available to display a otherwise forbidden page. This is not the case, as ViewPage-Start is not available to requests from the web browser. It can only be called from application view pipelines.

Component Entry Points

Component entry points, like page entry points, are intended to plug in managed content into the storefront. Storefront here means all the viewing pipelines and ISML templates being part of the storefront application.

Component entry points may be regarded as a replacement for ISML includes or modules. They are quite handy if parts of a storefront are realized in a more conventional way, i.e., not using the CMS for the implementation of complete pages. One wants to have certain spots within a page that are manageable by the CMS. Typical examples are page headers or mini carts. The content elements a component entry point brings to the storefront are components, but, whereas a page entry point can only render a single page at one time, a component entry point may render multiple components at a time.

Rendering

From a runtime perspective, component entry points are eventually realized by POs and as such are passive objects, i.e., like page entry points they cannot render by themselves.

Overview

ISML Tag

The CMS comes along with facilities to embed component entry points in the storefront. A component entry point is bound to the storefront by a particular ISML tag, ISContentInclude. The table below outlines which tags are available and how they can be configured. This can be done either literally or dynamically by using an ISML expression.

1 - ResourceSet parameter contains the cartridge id of the component entry point definition that uniquely identifies a system-managed page object. If ID is not denoting such an object, use the cartridge ID displayed in the Includes list hover shown in the Commerce Management application. However, it is strongly recommended to only refer to system-managed items from code artifacts like ISML.

Dynamic CEPs and Filter CEPs

Content Entry Point Definitions

As stated in the sections earlier for each type of content entry point (see element and attribute descriptions of their definition), the combination of an existing pageletPipeline element and the pageletAssignmentsEnabled attribute as part of the content entry point definition determines the nature of the content entry point:

• Dynamic: pageletAssignmentsEnabled = false and pageletPipeline set → The pipeline will determine pagelet assignments fully dynamically
• Filter: pageletAssignmentsEnabled = true and pageletPipeline set → The pipeline is a filter pipeline that decides which pagelet assignments should be processed out of all contained pagelet assignments

As seen in the example below, there are two slot definitions. Slot1 would be a dynamic slot whereas Slot2 is a filter slot.

<pagelet:PageletModel xmlns:pagelet="http://www.intershop.de/pagelet/2010" name="DynamicAndFilterSlot.pagelet2">
  <slotDefinitions name="Slot1">
    <pageletPipeline referencedName="ProcessSlot-GetPagelets"/>
  </slotDefinitions>
  <slotDefinitions name="Slot2" pageletAssignmentsEnabled="true">
    <pageletPipeline referencedName="ProcessSlot-Filter"/>
  </slotDefinitions>
</pagelet:PageletModel>

ApplicationBOPageletPipelineExecutor Extension

An extension to the ApplicationBO called ApplicationBOPageletPipelineExecutor exists that provides with methods to execute the pageletPipeline in the storefront application context to determine dynamic/filtered pagelet assignments. This extension prepares the rendering dictionary with all key/value pairs that the pageletPipeline will need to determine the dynamically assigned pagelets or the filtered pagelet assignments.

API

The following table shows the methods of the ApplicationBOPageletPipelineExecutor with information to what type of content entry point it refers to and from what context the method are usually called.

Rendering Dictionary

The ApplicationBOPageletPipelineExecutor is not only responsible to execute pageletPipeline but also to provide it with all values necessary for the pipeline to determine the dynamic/filtered pagelet assignments. This is done by providing the pipeline with parameters in the pipeline dictionary provided to the pipeline (here called rendering dictionary). Also, after execution of the pipeline, certain parameters are expected to be in the rendering dictionary.

The following table shows the values that will be provided to the type of pipeline and will be expected from it:

Additionally the following is provided to either type of pagelet pipeline based on the type of the content entry point:

Back Office

In general, the user is not able in any context in the back office to assign/unassign pagelets to dynamic content entry points whereas this is possible for filter content entry points. However, the resulting pagelet assignments can be shown depending on the context. This will be further explained in the subsections.

Organization/Channel Context

• Dynamic: Since the pageletPipeline must be executed in the context of the storefront application, this is not possible in the context of an organization or channel. That means that there won't be any pagelet assignments shown.
• Filter: All explicitly assigned pagelets are shown. The pageletPipeline to filter is not executed in the back office.

Application Context

• Dynamic: Pagelet Assignments are shown as a result of the execution of the pageletPipeline in the storefront application context
• Filter: All explicitly assigned pagelets are shown. The pageletPipeline to filter is not executed in the back office.

Storefront Rendering

When rendering dynamic/filter content entry points, the ApplicationBOPageletPipelineExecutor is used to execute the pageletPipeline and to retrieve the pagelets to be rendered. Please see the API as seen in the sections above.