ISML Tag - ISPLACEHOLDER

Name

ISPLACEHOLDER

Short Description

defines placeholders in a template

Table of Contents

Product Version

6.5

Product To Version

 

Statusfinal

1 Introduction

<ISPLACEHOLDER> is used to define spots in an ISML template where the Web Adapter post-processing will fill in content that was defined through matching <ISPLACEMENT> tags within the current request's HTML response. The connection between an <ISPLACEHOLDER> and the matching <ISPLACEMENT> entries is done through the <ISPLACEHOLDER> ID.

2 Syntax

<ISPLACEHOLDER
id = "( {String} | {ISML expression} )"
[ prepend = "( {String} | {ISML expression} )" ]
[ separator = "( {String} | {ISML expression} )" ]
[ append = "( {String} | {ISML expression} )" ]
[ preserveorder = "( true | false )" ]
[ removeduplicates = "( true | false )" ]
>

3 Example

Defining Meta Tags

This example aggregates all values that belong to <ISPLACEHOLDER> with /id="keywords"/ while removing duplicates. This way several components on a page can influence the content of the meta tag for keywords.
The respective <ISPLACEMENT> values are separated by commas. By specifying the prepend and append attributes this tag will only be generated if the corresponding <ISPLACEMENT> tags are present in the HTML. The order of the <ISPLACEMENT> values
is given by the order of the <ISPLACEMENT> tags within the HTML since no additional ordering algorithm is applied (preserveorder="false"). This can be done since there are no ordering dependencies between keywords.

<ISPLACEHOLDER id="keywords" prepend="#'<meta name="keywords" content="'#" separator=", " append="#'"/>'#" preserveorder="false"/>
<ISPLACEMENT placeholderid="keywords">foo</ISPLACEMENT>
<ISPLACEMENT placeholderid="keywords">bar</ISPLACEMENT>

Using the code above, the Web Adapter post-processing results in the following HTML:

<meta name="keywords" content="foo, bar"/>

Note

To use double quotes (") within the attribute values of prepend, separator, or append some
form of escaping is needed. The two options that work with ISML are as follows:

<ISPLACEHOLDER id="keywords" prepend="#'<meta name="keywords" content="'#" separator=", " append="#'"/>'#" preserveorder="false"/>
<ISPLACEHOLDER id="keywords" prepend="#"<meta name=\"keywords\" content=\""#" separator=", " append="#"\"/>"#" preserveorder="false"/>

In contrast to this, the following example will not work:

<ISPLACEHOLDER id="keywords" prepend="<meta name=\"keywords\" content=\"" separator=", " append="\"/>" preserveorder="false"/>

Defining JavaScript References

The following example illustrates the usage of <ISPLACEHOLDER> to define a spot within the HTML result where the aggregated JavaScript references (content of the <ISPLACEMENT> tags with placeholderid="JS") will be inserted.
When inserting the values, duplicates will be removed and the order of the JavaScript references will be preserved. By specifying the prepend, separator and append attributes the required HTML syntax for the JavaScript references is generated for each <ISPLACEMENT> value while the <ISPLACEMENT> tag only provides the path to the JavaScript reference:

<ISPLACEHOLDER id="JS" prepend="#'<script type="text/javascript" src="'#" separator="#'">
</script><script type="text/javascript" src="'#" append="#'"></script>'#" />
<ISPLACEMENT placeholderid="JS">1.js</ISPLACEMENT>
<ISPLACEMENT placeholderid="JS">2.js</ISPLACEMENT>

Alternatively, you could reach the same result without using the prepend, separator, and append attributes if the <ISPLACEMENT> values already include the complete markup for a JavaScript reference:

<ISPLACEHOLDER id="JS">
<ISPLACEMENT placeholderid="JS"><script type="text/javascript" src="1.js"></script></ISPLACEMENT>
<ISPLACEMENT placeholderid="JS"><script type="text/javascript" src="2.js"></script></ISPLACEMENT>

The result after the post-processing is:

<script type="text/javascript" src="1.js"></script>
<script type="text/javascript" src="2.js"></script>

4 Attributes

4.1 id

This attribute is required.

id = String | ISML expression

This attribute specifies the ID of the placeholder. Here the Web Adapter's postprocessing will insert only the content of <ISPLACEMENT> tags that refer to this ID with their respective placeholderid.

4.2 prepend

This attribute is optional.

prepend = string | ISML expression

If defined, the prepend value will be inserted in the HTML markup where the <ISPLACEHOLDER> is defined. After this, the values of the respective <ISPLACEMENT> tags are inserted.

4.3 separator

This attribute is optional.

separator = string | ISML expression

If defined, the separator value will be used to separate the values of the respective <ISPLACEMENT> tags.

4.4 append

This attribute is optional.

append = string | ISML expression

If defined, the append value will be inserted in the HTML markup after the values of the respective <ISPLACEMENT> tags are inserted.

4.5 preserveorder

This attribute is optional.

preserveorder = true | false

The default value is true. This attribute determines if a special ordering algorithm should be applied to the list of aggregated <ISPLACEMENT> values.
This is needed amongst others to keep the right order for loading dependencies of JavaScript or CSS files. In addition, this algorithm removes duplicates too.
For the ordering algorithm to work it is required that the <ISPLACEMENT> tags are grouped by their page/component/template instance. If the application of the ordering algorithm is not needed (e.g for meta tag values) it can be disabled by specifying preserveorder="false".

4.6 removeduplicates

This attribute is optional.

removeduplicates = true | false

The default value is true. With this attribute the aggregation of the <ISPLACEMENT> values can be influenced in such a way that duplications will be omitted. removeduplicates is not needed in combination with preserveorder="true" since the ordering algorithm already removes duplicates. This attribute is useful if the ordering is not needed but duplicates should be
removed e.g. for keywords.

Note

For the removal of duplicates to work the contents of the individual <ISPLACEMENT> tags have to be exactly the same because the Web Adapter performs only a simple text comparison.

The following example shows two JavaScript references that are semantically duplicates but would not be handled as such since the plain text comparison yields unequal values.

<script type="text/javascript" src="shopfunctions.js"></script>
<script src="shopfunctions.js" type="text/javascript"></script>

To avoid this kind of problems, you may prefer the first of the JavaScript reference examples (see Defining JavaScript References) where only the real references are defined by the <ISPLACEMENT> tags and the rest is handled by the prepend, append, and separator values.

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