isprint Element

<isprint> is used to format and encode data for output.

Syntax

<isprint
  value="${output}"
  style="STYLE_ID"
  timezone="SITE"
  padding=padding_constant
  encoding="on"
/>

value

Required

Allowed data type: expression only. String is not allowed

output is an expression that resolves to the text you want to output.

style

Required

You must include either style or formatter, but not both:

• style = STYLE_ID Allowed data type: string style specifies a style identifier. Instead of using the style parameter, you can alternatively define a formatter string with the formatter attribute.

formatter

Required

You must include either style or formatter, but not both:

• formatter = format Allowed data type: string or expression. formatter defines a formatting string to control how <isprint> outputs expression results. For information on building your own formatter string, refer to Formatting Expression Results (which follows). If formatter is used, style must be omitted.

timezone

- SITE lets you print time zones as specified for your site. Defined through the Business Manager via the Site Preferences module, Time Zone section.

This is the default. If the attribute or value isn't provided, the value for the site is used.

• INSTANCE lets you print time zones as specified for your instance. Defined through the Business Manager via the Global Preferences module, Instance Time Zone Section.
• utc lets you print the date values without time zone conversion. In the unique case of customer.birthday, the "utc" time zone reflects the time zone free nature of the date value type. User input for the date attribute is now always interpreted as UTC time in the Business Manager. This timezone value ensures that no time zone conversion occurs for date attributes that are supposed to have no time component. If you require time zone conversion, use the existing value type datetime instead.

You can specify a particular time zone used for printing dates. This attribute enables you to specify whether you want to print dates with the instance time zone, the site time zone or without time zone conversion.

Note Time zone identifiers are case insensitive.

Example:

<isprint value="${new Date()}" style="DATE_LONG" timezone="SITE">
<isprint value="${new Date()}" style="DATE_LONG" timezone="INSTANCE">
<isprint value="${customer.birthday}" style="DATE_SHORT" timezone="utc"/>

padding

Allowed data type: string or expression.

padding_constant is used only with mail templates, which are templates using plain rather than html type, to define field width and other spacing issues. For example, when printing a list of product names using a loop statement, you can define a constant field width for every element of the list. The value for padding can be any positive or negative number. The absolute value of padding_constant defines the field width. A positive value produces left-aligned output; a negative value produces right-aligned output. If the output string is greater than the field size, the output string is truncated at its right end.

encoding

Default value is on. With this attribute, you can explicitly switch automatic encoding on and off. Salesforce B2C Commerce supports encoding in HTML, XML and WML. Even if encoding is turned off, you an use the StringUtil API to encode individual strings.

A ${} script expression embedded directly into the HTML is similar to the <isprint/> tag with encoding on and default styles.

The context element enables you to encode data to avoid cross-site scripting attacks in areas such as HTML attributes, XML, JavaScript, and JSON. Each value maps to a method in the SecureEncoder Class.

context can be one of the following values:

• htmlcontent encodes a given input for use in a general context.
• htmlsinglequote encodes a given input for use in an HTML Attribute guarded by a single quote.
• htmldoublequote encodes a given input for use in an HTML Attribute guarded by a double quote.
• htmlunquote encodes a given input for use in an HTML Attribute left unguarded.
• jshtml encodes a given input for use in JavaScript inside an HTML context.
• jsattribute encodes a given input for use in JavaScript inside an HTML attribute.
• jsblock encodes a given input for use in JavaScript inside an HTML block.
• jssource encodes a given input for use in JavaScript inside a JavaScript source file.
• jsonvalue encodes a given input for use in a JSON Object Value to prevent escaping into a trusted context.
• uricomponent encodes a given input for use as a component of a URI.
• uristrict encodes a given input for use as a component of a URI.
• xmlcontent encodes a given input for use in a general XML context.
• xmlsinglequote encodes a given input for use in an XML attribute guarded by a single quote.
• xmldoublequote encodes a given input for use in an XML attribute guarded by a double quote.
• xmlcomment encodes a given input for use in an XML comments.

These are some examples:

<div id="
  <isprint encoding="htmldoublequote" value="${unsafeData}"/>
"></div>

<script type="text/javascript">
  var data="<isprint encoding="jsblock" value="${unsafeData}"/>";
</script>

var json = {"trusted_data" : <isprint encoding="jsvalue" value="${unsafeData}"/>};
return JSON.stringify(json);

Purpose

The <isprint> tag outputs the result of expressions and template variables. Even though it's possible to output expression results without <isprint>, you should always use it because it contributes to optimizing your template code.

The <isprint> tag also takes care of formatting and encoding output strings.

Note Encoding is always done after formatting.

Formatting Expression Results

If the result of an expression appears on an HTML page, you should first specify how it should be done. For example, a date can be formatted in different ways depending on the store's locale:

• 12 March 1999
• 12.03.1999
• 03/12/99

All formatters are additionally customized by regional settings.

Note Objects of classes other than Money, Date, Quantity and Number are not formatted and the result of formatting these objects isn't standardized.

Using Styles

Styles are pre-defined formatter strings, which are defined in standard formatter classes. You can specify a style via the style attribute of the <isprint> tag.

Money Formatting

This class is used to format the expression results of type Money. The following table shows valid styles.

Note Currency symbols are based on the Default Currency, which is set per site, and can be configured in Administration > Sites > Manage Sites > SiteGenesis - General.

Number Formatting

This class is used to format expression results of type Number. The following table lists the valid styles.

Quantity Formatting

This class is used to format expression results of type Quantity. The following table lists the valid styles.

• Input: 3333 kg
• Formatted string: "3,333"
• Input: 3333.1 kg
• Formatted string: "3,333.1"
• Input: 3333.1234 kg
• Formatted string: "3,333.123"

| | QUANTITY_LONG | 0 to 3 digits after decimal separator. Following quantity symbol. |

• Input: 3333 kg
• Formatted string: "3,333 kg"
• Input: 3333.1 kg
• Formatted string: "3,333.1 kg"
• Input: 3333.1234 kg
• Formatted string: "3,333.123 kg"

|

Date Formatting

This class is used to format expression results of type Date. The following table lists the valid styles.

Using the Default Style of a Formatter Class

The default style of a formatter class is used if nothing else has been specified by the user, neither a style, nor a user-defined formatter style. The following table lists the valid styles.

Specifying User-defined Formatter Strings

A formatter string is explicitly given by the user via the formatter attribute of <isprint>. For more information about valid placeholders, see the B2C Commerce Script API documentation. The following table provides examples of user-defined formatter strings.

• Scheme: "_ #,#00.0#"
• Input: 3
• Formatted string: "$ 03.00"
• Input: 3333.123
• Formatted string: "$ 3,333.12"

| | Number Formatting | | | Quantity Formatting |

• Scheme: "#,#00.0# _;(-#,#00.0# *)"
• Input: 3
• Formatted string: "03.0 kg"
• Input: 3333.333
• Formatted string: "3,333.33 kg"

| | Date Formatting |

• Scheme: "EEE, MMM d, 'yy"
• Formatted string: "Wed, July 10, '96"
• Scheme: "ha"
• Formatted string: "12:08 PM"
• Scheme: "Ka, z"
• Formatted string: "0:00 PM, PST"
• Scheme: "yyyyy.MMMMM.dd GGG hhaaa"
• Formatted string: "1996.July.10 AD 12:08 PM"

|

Example

In the following example, the number style, INTEGER is used for the value sitecount.

<isprint value=${pdict.SiteCount} style="INTEGER"/>

Using Formatters

User-defined formatters let you explicitly specify a format via the <isprint> formatter attribute. You build formatters with placeholders. For example, "* #,#00.0#", "EEE, MMM d" or "yy".

The following example uses the # placeholder, a page incrementer:

<isprint value="${pdict.pagingmodel.start+1}" formatter="#" />

The following example uses the placeholders "* #,#00.0#," which define how decimal places and commas are handled for a list generated by CustomAmount data.

<isprint value=${pdict.Custom.Amount} formatter= "* #,#00.0#"/>

Encoding Expression Results

It's possible to use national characters, such as Greek or Cyrillic letters, as well as mathematical symbols and any non-ASCII characters in HTML documents. To ensure that a web browser can interpret and show these characters correctly, they must be encoded using HTML representations. To do this, you must replace characters, such as "<," ">," or "&" with named character entities as defined in the HTML 4.0 standard or XHTML 1.0/1.1.

Expression output is automatically encoded if the expression is embedded directly in the template or used for an HTML attribute. This ensures that the site isn't subject to cross-site scripting attacks. If the expression is used in an ISML tag attribute, no encoding is applied. Use <isprint> for more granular control of the expression output especially if the result of the expression is a string that contains a special character.

See the example, which shows the exact string returned by <isprint> for a string containing a quote sign. The example assumes that the template variable product<name></name> stores the value Nokia 447X Pro 17" Monitor.

ISML code in template: <isprint value="${Product.name}">

generated HTML code: "Nokia 447X Pro 17" Monitor"

shown by the browser: Nokia 447X Pro 17 " Monitor

Example with Deactivation of Encoding

<isprint... encoding="off">

The default is "on".

Example

The first example demonstrates how to use <isprint> to output an expression that returns a string. The returned string is formatted as defined by either the default formatter (first sample), or by using a style (second sample), or by a user-defined formatter string (third sample).

<isprint value="${pdict.Basket.TotalGrossPrice}">
<isprint value="${pdict.Basket.TotalGrossPrice}" style="MONEY_SHORT">
<isprint value="${pdict.Basket.TotalGrossPrice}" formatter="* #00.0#">

The next set of examples show the usage of the padding attribute:

<isprint value="${pdict.product.price}" padding="-10">

string output: " 5.00 USD"

<isprint value="${pdict.product.price}" padding="+10">

string output: "5.00 USD "

<isprint value="#'foolish'#" padding="+3">

string output: "foo"

These examples show usage of the encoding attribute:

<isprint value="${'>new<'}" encoding="on">

string output: ">new<"

<isprint value="${'>new<'}" encoding="off">

string output: ">new<"

The following example shows a string containing quotation marks, and the corresponding string that is returned by the <isprint> tag (it's assumed that the template variable product<name></name> has the value Nokia 447X Pro 17" Monitor):