ISML Tag - ISINCLUDE

Name

ISINCLUDE

Short Description

includes content of a template in another template

Table of Contents

Product Version

6.5

Product To Version

 

Statusfinal

1 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.

Note

The include concept enables web designers to reuse code and avoid unnecessary redundancy. Moreover, template inclusion allows web designers to maximize page cache usage by splitting up complex pages into parts that can be cached and parts which cannot be cached.

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.

Note

With Web Adapter includes as sketched above, it is the Web Adapter which assembles the servlet response. This is in contrast to local includes (using the template attribute), in which the application server assembles the servlet response. This has important implications for the caching behavior of pages, as discussed in more detail in here.

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.

Note

In special contexts, remote ISML includes always have to be resolved using a remote server include, since the servlet response is not delivered via the Web Adapter. This is the case e.g., with mail templates. In contexts like this, you have to force Intershop 7 to resolve remote ISML includes via a remote server include. Otherwise, the servlet response contains <WAINCLUDE> elements which the client cannot resolve. Use the <ISINCLUDE> attribute mode with value server to force a remote server include.

Note

Do not force Intershop 7 to use remote server includes in contexts which would allow for Web Adapter includes as well. Wherever possible, leave it up to Intershop 7 to decide which include mode to use.

2 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} )"]
>

3 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)#">

4 Attributes

4.1 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.

4.2 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.

4.3 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.

4.4 dictionary

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

Specifies the pipeline dictionary to be used.

4.5 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.

Note

This is only reasonable in very specific contexts, as discussed above.

4.6 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.

Note

The ID of this extension point node must be unique within the ISML template.

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

Reference - ISML Tags

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