FormatTemplate

Use this pipeline component to merge data from selected items and their associated templates to form formatted strings. These are usually HTML strings ready for display on the page. Items may come from the Context dictionary as well as the ContentList object in the Order dictionary.

Although this component appears as the FormatTemplate component in the Pipeline Editor, its ProgID is Commerce.CSFFormatTemplate.

Intended use: Content Selection pipeline, Format stage.

Configuration Values

None.

Values Read

The FormatTemplate component reads the following values from the indicated dictionaries.

Key	Dictionary	Description
_winnerindexes	Order	A SimpleList object containing the ContentList object positions of the winning content items. If this key is present, the _winners key should not be present. If both are present, only this key is used.
_winners	Order	A SimpleList object containing the values from the item_id key of the winning content items. If this entry is present, the _winnerindexes key should not be present. If both are present, only the _winners_indexes key is used.
_content	Order	A reference to the ContentList object. Multiple values are read. See the Remarks section below.
<arbitrary entry>	Context	Optional. Any arbitrary property from the Context dictionary can be a source for a substituted value in a template.
FormatTemplate	Order	Optional. If present, this key overrides the default format template associated with each content item being formatted. The value of this key can be: A string The string contains the key in the Templates dictionary of the Context dictionary. The value associated with that key is a Format Template dictionary. A reference A reference to a Format Template dictionary.
templates	Context	Optional. A dictionary that maps names to Format Template dictionaries. Normally, the templates key of a content item would contain a name used as a key to this dictionary, giving the proper Format Template dictionary.
ContextProfile	Context	Optional. A reference to the ContentSelector object that can be named as a source for the template substitutions performed by this component.
RedirectUrl	Context	Optional. A string containing the URL of the redirector script. Note that most templates require this key.
CacheName	Context	Optional. A string containing the name of the current content cache. Note that most templates require this key.

The FormatTemplate component reads the following values for each item in the ContentList object referred to by the _content key:

Key	Description
item_id	The identifier for the various content items.
<arbitrary fields>	A field in the ContentList object specified by a Template dictionary. Acts as the source of a value used in the template.
values	A dictionary derived from the creative_property and creative_property_values tables in the marketing database. The values in the dictionary are specific to the creative type.
template	The name of a template in the Templates dictionary. Either this value or the FormatTemplate entry in the Order dictionary must be specified.

All of these keys are optional with the exception of the item_id key.

Values Written

The FormatTemplate component writes the following values to the Order dictionary.

Key	Description
_formatted	A SimpleList object containing the formatted strings.

Remarks

A template is a string that contains substitution variables. Substitution variables can consist of letters, numbers, the underscore character, and are identified in the template string by the delimiters {% and %}. For example, {%Book_Title%} is a valid substitution variable. If for some reason you need to have a literal {% in your document, append an ampersand (&) to the sequence ({%&).

The information that replaces the substitution variables can come from several sources, including the Values dictionary in the ContentList object, the actual content item fields in the ContentList object, and from arbitrary properties in the ContentSelector object (CSO) or the Context dictionary. In addition, a default value can be supplied in the event that no value is found elsewhere. The source of the value, the default value, and how the value should be encoded, are all contained with the template string in a Format Template dictionary.

The Values dictionary is used to store variable properties of a particular type of content. For example, image ads and text ads are both ads, and should be in the same ContentList object so that they can compete with each other. But some of their properties are unique and do not apply to ads of the other type. This presents problems in the fixed schema supported by the ContentList object. The solution is a CLCOL_DISPATCH column (named Values) containing values that are references to dictionaries that contain unique keys and values. The keys and values in these dictionaries come from the creative_property and creative_property_values tables.

Format Template dictionaries are created by the LoadAdvertisements and LoadDiscounts objects from information in the marketing database. A Format Template dictionary contains a single template and information about the substitution variables in the template. It contains an entry named "text" and the value for that entry is the template string. For each substitution variable in that string, the Format Template dictionary contains three additional entries that provide the value source, the default value, and the encoding scheme for that variable. The names of these additional entries are formed by the name of the variable appended with one of the strings "_default", "_source", and "_encoding." The following table describes these additional dictionary entries.

Dictionary Entries	Description of Dictionary Entry Value
Text	The text of the template, which may include substitution variables. The other entries in the dictionary provide information about how values for the substitution variables are retrieved and formatted.
<variable>_default	A string that provides the default value, if any, for the substitution value. The default value is used if a value cannot be found in any of the specified sources.
<variable>_source	A number indicating sources for the value. The name of the variable is searched for in a variety of places, indicated by one of the following numbers: 1 Looks for a value in the content item. First, the Values dictionary in the ContentList object is used, if it is present. Next, the columns of the ContentList object are examined. 2 Uses an intrinsic value, if one matches. The only currently supported intrinsic value is "unique," which causes a unique number to be generated. 3 Looks for a value in the Context dictionary. First the ContextProfile entry (the CSO) in that dictionary is examined for a matching entry name, and then the Context dictionary is examined for a matching entry name. NULL or zero (0) Examines all of the above sources in the order shown, stopping when the first match is found. If no value can be found in the specified sources, the default value is used.
<variable>_encoding	A number indicating the type of encoding, if any, to apply to the value. The options are: NULL or zero No encoding. 1 Performs full URL-encoding. An example of when this encoding is required would be a ClickUrl entry passed to the redirector. 2 Limits encoding in which space characters are encoded as plus characters. As an example, this type of encoding is useful in would-be URLs that do not go through the redirector, such as image URLs.

The resulting strings are returned in a SimpleList object assigned to the _formatted key in the Order dictionary.

See Also

CSFLoadAdvertisements

CSFLoadDiscounts

All rights reserved.