Introduction

The <ISINCLUDE> tag directs Intershop 7 to include the contents of one template inside another. The template being included can be as complex as an entire template, or as simple as a single line of HTML code.

There are two ways of referencing templates for inclusion:

1. local include
   To reference local templates for inclusion, use either the template or the templatesDirectory attribute.
   template can be used to specify the path and the file name of a single template to be included. The specified path has to be relative to your template's root directory.

   • Example:

     <ISINCLUDE template="default/Template2.isml">

     templatesDirectory can be used to specify a path to a directory with templates to be included. All templates residing in the given directory will be included sorted by name.

   • Example:

     <isinclude templatesDirectory="product/editor/generalTab"/>

     Local includes are resolved by the application server. The application server assembles the response out of the including and the included templates and returns the result to the Intershop 7 Web Adapter. Note that this also implies that the entire servlet response is cached (if possible), consisting of the including and the included templates.

2. remote include
   Content can also be included via a HTTP or HTTPS connection, this is called a remote ISML include. Use the URL attribute to specify a pipeline or a valid URL.
   The processing of remote ISML includes depends on the details of the pipeline or resource call. In the most common case, the remote ISML include triggers a pipeline request addressed to the same Intershop 7 cluster (using the same protocol and port) which has processed the original request for the template that contains the <ISINCLUDE> element. In the example below, the remote include triggers the execution of the MyPipeline-Start pipeline.

   <ISINCLUDE url="#URL(Action('MyPipeline-Start'))#">

   Initial processing of a template containing such an <ISINCLUDE> proceeds as follows:
   a. The application server converts the <ISINCLUDE> element into a corresponding <WAINCLUDE> element.
   This is why remote ISML includes like this are also referred to as remote Web Adapter includes, or WA-includes, for short. The syntax of a <WAINCLUDE> call reads as follows:

   <wainclude url = "..." [username = "..." password = "..."]>

   b. The application server returns the template content including the <WAINCLUDE> elements to the Web Adapter.
   c. The Web Adapter parses the returned content for <WAINCLUDE> elements.
   d. If the content te be produced by the called pipeline is already stored in the cache, the requested page is retrieved from the page cache. If not, the Web Adapter invokes the application server to execute the requested pipeline.
   e. The Web Adapter assembles the complete page and sends it to the client.

Remote ISML includes cannot be resolved using Web Adapter includes if one of the
following conditions applies:

• The remote ISML include targets a resource not located on the current Intershop 7 cluster.
• The remote ISML include has to be resolved using a protocol other than the protocol of original request (e.g., HTTPS instead of HTTP).

In contexts like this, the application server opens a HTTP or HTTPS connection in order to resolve the <ISINCLUDE> directly, a process also referred to as remote server include. Hence, similar to local includes, the servlet response is assembled by the application server, and not by the Web Adapter. By default, Intershop 7 automatically decides which method to use in order to resolve a remote ISML request: a Web Adapter include or a remote server include.

Syntax

<isinclude
template = "( {ISML template identifier} | {ISML expression} )" |
templatesDirectory = "(relative directory path)"
url = "( {URL} | {ISML expression} )"
[ username = "( {string constant} | {ISML expression} )" ]
[ password = "( {string constant} | {ISML expression} )" ]
[ mode = "( server | automatic )" ]
[ dictionary = "( {string constant} | {ISML expression} )" ]
[ extensionpoint = "( {string constant} | {ISML expression} )"]
>

Example

The following example shows a standard local include of a template:

<ISINCLUDE template="inc/blueBar">

A remote include triggering another pipeline to show hot deals on a storefront page might look like this:

<ISINCLUDE url="#URL(action('BrowseCatalog-Hotdeals'), Parameter('catalogCategoryID','Storefront'))#">

Dynamic template selection: The name of the referenced template is built during runtime.

<ISINCLUDE template = "#'ProductTemplates/Template'.(Product:TemplateNumber)#">

Attributes

template|templatesDirectory

One of this attributes is required.

template = "( {ISML template identifier} | {ISML expression} )"
templatesDirectory = "(relative directory path)"

Use template to specify the name and location of a template to be included. You can either hard code its name or use an ISML variable identifier.
Use templatesDirectory to specify a path to a directory containing multiple templates you want to include. The order in which templates are included depends on the name of the templates.

url

This attribute is required.
url = string | ISML expression

Specifies a URL for including a remote resource (e.g. a pipeline) via a hard-coded string or an ISML variable identifier.

username and password

These attributes are optional.
string constant | ISML expression
password = string constant | ISML expression

Use username and password in combination to provide HTTP authentication.
Both attributes are only relevant when the required attribute is a URL and the web server uses basic HTTP authentication.
The pipelet DetermineBasicAuthentication stores the HTTP username and password for the current pipeline call in the pipeline dictionary. When DetermineBasicAuthentication is used in a pipeline, remote templates that also reference the target template can refer to the pipeline variables HTTPUsername and HTTPPassword.

dictionary

This attribute is optional.
dictionary = string contant | ISML Expression

Specifies the pipeline dictionary to be used.

mode

mode = server | automatic
Setting the mode to automatic(default) leaves it up to Intershop 7 to decide which method to use in order to resolve a remote ISML include: Intershop 7 will use Web Adapter includes whenever possible, and remote server includes otherwise only, e.g. because the remote ISML include targets a resource or pipeline on a remote host. Setting the mode to server forces Intershop 7 to use a remote server include.

extensionpoint

extensionpoint = string contant | ISML Expression
ISML templates can define extension points by using the <ISINCLUDE> tag with the attribute extensionpoint.
The ISML template processor includes every ISML template which is registered in current execution contexts to this extension point. The extension model files reference such an extension point in an ISML template via template name and extension point identifier.

The process of creating ISML template extension points and appropriate template extensions is explained in the corresponding cookbook.