CSFFormatTemplate
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:
|
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:
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:
|
The resulting strings are returned in a SimpleList object assigned to the _formatted key in the Order dictionary.