Personal Library

Guide - ISML Template Style Guide

Introduction

This document describes best practice conventions for development of templates for applications based on Intershop 7. It outlines standards that have been defined and implemented during development of solutions based on Intershop 7 that proved to be successful, helpful or desirable. Although following these standards is not always technically necessary, Intershop strongly recommends that all parts of Intershop, implementation partners and customers follow these standards to:

Increase the readability of the source code of ISML templates,
Reduce frictions in software development,
Allow for reusing code,
Make ISML templates compliant with the XHTML standard,
Simplify managing ISML templates by using a proper naming scheme.

Note

The rules below are not exhaustive.
For more discussion of these and related issues, see Reference - ISML Expressions and child pages and Reference - Object Path Expressions.

Template Rules and Conventions

ISML

Use lower-case tag names for standard tags.
Use mixed-case tag names for self defined ISML tags.
Avoid using JSP.
Business functionality should be implemented in pipelines, not in templates.
Always declare the scope at <ISSET>, prefer usage of scope="request".
Always declare parameters for <ISMODULE>, use lower-case parameter names, prefer usage of strict modules.

Every template for HTML pages must begin with:

<iscontent type="text/html" charset="UTF-8">

For pages that depend on the personalization group id, add personalized="true" to the <ISCONTENT> tag.
Use code compacting via:
```
<iscontent compact="true"/>
```
Enable caching of static templates via:
```
<iscache type="relative" hour="24"/>
```
Printouts must be done using <ISPRINT>. Expressions in # without an enclosing <ISPRINT> are not allowed because of the danger of cross-side scripting attacks. Switch type encoding="off" in the <ISPRINT> tag if you want special HTML characters to be kept.
Correct
```
User Comment: <isprint value="#GuestbookEntry:Comment#"/>
```
Wrong
```
User Comment: #GuestbookEntry:Comment#
```
Even with <ISCONTENT> defining UTF-8 as encoding, use only ASCII characters in an ISML file. For example, use ä instead of ä.

Prevent subtags in attributes since this prevents proper localization.

Correct

<ISMessageBox message="You have not selected any auctions.\u003cbr/\u003eUse the checkboxes to select the auctions, then click &quot;Cancel&quot; again.">

Wrong

<ISMessageBox message="You have not selected any auctions.<br/>Use the checkboxes to select the auctions, then click &quot;Cancel&quot; again.">

Try to write ISML templates in an XML conform way, e.g., treat ISML as a transformation, not a grammar. Do not mix ISML tags and HTML output tags, but keep them separated.

Correct

<isif condition="#ConfigurationParameterDefinition:Multiple eq 'true'#">
    <select class="select" name="ConfigurationParameter_#ConfigurationParameterDefinition:Name#" multiple="multiple">
<iselse>
    <select class="select" name="ConfigurationParameter_#ConfigurationParameterDefinition:Name#">
</isif>

Wrong

<select class="select" name="<isprint value="#'ConfigurationParameter_'.ConfigurationParameterDefinition:Name#">" 
    <isif condition="#ConfigurationParameterDefinition:Multiple eq 'true'#">multiple="multiple"</isif>>

HTML 5 Standard

The following guidelines are intended to make ISML templates compliant with the HTML standard.

Use the following <!DOCTYPE> definition:
```
<!DOCTYPE HTML>
```

Use the meta tag to declare the document encoding:

<meta http-equiv="Content-Type" content="text/html"; charset="UTF-8"/>

Lowercase tag names and attributes.
All attributes must have a value, also those that typically do not take values. For example, nowrap has to be replaced by nowrap="nowrap". Attributes which have to be replaced are: compact, checked, declare, readonly, disabled, selected, defer, ismap, nohref, noshade, nowrap, multiple, noresize.

Do not use proprietary attributes like width and height for tables. The most outer table of login pages, for example, must have the class "centeredTable", and this class is contained in the style sheet. Please note that there may be more templates containing an attribute height, which may also be changed in this way.

/* Setting height to 100% does not work for XHTML at least in Firefox */
.centeredTable
{
    margin: 25% auto;
}

body
{
    background-color: #FFFFFF;
    /* To avoid proprietary <body> attribute "topmargin", "leftmargin" */
    margin: 0px;
}

form
{
    /*To avoid space between tables in <form><table>…</table></form>*/
    margin-top: 0px;
    margin-bottom: 0px;
}

Attributes have to be included within double quotes.
All images must have an alt attribute (possibly empty).
Close all open tags according to XML conventions, like <input …/>, <img …/>, <meta …/>, <link …/>, <br/>.
Use nesting according to the XML standard.
Reserved characters must be replaced by their HTML codes:
- < equals <
- > equals >
- & equals &
- (and so on)
Enclose all url() and urlex() method calls in an <ISPRINT> tag to ensure that all '&' parameter separators are encoded to the XHTML conform '&':
```
<a href="<ISPRINT value="#URL(Action('Pipeline-StartNode'), Parameter('Param1', Value1))#">" class="...">Link</a>
```
Include CSS definition.
Define color, font, width .... and all visual appearance attributes only in the CSS file.

The resulting HTML page has to be well-formed, this means there must be a valid XML structure.

Correct

<form>
  <table>
    <tr>
    </tr>
  </table>
</form>

Wrong

<table>
  <form>
</table>
<table>
  </form>
</table>

Forms must not begin in a table.

Correct

<form>
  <table>
    <tr>
    </tr>
  </table>
</form>

Wrong

<table>
  <form>
    <tr>
    </tr>
  </form>
</table>

Note that the style must be part of the style sheet.

body
{
    background-color: #FFFFFF;
    /* To avoid proprietary <body> attribute "topmargin", "leftmargin" */
    margin: 0px;
}

form
{
    /*To avoid space between tables in <form><table>...</table></form>*/
    margin-top: 0px;
    margin-bottom: 0px;
}

Forms have to include the whole table content, not only singe rows.

Correct

<form>
  <table>
    <tr>
    </tr>
    <tr>
    </tr>
  </table>
</form>

Wrong

<table>
  <tr>
  </tr>
  <form>
    <tr>
    </tr>
  </form>
</table>

Input tags, e.g., buttons and hidden input fields, must be defined within a form and a surrounding td tag.
Submit buttons must be inside a form.

Use the FireFox plugin "HTML Tidy" to check valid templates.

Correct

 
<form>
  <table>
    <tr>
      <td>
        <input type="hidden" value="..."/>
      </td>
    </tr>
  </table>
</form>

Wrong

<table>
  <input type="hidden" value="..."/>
  <form>
    <tr>
       <td>
       </td>
    </tr>
  </form>
</table>

Use only valid values for IDs. See SelfHTML for a definition. The value of such an attribute must begin with a letter A-Z or a-z, the remaining string may contain letters A-Z or a-z, digits 0-9, separators (-), underlines (_), colons (:) and dots (.). Not allowed are special characters or whitespaces.

JavaScript

Try to avoid the use of JavaScript at all.
JavaScript should only be used for better usability but not to implement business logic.
Make sure all JavaScript parts set the accurate type.

Use a CDATA section to make it XHTML-compliant.

<script language="JavaScript" type="text/javascript">
/* <![CDATA[ */
// content of your Javascript goes here
/* ]]> */
</script>

Write general JavaScript functions rather than those functions applicable only for your purpose. For example, write a selectAll function that can handle different layers, forms and form elements.

Use only accurate JavaScript. Only use attributes that are available for your objects. For selectAll, do not use the checked attribute for hidden input fields.

<script language="JavaScript" type="text/javascript">
/* <![CDATA[ */
// Selects or deselects all elements of a specific form with a specific name
// (or part of the name), as well as enables and disables a layer with specified
// id's. It depends on the visibility of the select layer whether the form
// elements are selected or not.
// formName:               name of the form to handle
// partOfFormElementName:  part of the name of the form elements
// selectLayerID:          the layer that contains the 'Select All' link
// clearLayerID:           the layer that contains the 'Clear All' link
function selectAll(formName, partOfFormElementName, selectLayerID, clearLayerID)
{
    //alert(formName + ", " + partOfFormElementName + ", " + selectLayerID + ", " + clearLayerID);
    var formElements = document.forms\[formName\].elements;
    var select = true;

    if (document.getElementById(selectLayerID).style.display == "none")
    {
        select = false;
    }

    for (var i=0; i<formElements.length; i++)
    {
        if ((-1 != formElements\[i\].name.indexOf(partOfFormElementName)) &&
            (formElements\[i\].disabled == false) &&
            ((formElements\[i\].type == "checkbox") ||
             (formElements\[i\].type == "radio")))
        {
            formElements\[i\].checked = select;
        }
    }

    if (select)
    {
        document.getElementById(selectLayerID).style.display = "none";
        document.getElementById(clearLayerID).style.display = "block";
    }
    else
    {
        document.getElementById(selectLayerID).style.display = "block";
        document.getElementById(clearLayerID).style.display = "none";
    }
}
/* ]]> */
</script>

Do not use "this.form". Use "document.<Form Name>.".
Enable JavaScript Debugging for template development to get errors for invalid statements. In Internet Explorer, make sure Tools | Internet Options | Advanced | Disable Script Debugging is not checked. In FireFox, use FireBug.

Formatting Rules

Indention

Use tabs instead of spaces and do not convert tabs to spaces.
Spaces consume much more disk space and increase the number of transferred bytes between server and client dramatically.
Remove spaces and/or tabs at the end of lines.
Visualize the page structure by adding markers and comments to the source code for better readability.

Correctly indent for combination of ISML and HTML (except for setting form values):

Correct

<table>
  <tr>
    <td>
      <isif ...>
        <input ... value="Blubber"/>
      </isif>
    </td>
  </tr>
</table>
<table>
  <tr>
    <td>
      <input …value="<isif ...>Blubber</isif>"/>
    </td>
  </tr>
</table>

Wrong

<table>
  <tr>
    <td>
      <isif ...><input ... value="Blubber"/></isif>
    </td>
  </tr>
</table>
<table>
  <tr>
    <td>
      <input ... value="
        <isif ...>
          Blubber
        </isif>"/>
    </td>
  </tr>
</table>

Write comments for important blocks of code.
Use HTML comments for compiled HTML pages.
Use ISML comments for documenting the source for further development.
Use includes for easier modularization and reuse of small parts of a complex page.
Forms must have a name and the method has to be "post".

Do not surround button texts with spaces:

Correct

<input type="submit" name="apply" value="Apply" />

Wrong

<input type="submit" name="apply" value="    Apply    " />

Template Naming

This section shortly describes template naming conventions. All templates should start with the name of the persistent object that has its data edited or displayed. In the file system, templates are also grouped into sub-directories within the templates directory of a cartridge (e.g., under /staticfiles/cartridge/templates) according to these persistent objects (as shown in the sample directory structure of the buying site).

/en
/en/department
/en/awf
/en/user
/en/catalog
/en/category
/en/product

Intershop recommends the following naming scheme for templates:

Template Name	Description	Example
[ENFINITY: BusinessObjectName]List	This template is used whenever a list of business objects is to be displayed.	AWFList, DepartmentList, BuyingOrgList
New[ENFINITY: BusinessObjectName]	This template is used whenever a new business object is to be created.	NewAWF, NewDepartment, NewBuyingOrg
[ENFINITY: BusinessObjectName]	This template is used whenever the details of an existing business object are to be shown. It should be returned by the <PrepareUpdate> start node.	AWF, Department, BuyingOrg
[ENFINITY: BusinessObjectName][ENFINITY: AssociatedBusinessObjectName]List	This template is used whenever a list of associated business objects is to be displayed. This template corresponds to a tab in the detail view of a business object.	AWFSequenceList, DepartmentUserList, CostCenterAddressList, ProductBundledProductList
New[ENFINITY: BusinessObjectName][ENFINITY: AssociatedBusinessObjectName]	This template is used whenever details of an associated business object are to be displayed. Append the prefix New in case you are creating a new associated business object.	NewAWFSequence, NewDepartmentUser, NewCostCenterAddress, NewProductBundledProduct
[ENFINITY: BusinessObjectName]Select[ENFINITY: AssociatedBusinessObjectName]	Use this template name in case of multi-page selection wizards. [ENFINITY: BusinessObjectName] represents the business object for which associated businesses object or object relation is to be created. [ENFINITY: AssociatedBusinessObjectName] represents the associated business object to be selected.	DepartmentSelectUser, DepartmentSelectRole, ProductSelectCatalog, ProductSelectCategory
Browse[ENFINITY: BusinessObjectName]	Use this template to browse the content of a business object. The content can be divided into multiple lists (i.e. products and sub-categories of a catalog category).	BrowseCatalogCategory, BrowseDepartment

Web Form Handling

Each screen to create or update an entity should use a web form to collect all submitted form parameters. If the user entered a wrong input value or forgot to enter some mandatory input values, an error message must be displayed together with the entered data.

Use only the webform to display the entered data. Do not use individual form parameters.

Correct

<tr>
  <td class="fielditem2">Description:&#160;</td>
  <td class="table_detail">
    <textarea name="RoutingRule_ShortDescription" rows="5" cols="70" class="inputfield_en">
      <isif condition="#(RoutingRuleForm:ShortDescription:Value NE '')#">
        <isprint value="# RoutingRuleForm:ShortDescription:Value #">
      <iselse>
        <isprint value="#RRule:ShortDescription#">
      </isif>
    </textarea>
  </td>
</tr>

Wrong

<tr>
  <td class="fielditem2">Description:&#160;</td>
  <td class="table_detail">
    <textarea name="RoutingRule_ShortDescription" rows="5" cols="70" class="inputfield_en">
      <isif condition="#isDefined(RoutingRule_ShortDescription)#">
        <isprint value="#RoutingRule_ShortDescription#">
      <iselse>
        <isprint value="#RRule:ShortDescription#">
      </isif>
    </textarea>
  </td>
</tr>

Checklist

All ISML (HTML) templates contain the following first line:

<iscontent type="text/html" charset="UTF-8" compact="true">

Template name and location exist in application frame and login pages:

<!-- Template Name: #WorkingTemplate#.isml -->
<!-- Template Location: <Cartridge Name>/staticfiles/cartridge/templates/default -->

The most outer table of login pages must have the class "centeredTable", and this class is contained in the style sheet. Please note that there may be more templates containing an attribute height, which may also be changed in this way.
```
/* Setting height to 100% does not work for XHTML at least in Firefox */
.centeredTable
{
    margin: 25% auto;
}
```

The document type is set correctly in application frame and login pages.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Available values for attributes are: selected, readonly, checked, disabled, nowrap, noresize, compact, declare, defer, ismap, nohref, noshade, multiple. You may use the attached tool FixxHTMLTags.plto get hints about possible inaccurate places. It can be started like this:
```
\\jcc2\user\winperl\isccperl.cmd <name of the script, which must be stored locally> <path with the templates>
```
Values for attributes are written in lower case ( POST-> post).
There are no linefeeds in form values in case they are set with ISML <input ... value="<isif ...>Blubber</isif>"/>.
All proprietary attributes are removed. E.g., remove the attribute wrap(except in text area; don not know a replacement). You may search for the regular expression "[ENFINITY:^o]wrap" in all templates.
alt attribute is added for images (maybe empty).
Empty name attributes for images removed? You may search for "name=""" in all templates.
Indentation in all templates is fixed.
Trailing slashes for <br/> (search and replace), <meta .../>, <link .../>, <input .../>, <img .../> are added.
Make sure forms occur only in {{td}}s and surround tables <form><table></table></form>.
Make sure inputs are surrounded by {{td}}s.
Make sure the GlobalJavaScript.isml is included only in the application frame.
Make sure all JavaScript parts set the accurate type <script language="JavaScript" type="text/javascript">
Use only accurate JavaScript functions, e.g., selectAll(<Form Name>,<Element Name>,<Select Layer>,<Clear Layer>)(no space between parameters!
Create includes for tabs and use breadcrumb module for breadcrumbs.
Make sure submit buttons occur only in forms.
Make sure the Ids of form elements are valid.

Reference

Please also refer to the Reference - ISML Reference.

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.

Table of Contents

Introduction

Template Rules and Conventions

ISML

HTML 5 Standard

JavaScript

Formatting Rules

Indention

Template Naming

Web Form Handling

Checklist

Reference