isinclude Element

Syntax

<isinclude 
  (template = template_name) | (url = url_path) //required. template or URL, but not both
  sf-toolkit = on | off //on is default
/>

Purpose

The template being included can be as complex as an entire page template, or as simple as a single line of HTML code.

Iterators used in the including template can be referenced from the included template. This is particularly useful if you want to use an included template in a loop statement. To avoid infinite template processing caused by self-includes, the maximum include depth is fixed to 10.

There are two possibilities when referencing an included template: The ISML code is processes or the ISML code isn't processed

ISML Code Is Processed

If the template is stored in a Salesforce B2C Commerce cartridge, you can use the template attribute to specify the path and the file name of the template to be included (the specified path has to be relative to your cartridge's root/templates/default language directory).

For example:

<isinclude template="reporting/ReportABTesting.isml">

• The path to the ISML template can only contain slashes. The template name can have the suffix ".isml" or not. If the suffix isn't present, it's appended automatically.

• The template path can be a fixed name or an expression, for example:

  <isinclude template="reporting/ReportABTesting.isml"> is a fixed name.

  <isinclude template="${pdict.Content.template}"> is an expression.

• The included template, contained in the Pipeline Dictionary, is determined by the template attribute of the Content object inside of the Pipeline Dictionary.
• The maximum include depth for template includes <isinclude template=""> is 10.

  This is necessary to protect template processing from recursive includes. If the include depth is reached or exceeded, an error is logged and templates of a higher include depth are omitted. This is because local includes are processed by the application server itself.

Example:

The following example shows a standard include of a template. The template blueBar.isml file could be used in a template to show a menu bar on the storefront pages.

This menu bar gives the customer access to different storefront functionality, such as a basket or the search mask. Using <isinclude> this way implements server-side frames that give you the full functionality of frames without the caveats of client-side frames due to incompatibilities between different browsers.

<isinclude template="inc/blueBar">

This example shows a standard include where the included template references an iterator of the including template:

<isloop iterator = "${pdict.Basket.product}" var="product">
<isinclude template = "inc/banner">
</isloop>
...
<!-- code of the included template -->

ISML Code Isn't Processed

The second possibility is to reference a remote URL that is located on another server accessible via an HTTP or HTTPS connection. In this case, use the URL attribute to specify a valid URL. Using the URL attribute directs B2C Commerce eCommerce to open an HTTP(S) connection to the specified remote system during run time, and to add the result of this HTTP(S) request to the template. Remote templates are particularly useful if you want to avoid client-side frames in HTML or when combining data in one template that comes from multiple servers.

The included URL can have a different caching policy. This lets you, for example, embed a dynamic snippet of HTML, which isn't cached, into a completely cached surrounding page. Conversely, a fully cached snippet can be embedded into a fully dynamic and uncached page.

for example:

<isinclude url="${URLUtils.url('Page-Include','cid', 'COOKIE_TEST')}">

• Use the URLUtils helper API class to construct a valid URL string.
• The maximum include depth for recursive URL includes <isinclude url=""> is 16.
• This is part of the B2C Commerce Web Server configuration, because remote includes are sent back to the Web Adapter, which performs another call to the application server. If the maximum include depth is reached, the B2C Commerce Web Server logs an error and cancels further request processing.

Example:

This example shows an include that combines data into one template. In this case, <isinclude> triggers another pipeline to show hot deals on the storefront entry page. The call is executed after the Webserver processes the initial request. Therefore, data in the Pipeline Dictionary is no longer available.

<isinclude url="${URLUtils.url('BrowseCatalog-Hotdeals',
'catalogCategoryID','Storefront')}">

This example illustrates dynamic template selection. The name of the referenced template is built during run time.

<isinclude template = "${'ProductTemplates/Template' + pdict.product.templateNumber}">

Suppressing the DwMarker Tag for Internet Explorer

If you have enabled the Storefront Toolkit, the content of every <isinclude> tag is surrounded by a dwMarker tag. Under some circumstances, the dwMarker tag causes Internet Explorer to change into Quirks mode.

For example:

<!-- dwMarker="linclude" dwTemplateTitle="/default/test/customassets.isml (SiteGenesis Storefront cartridge)" dwTemplateURL="http://localhost:60606/target=/c/sitegenesis_storefront_richUI/t/default/test/customassets.isml" -->
<!DOCTYPE html>

<isinclude template="test/customassets" sf-toolkit="off"/>

This suppresses the dwMarker tag around the content produced by test/customassets.isml. The new attribute is only supported by local includes. However, remote includes don't support this attribute.