isprint Element

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

Syntax

<isprint
   value    = output                           \\required
  (style    = style_ID) | (formatter = format) \\one required, but not both
   timezone = "SITE" | "INSTANCE" | "utc"
   padding  = padding_constant
   encoding = "on" | "off" | context         \\default is "on"         
/>
value = output

Allowed data type: expression only. String is not allowed

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

(style = style_ID) | (formatter = format)
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 = 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" | "INSTANCE" | "utc"
  • 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 = padding_constant

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 = "on" | "off" | context

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.

Note: 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.

Note: See the API documentation.

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
Note: 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.
Valid Style Identifier Description Example
MONEY_SHORT Two digits following a decimal separator. No currency symbol.

Input: 3333

Formatted string: "3,333.00"

MONEY_LONG Two digits following a decimal separator. Leading currency symbol.

Input: 3333

Formatted string: "$3,333.00"

Number Formatting

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

Valid Style Identifier Description Example
INTEGER No digits after decimal separator. No decimal separator.

Input: 2200.1234

Formatted string: "2,200"

DECIMAL Exactly two digits after decimal separator.

Input: 2200.1234

Formatted string: "2,200.12"

Quantity Formatting

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

Valid Style Identifier Description Example
QUANTITY_SHORT 0 to 3 digits after decimal separator. No quantity symbol.

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.

Valid Style Identifier Description Example
DATE_SHORT Date without clock time in short format. Formatted string: "9/25/99"
DATE_LONG Date without clock time in long format. Formatted string: "SEP 25, 1999"
DATE_TIME Clock time. Formatted string: "7:55:55 PM"

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.

Data Formatting Type Default Style
Money Formatting MONEY_LONG
Number Formatting DECIMAL
Quantity Formatting QUANTITY_SHORT
Date Formatting DATE_SHORT

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.

Standard Formatter Class Example
Money Formatting

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: "h:mm a"

Formatted string: "12:08 PM"

Scheme: "K:mm a, z"

Formatted string: "0:00 PM, PST"

Scheme: "yyyyy.MMMMM.dd GGG hh:mm aaa"

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

Placeholder Action
"0" Defines required placeholder
"#" Defines option placeholder
"*" Defines required symbol (for example, currency or weight)

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 stores the value Nokia 447X Pro 17" Monitor.

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

generated HTML code: "Nokia 447X Pro 17&quot; 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: "&gt;new&lt;"

<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 has the value Nokia 447X Pro 17" Monitor):

Tag in the template <isprint value="${pdict.product.price}">
Generated HTML code "Nokia 447X Pro 17&quot; Monitor"
Browser display Nokia 447X Pro 17" Monitor