Concept - CMS - Call Parameters

1 Introduction

Like parameterized functions or procedures in a programming language, a lot of content instances cannot be executed independently. This means that the content instances are rendered in the storefront, but expect a certain set of parameters to be available in their execution environment. For instance, a component to render products most certainly requires a product as input parameter. The content model that the instance is based on determines the parameters this parameter set contains. It does so by providing further elements called "Call Parameter Definitions".
The current pipeline dictionary represents the execution environment of a content instance. This is not necessarily the dictionary of the current request since several or all parts of a composite content instance can be rendered in one request. Rendering sub-elements of a composite can then be imagined in the same way as the rendering of strict ISML modules or the execution of strict pipelines, i.e., each sub-element will be served with its own dictionary.

The following values are always available in the execution environment of a content instance:

Dictionary Key

Type

Description

CurrentRequest

com.intershop.beehive.core.capi.request.Request

The current request.

CurrentSession

com.intershop.beehive.core.capi.request.Session

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.

2 Model

2.1 Call Parameter Definition

Call parameters are described in content models by using the element callParameterDefinitions. The respective Java interface is com.intershop.component.pmc.capi.definition.pagelet.CallParameterDefinition.

Attributes

  • name: A name that has to be unique within the scope of the model parent.
  • type: The Java type of the object the call parameter will be served with at runtime.
  • optional: A call parameter may be optional, i.e., it is not required at runtime.

Example

<?xml version="1.0" encoding="UTF-8"?>
<pagelet:PageletModel name="product.pagelet2" ...>
   <pageletDefinitions name="component" page="false">
      <callParameterDefinitions name="Product" type="com.intershop.component.product.capi.ProductBO" optional="false"/>
      <callParameterDefinitions name="Category" type="com.intershop.component.catalog.capi.CatalogCategoryBO" optional="true"/>
      ...
   </pageletDefinitions>
</pagelet:PageletModel>

2.2 Call Parameter Mapping

Content instances may be composites or aggregates, i.e., a content instance is made up of other content instances which, again, may also be composites or aggregates. It is possible to pass on call parameters of one content instance to its sub-content instances. The process of relaying call parameter values is called "parameter mapping"; it will happen automatically when the content models of the outer and inner content instance have matching call parameter definitions. Two call parameter definitions match when they have the same name and type.

The following diagram demonstrates how call parameter mapping takes place at rendering time.

CallParameterMapping

The call parameter values of a and b are mapped from the environment of the pagelet a to the environment of the slot s. From this environment, the value of d is mapped to the environment of the pagelet b. These mappings are defined at the content model items building the base for the existence of slot s within the pagelet a, a model element of type SlotInclusionDefinition, and the fact that pagelet b could be assigned to slot s, a model element of type ContentEntryPointDefinitionExtension. Since both pagelets and the slot require different call parameters according to their models, explicit call parameter mappings have to be provided at the inclusion and extension binding the model elements together. The content model element defining call parameter mappings is parameterMappings.

Attributes

  • source: The name of the source parameter the value of which is mapped at rendering time.
  • target: The name of the target parameter that the value of another parameter is mapped to.

Example

<?xml version="1.0" encoding="UTF-8"?>
<pagelet:PageletModel name="contentmodel.pagelet2" ...>
  <pageletDefinitions name="A" page="false">
    <callParameterDefinitions name="a" type="java.lang.String"/>
    <callParameterDefinitions name="b" type="java.lang.String"/>
    <callParameterDefinitions name="c" type="java.lang.String"/>
    <slotInclusionDefinitions>
      <slotDefinition referencedName="contentmodel.pagelet2-S" />
      <parameterMappings xsi:type="pagelet:ParameterMappingDefinition" target="d" source="a"/>
      <parameterMappings xsi:type="pagelet:ParameterMappingDefinition" target="e" source="b"/>
    </slotInclusionDefinitions>
  </pageletDefinitions>
  <slotDefinitions multiplicity="ZERO_MANY" name="S">
    <callParameterDefinitions name="d" type="java.lang.String"/>
    <callParameterDefinitions name="e" type="java.lang.String"/>
  </slotDefinitions>
  <pageletDefinitions name="B" page="false">
    <callParameterDefinitions name="f" type="java.lang.String"/>
    <contentEntryPointExtensionDefinitions>
      <contentEntryPointDefinition referencedName="contentmodel.pagelet2-S" />
      <parameterMappings xsi:type="pagelet:ParameterMappingDefinition" target="f" source="d"/>
    </contentEntryPointExtensionDefinitions>
  </pageletDefinitions>
</pagelet:PageletModel>

2.3 Configuration Parameter Mapping

In the same way that call parameters of one content instance can be passed on to another one at rendering time, it is possible to use a configuration parameter value of a content instance as call parameter value for its sub-instances.

ConfigurationParameterMapping

The diagram above shows a slot which has two configuration parameters, a and b, and is rendered in the storefront. The value of a is mapped to the call parameter c of the pagelet b bound to slot s when it is rendered. The values of configuration parameters to be mapped to call parameters may be of arbitrary type since their method toString is used when they are bound at rendering time. The content model element responsible for the specification of configuration parameter bindings is configurationMappings.

Attributes:

  • source: The name of the source configuration parameter the value of which is mapped to a call parameter.
  • target: The name of the target call parameter that a configuration parameter value is mapped to.

Example

<?xml version="1.0" encoding="UTF-8"?>
<pagelet:PageletModel name="contentmodel.pagelet2" ...>
  <slotDefinitions multiplicity="ZERO_MANY" name="S">
    <configurationParameterDefinitions name="a" typeReference="types.pagelet2-Text" />
    <configurationParameterDefinitions name="b" typeReference="types.pagelet2-Text" />
  </slotDefinitions>
  <pageletDefinitions name="B" page="false">
    <callParameterDefinitions name="c" type="java.lang.String"/>
    <contentEntryPointExtensionDefinitions>
      <contentEntryPointDefinition referencedName="contentmodel.pagelet2-s" />
      <configurationMappings xsi:type="pagelet:ParameterMappingDefinition" target="c" source="a"/>
    </contentEntryPointExtensionDefinitions>
  </pageletDefinitions>
</pagelet:PageletModel>

3 Rendering

Call parameters, whether mapped from anywhere else or not, are accessible in rendering templates or pipelines by simply using their names as specified in the content models. However, if a mandatory call parameter for it is not available, it will not prevent the content instance from being rendered; a warning message will be logged.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets