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.
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:
contentEntryPointDefinition is a model reference to a content entry point definition. A definition qualified name is expected as value.
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.
All pagelet assignments share a common set of attributes.
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.
As this chapter is merely focusing on content entry points it is still important to know about another assignment type.
An assignment type that connects a pagelet entry point to any arbitrary database object (i.e., view context, product or catalog-category). It is called
PageletEntryPointAssignment and it closes the gap between content (in the literal sense of the word) and pagelet (presentation). For more information, please have a look into Concept - CMS chapter View Contexts.
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:
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
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.
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
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.
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.
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:
Slot object is a filter slot.
Slot object is a dynamic slot.
Slot object to return all
PageletAssignments as per description in chapter "Assignments / Rendering"
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>
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.
As the slot is one of the constituent parts of a pagelet, the pagelet that owns the
Slot object must also be present, otherwise the object lookup by name will fail. From the beginning on (=Page Entry Point), the CMS framework inserts them (i.e., the pagelet) into the pipeline dictionary.
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.
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 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:
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.
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.
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.
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).
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.
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.
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.
A system-managed pagelet entry point is created:
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
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.
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.
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);
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.
All pieces of code that are mentioned here are available to be used by the application developer to render a somehow determined
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
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.
PageletEntryPointUUID, PageletEntryPointID, ResourceSet
PageletEntryPoint, PageletEntryPointUUID, PageletEntryPointID
Initiates the render process (including call parameter evaluation) for the given page object or the string values identifying a page.
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.
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.
Remember: Functional Pages are always system-managed pages. Therefore, it is legal to refer to them at development time and place a
ID value in the pipeline dictionary before calling the render pipeline
ViewPage-Start. Make sure the value is equal to the qualified name of the defining
Page Entry Point Definition.
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.
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
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
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, 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.
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.
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.
PageletEntryPointUUID, PageletEntryPointID, ResourceSet
Initiates the render process (including call parameter evaluation) for the component entry point object identified by ID and an optional
To implement a loop over all pagelets available at rendering time and assigned to the given pagelet entry point. The iterator order is equal to the priority (highest first) in which pagelets are assigned.
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.
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:
pageletAssignmentsEnabled = false and
pageletPipeline set → The pipeline will determine pagelet assignments fully dynamically
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>
An extension to the
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.
The extension will only be created and registered in the context of the storefront application itself or its management application. It is not applicable for the organization/channel context.
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.
|Content Entry Point Type
<S extends ContentEntryPoint<S>> Iterator<? extends Pagelet> getPagelets(ContentEntryPoint<S> cep)
|Returns all dynamically assigned pagelets to this content entry point by executing the
pageletPipeline of its definition.
<S extends ContentEntryPoint<S>> Iterator<? extends Pagelet> getPagelets(ContentEntryPoint<S> cep, Date date)
Returns all dynamically assigned pagelets to this content entry point by executing the
<S extends ContentEntryPoint<S>> Iterator<? extends Assignment<Pagelet, S>> getPageletAssignments(Collection<? extends Assignment<Pagelet, ?>> assignments, ContentEntryPoint<S> cep)
|Returns all filtered pagelet assignments based on the provided pagelet assignments by executing the
pageletPipeline of the given content entry point's definition.
<S extends ContentEntryPoint<S>> Iterator<? extends Assignment<Pagelet, S>> getPageletAssignments(Collection<? extends Assignment<Pagelet, ?>> assignments, ContentEntryPoint<S> cep, Date date)
|Returns all filtered pagelet assignments based on the provided pagelet assignments by executing the
pageletPipeline of the given content entry point's definition. Additionally provides the date to the rendering dictionary.
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:
|Pagelet Pipeline Type
|Provided to Pipeline
|Expected from Pipeline
Additionally the following is provided to either type of pagelet pipeline based on the type of the content entry point:
|Content Entry Point Type
|Provided to Pipeline
|Pagelet Entry Point
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.
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.
pageletPipeline to filter is not executed in the back office.
pageletPipeline in the storefront application context
pageletPipeline to filter is not executed in the back office.
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.