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.
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
$content.keyVal.a will yield a value of
All Key/Value Fields possess two special properties:
|Provides direct access to the content object as a map.|
|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.,
map likewise surfaces additional general operations.
You may use either
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
|Retrieves the value associated with the given key. For example, |
|Returns an iterable of objects with separate |
|Creates or overwrites a key with the provided value. Accessible through the |
|Deletes the key-value pair. Accessible through the |
Note that because of the common way Velocity handles reading and writing syntaxes,
.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
So, an image with a metadata key-value pair of
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:*_*
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
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.
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:
Users inputting data into this Key/Value field will find a dropdown menu in the Key position contining
key3. Moreover, while
key1 is selected, the Value field will change from a text input to a dropdown containing