Key/Value Fields provide a convenient way to add non-structured information to your content.
This information is handled using key-value pairs that are stored in the content as a map. Their contents can then be easily displayed on a Page or widget.
Usage
In the traditional interface, adding content to a Key/Value Field is as simple as specifying a key and a value in the field. The addition will be added to a list visible beneath it.
Accessing Key/Value Fields by velocity is straightforward: Each key becomes a property of the field. For example, if a field with a system name of keyVal includes the two key-value pairs of a=1 and b=2, calling $content.keyVal.a will yield a value of 1.
Properties
All Key/Value Fields possess two special properties:
| Property | Description |
|---|---|
map | Provides direct access to the content object as a map. |
keys | Provides a list of keys as an array. |
All keys may be accessed through the map object in similar fashion to the core object — e.g., $content.keyVal.map.a. The map likewise surfaces additional general operations.
You may use either map or keys as a valid key for a stored value, but said key will not be accessible directly from the field. That is, if you specify the pair map=treasure, you must access it through the map object, as $content.keyVal.map.map.
Methods
| Method | Description |
|---|---|
.get(key) | Retrieves the value associated with the given key. For example, $content.keyVal.get("a"), in the example throughout the above, would yield 1. This is functionally identical to calling keyVal.a, or keyVal["a"]. Accessible through both the field object and the map property — i.e., keyVal.map.get("a"). |
.entrySet() | Returns an iterable of objects with separate key and value properties, each representing a key-value pair. Accessible through both the field object and the map property. |
.put(key, value) | Creates or overwrites a key with the provided value. Accessible through the map property. Example: $content.keyVal.map.put('pitcher2', 'Nolan Ryan'). |
.remove(key) | Deletes the key-value pair. Accessible through the map property. Example: $content.keyVal.map.remove('pitcher2'). |
Note that because of the common way Velocity handles reading and writing syntaxes, .put() and .remove() operations will still print the current value, as though a .get() were called before assignment or deletion. While this can be useful for parsimony in certain cases, in some other cases it may yield output not intended for display.
If the key did not exist at the time of the call, this will result in a null value that can be hidden through the use of quiet reference notation, such as $!content.keyVal.map.put('v', 'v'). For a more consistent way to hide the operation's output, you can place this operation inside a temporary dummy value in a directive that will not display, such as the case shown below:
#set($dummy = $content.keyVal.map.remove('v'))
If the code appears in a context that will not be rendered, such as a Scripting API call, the above note can be disregarded.
Elasticsearch Mapping Considerations
Key/Value fields have a special mapping convention to simplify access via Lucene query.
+{ContentType}.{keyValFieldVar}.key_value:{key}_{value}
So, an image with a metadata key-value pair of height:800 could be retrieved by any of the following queries:
+Image.metaData.key_value:height_800
+Image.metaData.key_value:height_*
+Image.metaData.key_value:*_800
+Image.metaData.key_value:*_*
Example: Iterating
To display the complete contents of a Key/Value Field, loop through its map object.
#set($content = $dotcontent.find("$CONTENT_INODE"))
#foreach($mapEntry in $content.keyVal.map.entrySet())
$mapEntry.key : $mapEntry.value
#end
Whitelisting
As of version 22.05, dotCMS supports creating a whitelist of valid keys for a given Key/Value field, as well as pre-defined values for said keys.
While configuring the Key/Value field in the Content Type editor, simply set a key of whiteList and then its definition, using JSON syntax, in the corresponding value field.
Example
Let's say you want create a whitelist containing the following:
- One predefined key with two possible predefined values
- Two other predefined keys permitting arbitrary value entry
You might create this whitelist as follows:
| Key | Value |
|---|---|
whiteList | { "key1":["val1", "val2"], "key2":[], "key3":[] } |
Users inputting data into this Key/Value field will find a dropdown menu in the Key position contining key1, key2, and key3. Moreover, while key1 is selected, the Value field will change from a text input to a dropdown containing val1 and val2.
