Connector for SAP Commerce Cloud Manual / Version 2406.1
Table Of Contents
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" %> <c:if test="${not empty param.content}"> <c:set var="lc_externalRef" value="cm-seosegment:${param.content}"/> </c:if> <lc:include storeId="${cmsSite.uid}" locale="${lc:toLocale(cmsSite.locale)}" productId="${product.code}" categoryId="${searchPageData.categoryCode}" placement="${placement}" view="${param.view}" externalRef="${lc_externalRef}" parameter="${param.parameter}" pageId="${cmsPage.uid}"/>
All parameters are described in the next two sections.
Include Tag Reference
The tag attributes have the following meaning:
Parameter | Description |
---|---|
|
These attributes are mandatory. They are used in the CAE to identify the site that provides the requested fragment. |
|
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. |
|
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 |
|
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. |
|
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 |
|
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: |
|
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 |
|
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
|
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
|
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 |
Table 5.2. 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 |
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 |
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 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
Content type and search engine field can be configured with Spring properties
Search term lookup is cached, by default for 60 seconds. You can configure the cache
time in seconds with Spring property
Search Term external references are resolved by querying the Solr search engine. The CAE Feeder must be running for up-to-date results. |
Table 5.3. 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 5.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 5.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
| ||||
| x | - | - |
ExternalPageFragmentHandler
| |
| x |
ProductFragmentHandler
| |||
| x | - |
CategoryFragmentHandler
|
Table 5.4. 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.
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 5.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.3, “Configuring 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 Hybris workspace archive the usage of the exposeErrors
parameter is demonstrated in the main.tag
JSP. 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 param.content && empty product.code && empty searchPageData.categoryCode}"
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>