CSFFormatTemplate

For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.

Use the CSFFormatTemplate 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.

Intended use: Content Selection pipeline, Format stage.

Values Read

The CSFFormatTemplate pipeline component reads the following values from the indicated dictionaries.

Key	Dictionary	Description
_content.item_id	Order	The identifier for the various content items.
_winners	Order	Optional. 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.
_winnerindexes	Order	Optional. 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.
_content.values	Order	Optional. 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.
_content.template	Order	Optional. The name of a template in the Templates dictionary. Either this value or the CSFFormatTemplate entry in the Order dictionary must be specified.
_content.*	Order	Optional. A reference to the ContentList object. Multiple values are read. See the Remarks section below.
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.
<arbitrary entry>	Context	Optional. Any arbitrary property from the Context dictionary can be a source for a substituted value in a template.

Values Written

The CSFFormatTemplate pipeline 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

Other Resources

CSFLoadAdvertisements

CSFLoadDiscounts