Connector for HCL Commerce Manual / 6.2.2 The CoreMedia Include Tag

Connector for HCL Commerce Manual / Version 2207

6.2.2 The CoreMedia Include Tag

Behind the scenes of the CoreMedia Content Widget works the CoreMedia lc:include tag. You may also use it in your own JSP templates to embed CoreMedia content on the commerce side. In general it is used like this:

<%@ taglib prefix="lc" uri="http://www.coremedia.com/2014/livecontext-2" %>
<lc:include
        storeId="${WCParam.storeId}"
        locale="${WCParam.locale}"
        catalogId="${WCParam.catalogId}"
        productId="${WCParam.productId}"
        categoryId="${WCParam.categoryId}"
        placement="${param.placement}"
        view="${param.view}"
        externalRef="${WCParam.externalRef}"
        exposeErrors="${not empty WCParam.externalRef
                      && empty WCParam.categoryId
                      && empty WCParam.categoryId}"
        httpStatusVar="fragmentHttpStatus"/>

All parameters are described in the next two sections.

Include Tag Reference

The tag attributes have the following meaning:

Parameter	Description
`storeId`, `locale`	These attributes are mandatory. They are used in the CAE to identify the site that provides the requested fragment.
`catalogId`	In a multi-catalog scenario this attribute is mandatory. It is used in the CAE to identify the catalog context for rendering the requested fragment.
`productId`, `categoryId`	These attributes are used in the CAE to find the context which will be used for rendering the requested fragment. Both parameters should not be set at the same time since depending on the attributes set for the include tag, different handlers are invoked: If the `categoryId` is set, `CategoryFragmentHandler` will be used to generate the fragment HTML. If the `productId` is set, `ProductFragmentHandler` will be used to generate the fragment HTML.
`pageId`	This parameter is optional. Usually, the page ID is computed from the requested URL (the last token in the URL path without a file extension). If you set the parameter, the automatically generated value is overwritten. On the Blueprint side an Augmented Page will be retrieved to serve the fragment HTML. The transmitted page ID parameter must match the External Page ID of the Augmented Page. You might use the parameter, for example, in order to have one CoreMedia page to deliver the same content to different shop pages.
`placement`	This attribute defines the name of a placement in the page grid of the requested context. In the example for the header fragment, the "header" placement was used. If you do not want to render a certain placement but a view of the whole context (generally a CMChannel), you may omit it. If the view attribute isn't set, the "main" placement will be used as default instead. This attribute can be combined with the `externalRef` attribute. In this case the placement will be rendered for a specific CMChannel, so the external reference must point to a CMChannel instance.
`view`	The attribute "view" defines the name of the CMS view which will render the fragment. Such view templates must exist on the CMS side. There are several views prepared in the Blueprint: `metadata` (to render the HTML title and metadata), `externalHead` (to render parts of the HTML header like CSS and JavaScripts that are needed in CMS fragments), `externalFooter` (is also mostly used for loading scripts) and `asAssets` (that can render the CoreMedia Product Asset Widget). If you omit the view, the default view will be used. In such cases you have either the `placement` or the whole page grid of a CoreMedia page is rendered.
`externalRef`	This attribute is used in the CAE to find content. Several formats are supported here as described in the next section. The attribute can be used in combination with the `view` and/or `parameter` attribute.
`parameter`	This attribute is optional and may be used to apply a request attribute to the CAE request. The request attribute is stored using the constant `FragmentPageHandler.PARAMETER_REQUEST_ATTRIBUTE`. The value may be read from a triggered web flow, for example, to pass a redirect URL back to the commerce system once the flow is finished. The attribute also supports values to be passed in JSON format (using single quotes only), for example `parameter="{'test':'some value','value':123}"`. The key/values pairs are available in the `FragmentParameters` object and may be accessed using the `getParameterValue(String key)` method. Other additional values, like information about the current user that should be passed for every request, may be added to the request context that is build when the commerce system requests the fragment information from the CAE (see next section).
`var`	This attribute is optional. If set, the parsed output of the CAE is not written in the parsed output stream but in a page attribute named like the `var` parameter value. This allows you, for example, to replace or transform parts of the CAE result or, if empty, to render a different output.
`exposeErrors`	This attribute is optional. If set to true, the tag will expose any errors that occur during the interaction with the CMS. These errors are then directly written to the response. Thus, the commerce system has the ability to handle the errors, to show an error page, for instance.
`httpStatusVar`	This attribute is optional. If set, the HTTTP status code of the fragment request is set into a page attribute named like the `httpStatusVar` parameter value. This allows you, for example, to react on the result code, for example, set the fragment as uncacheable in the caching layer of your commerce system.

Table 6.3. Attributes of the Include tag

External References

Any linkable CoreMedia content can be included as a fragment by specifying a value for the externalRef attribute. The value of the attribute is applied to the first ExternalReferenceResolver predicate that is applicable for the externalRef value. The Spring list externalReferenceResolvers which contains the supported ExternalReferenceResolvers is injected to the ExternalRefFragmentHandler. This section shows the supported formats that are applicable for the existing resolvers.

The following table shows an overview about the possible values for the externalRef attribute.

Value Type	Example	Description
Content ID	cm-coremedia:///cap/content/4712	Includes the content with the given cap id as fragment. The root channel of the corresponding site will be used as context.
Numeric Content ID	cm-4712	Works the same way like the content ID include, only with the numeric content ID.
Absolute Content Path	cm-path!!Themes!basic!img!icons!ico_rte_link.png	Includes the content with the given absolute path. All exclamation marks ('!') after the prefix 'cm-path!' will be mapped to slashes ('/') to provide a valid absolute CMS path. The given path may not contain 'Sites' (referencing content of a different site is not allowed). The `storeId` and `locale` parameter are still mandatory for this case.
Relative Content Path	cm-path!actions!Login	Includes the content with the given path treated as a relative path from the site's root folder. All exclamation marks ('!') after the prefix 'cm-path!' will be mapped to slashes ('/') to provide a valid relative CMS path. The given path may not contain '..' (going up in the hierarchy). The site is determined through the `storeId` and `locale` parameter.
Numeric Context and Content ID	cm-3456-6780	The prefix is the numeric content ID of the context to be rendered. The suffix is the numeric content ID of the content to be rendered with the given context.
Segment Path	cm-segmentpath:!corporate!on-the-table	The actual value (excl. the format prefix `cm-segmentpath:`) denotes a segment sequence, separated by exclamation marks. The segments are matched against the values of the `segment` properties of the content. The very last segment denotes the actual content. The other segments denote the navigation hierarchy which determines the context of the content. The example value references a linkable content with the segment `on-the-table` in the context of a channel `corporate` (which is apparently the root channel, since it consists of a single segment). The context and the content must fulfill the Blueprint's context relationship, otherwise the request is handled as invalid. Segment Path external references are resolved by querying the Solr search engine. The CAE Feeder must be running for up-to-date results.
Search Term	cm-searchterm:summer	Includes the content that contains the given search term (specified after the prefix `cm-searchterm:`). This resolver is typically used to resolve search landing pages. By default, contents of type `CMChannel` below the segment path `<root segment>/livecontext-search-landing-pages` are checked if their `keywords` search engine index field contains the term. Matching is case-insensitive by default and can be customized by using a different search engine field or field type. The value of the segment path which is used to identify the SLP channel is configured with the property `livecontext.slp.segmentPath`. Content type and search engine field can be configured with Spring properties `searchTermExternalReferenceResolver.contentType` and `searchTermExternalReferenceResolver.field`, respectively. The segment path is configured as relative path after the root segment. The configured segment path value must not start with a slash. Search term lookup is cached, by default for 60 seconds. You can configure the cache time in seconds with Spring property `cache.timeout-seconds.com.coremedia.livecontext.fragment.resolver.SearchTermExternalReferenceResolver` and the maximum number of cached search term lookups with `cache.capacities.com.coremedia.livecontext.fragment.resolver.SearchTermExternalReferenceResolver` (defaults to 10000). Search Term external references are resolved by querying the Solr search engine. The CAE Feeder must be running for up-to-date results.

Table 6.4. Supported usages of the externalRef attribute

Finding Handlers

You can control the behavior of the include tag by providing different sets of attributes. Depending on the used attributes, different handlers are invoked to generate the HTML.

The CoreMedia lc:include tag requests data from the CAE via HTTP. Each attribute value of the include tag is passed as path or matrix parameter to the FragmentPageHandler. In order to find the matching handler, the FragmentPageHandler class calls the include method of all fragment handler classes defined in the file livecontext-fragment.xml. The first handler that returns "true" generates the HTML. Example 6.1, “Default fragment handler order” shows the default order:

<util:list id="fragmentHandlers" value-type="com.coremedia.livecontext.fragment.FragmentHandler">
  <description>This list contains all handlers that are used for fragment calls.</description>
  <ref bean="externalRefFragmentHandler" />
  <ref bean="externalPageFragmentHandler" />
  <ref bean="productFragmentHandler" />
  <ref bean="categoryFragmentHandler" />
</util:list>

Example 6.1. Default fragment handler order

If the handlers are in the default order, then the table shows which handler is used depending on the attributes set. An "x" means that the attribute is set, a "-" means that the attribute is not allowed to be set and no entry means that it does not matter if something is set. For more details, have a look into the handler classes.

External Reference Page ID Category ID Product ID Used Handler

x ExternalRefFragmentHandler

ExternalPageFragmentHandler

ProductFragmentHandler

CategoryFragmentHandler

Table 6.5. Fragment handler usage

Note

The parameters category id and product id may be treated as technical id or as external id. It is recommended to work with external ids if possible. If the commerce system cannot pass external ids into the fragment parameters because only technical ids are available, this behaviour must be configured on the commerce adapter side. The property metadata.additional-metadata.allow-tech-ids=true has to be set for the commerce adapter, if you want to use technical ids in the fragment connector.

For customers using HCL Commerce the property metadata.additional-metadata.allow-tech-ids=true is set by default.

Fragment Request Context

In addition to the passed request parameters, a context is build by the registered ContextProvider implementations that are part of the commerce workspace. The context provider passes context information as header attributes to the CAE. For more details see Section 6.3, “Extending the Shop Context”.

CMS Error Handling

Since the CoreMedia include tag requests data from the CAE via HTTP, errors can occur. The error handling can be controlled by different parameters. If the com.coremedia.fragmentConnector.isDevelopment property (see Section 3.8, “Deploying the CoreMedia Fragment Connector”) is set to true, the include tag will embed occurring error messages as strings into the page output. You may not want to see such information on the live side, thus the flag can be set to false and all output will be suppressed (the errors are only visible in the log).

This behavior is sufficient for providing additional (possibly optional) information on a page, a banner or teaser, for instance. But if the requested content is the major content of a page, then it is not desirable to deliver a mainly empty page. In such a case the commerce system should be able to handle the error situation and answer in an appropriate form. That could be, for example, a 404 error page.

For this purpose the exposeErrors parameter was introduced to the include tag. If this parameter is set to true, the tag will expose any error that occurs during the interaction with the CMS. These errors are directly written to the response. Sending a response with an error status code (404, for instance) requires that still nothing has been written to the Response object. Therefore, this flag should only be set on the include tag if rendered early enough before any other response code has been set.

In the HCL Commerce reference workspace the usage of the exposeErrors parameter is demonstrated in the CommonJSToInclude.jspf template. The template is executed on every page request and renders, among other things, the HTML head section of a page. The first occurrence of the include tag is used to do the error handling.

Since the template is executed for all shop pages the flag must be set depending on the target page. If it's a content centered page (it has, for example, a cm parameter), then the parameter would be set to true, in case of a category or product detail page probably not.

exposeErrors="${not empty WCParam.externalRef && empty WCParam.productId && empty WCParam.categoryId}"

Another possibility to handle failed fragment requests is the usage of the httpStatusVar parameter. If this parameter is set, the include tag will write the HTTP status code of the fragment request into a JSP attribute/variable. You can then add JSP code to react on specific result codes and for example disable caching of this fragment in the commerce cache.

<lc:include ...
  httpStatusVar="status"/>
...
<c:if test="${not empty status && status >= 400}">
  ... // error handling
</c:if>

Search Results

Table Of Contents

Filter