It is possible to create placeholders in the content configuration. The placeholder is replaced with a value provided from a source outside the configuration itself. If no outside value is provided, a default value specified in the placeholder is used.
A placeholder has the general syntax:
{<source>:<key>|<default>}
Placeholder configuration
The placeholders are configured in the content configuration. The fields in the placeholder configuration is as follows:
|
Name |
Description |
|---|---|
|
Source |
From which data source to resolve the key into a value, see below. |
|
Key |
The key field defines the key we use for the replacement, i.e., the placeholder is replaced with the value associated with <key> in the widget configuration. Key must contain only characters -, a-z, A-Z or 0-9. |
|
Default |
The <default> value kicks in if the <source>:<key> for some reason cannot be evaluated. A reason for this can be that the value for the given key is not found. The symbols { } ): | can not appear in default. |
|
Value |
The value associated with key or the default value. |
Placeholder values may come from different sources, currently the following:
From context parameters
When using source parameter, the placeholders are replaced with parameters provided as key/value pairs in the context object of the widget data requests. The syntax to specify such parameters in the request context.
"parameters": [{"key":"key1", "value":"somevalue"},{"key":"key2", "value":"somevalue"}]
From user profile
When using source user, the placeholders are replaced with values from the user profile. The placeholder is replaced with the highest weighted item in the user profile group given by the placeholder key.
From content profile
When using source content, the placeholders are replaced with values from the content profile. The placeholder is replaced with the highest weighted item in the content profile group given by the placeholder key.
From location
When using source location, the placeholders are replaced with values from the user's current location. The supported keys are country, region, city, company, metrocode, postalCode and isoRegion.
From device
When using source device, the placeholders are replaced with values from the user's current device. The supported keys are deviceType, browserOs, browser, and mobileBrand.
Fields with placeholders
Query
There can be multiple placeholders in the same query field. The String value for query will have special characters escaped to avoid AQL injection.
//From content configuration
"query": "query(title:\"{parameter:userquery|car}\")"
//From the widget data request
"context": "parameters":[{"key":"userquery","value":"sony"},{"key":"key2", "value":"somevalue"}]
//Result query when replacement is done
"query(title:\"sony\")"
//From content configuration
"query": "query(title:\"{parameter:userquery|car}\")"
//From the widget data request
"context": "parameters":[{"key":"somekey", "value":"somevalue"}]
//Result query with default value, since replacement was not possible
"query(title:\"car\")"
Filter
There can be multiple placeholders in the same filter field. The String value for filter will have special characters escaped to avoid AQL injection.
"filter": "filter(category:\"{parameter:productcategory|electronics}\")"
Reporting
The key or value in reporting can contain placeholders. The additional rules that apply to the value and key in reporting are described here.
"reporting": [{"key" : "category" , "value" : "{parameter:productcategory|none}" }, {"key" : "{parameter:id|categories}", "value" : "book" }]
SiteIds
In a recs content configuration, the siteIds field can contain placeholders. Note that a valid default site id must be provided for each placeholder.
"siteIds": ["{parameter:someSiteId|12345678910}", "{parameter:someOtherSiteId|12345678910}", "12345678911"]
Items
In a fixed content configuration, a top level item value can contain placeholders.
The placeholder will be replaced when it occurs as a top level value, as in:
items: [{"key1": "{parameter:value1|default1}"}]
The placeholder will not be replaced when it occurs deeper inside the item, as in
items: [{"key1": {"subkey1": "{parameter:value1|default1}"}}]
ItemDefaults
The field itemDefaults can contain placeholders as values, as in
itemDefaults: {"key1": "{parameter:value1|default1}"}