isprint Element

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

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.

Time zone identifiers are case insensitive.

Example:

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.

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:

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.

Encoding is always done after formatting.

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.

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

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.

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

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 IdentifierDescriptionExample
MONEY_SHORTTwo digits following a decimal separator. No currency symbol.Input: 3333 Formatted string: "3,333.00"
MONEY_LONGTwo digits following a decimal separator. Leading currency symbol.Input: 3333 Formatted string: "$3,333.00"

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

Valid Style IdentifierDescriptionExample
INTEGERNo digits after decimal separator. No decimal separator.Input: 2200.1234 Formatted string: "2,200"
DECIMALExactly two digits after decimal separator.Input: 2200.1234 Formatted string: "2,200.12"

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

Valid Style IdentifierDescriptionExample
QUANTITY_SHORT0 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_LONG0 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 IdentifierDescriptionExample
DATE_SHORTDate without clock time in short format.Formatted string: "9/25/99"
DATE_LONGDate without clock time in long format.Formatted string: "SEP 25, 1999"
DATE_TIMEClock time.Formatted string: "7:55:55 PM"

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 TypeDefault Style
Money FormattingMONEY_LONG
Number FormattingDECIMAL
Quantity FormattingQUANTITY_SHORT
Date FormattingDATE_SHORT

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 ClassExample
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 a"
  • Formatted string: "12:08 PM"
  • Scheme: "K a, z"
  • Formatted string: "0:00 PM, PST"
  • Scheme: "yyyyy.MMMMM.dd GGG hh aaa"
  • Formatted string: "1996.July.10 AD 12:08 PM"

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

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

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

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

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

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

The default is "on".

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

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

string output: " 5.00 USD"

string output: "5.00 USD "

string output: "foo"

These examples show usage of the encoding attribute:

string output: ">new<"

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

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