Dictionary
{{ dictionary }}
Object containing a list of key-value pairs where the keys are unique.
| Name |
Type |
Description |
| is_valid |
Boolean |
True if there is at least one key-value pair |
| value |
String |
The json representation of the values. For dictionary fields you do not typically care about this - use values instead |
| editable |
Boolean |
True if properties can be added or removed from this dictionary. This will only be true if the dictionary was created using the {% create_dictionary %} method |
| keys |
list |
A list of strings containing all of the keys in the dictionary |
| values |
object |
An object containing all of the keys and values of the dictionary |
| count |
Integer |
The number of key-value pairs in the dictionary |
| field_id |
String |
The identifier for this field |
| label |
String |
The label for this field |
| output |
String |
The JSON representation of the values. May include additional markup in the editor preview to make it easier to edit content |
Individual dictionary values may be accessed using the {{ dictionary.keyName }}, {{ dictionary['keyName'] }}, {{ dictionary.values.keyName }}, or dictionary.values['keyName'] syntax.
You may also treat this object as a list containing all of the keys which may be iterated using a {% for %} loop. For more details, see the examples below:
{% create_dictionary %}
Creates a new editable dictionary with the given properties.
Examples
{% capture settings %}
inputs: posts
number: 5
style: 'two-tone'
sortable: false
original_entity: entity
{% endcapture %}
{% create_dictionary settings = *settings %}
{{ settings | inspect }}
{% set_dictionary %}
Sets properties on an editable dictionary object. If the dictionary does not exist it will be created and stored on the current scope. If the dictionary exists but is not editable this will throw an error.
Examples
{% var inputname = 'inputs' %}
{% set_dictionary settings = &inputname:posts number:posts.size sortable:true %}
{% unset_dictionary %}
Removes properties from an editable dictionary object. If the dictionary does not exist an empty one will be created and stored on the current scope. If the dictionary exists but is not editable this will throw an error.
Examples
{% capture unset_properties %}
{{inputname}}
number
sortable
{% endcapture %}
{% unset_dictionary settings *unset_properties style %}
{% copy_to_dictionary %}
Copies properties from one or more copyable objects (eg: dictionaries) into an editable dictionary. If the dictionary is not editable this will throw an error. If the dictionary does not exist then one will be created and saved on the current scope.
The following objects are copyable and can be used as arguments in the {% copy_to_dictionary %} method:
- dictionary will copy all of the dictionary properties from one dictionary to another
- labels will copy all of the key-value pairs from the labels field to the dictionary. If the labels field contains duplicate keys then only one of the values will be copied for that key.
- profile will copy all of the profile settings to the new dictionary
- datastore_item will copy all of the datastore fields to the new dictionary, along with the datastore item name (as a text object), title (as a text object), and folder (as a folder object) if it is in a folder
- form_submit will copy all of the form submission values (as their respective object types) to the new dictionary
- client will copy all of the client properties as strings to the new dictionary
- cookies will copy all of the cookies as strings to the new dictionary
- request.headers will copy all of the request headers as strings to the new dictionary
- client_permissions will copy all of the permissions (as permission objects) that have been specified for the client to the new dictionary - including both allowed and denied permissions
- post_params will copy all of the post parameters from the request to the new dictionary. Parameter values will either be strings or arrays (if the request had multiple post parameters with the same name).
- query_params will copy all of the query parameters (as strings) from the request to the new dictionary.
- session will copy all of the session properties as strings to the new dictionary
- site will copy all of the settings (as their respective object types) from the site to the new dictionary
Examples
{% create_dictionary pagination = limit:5 page:2 %}
{% create_dictionary sorting = sort_by:"post_date" sort_direction: "desc" %}
{% comment %}This will create a new dictionary if it does not already exist. Any previous filters may be overwritten from request.post_params.{% endcomment %}
{% copy_to_dictionary filters = request.post_params pagination sorting %}
{% comment %}If you use the new_only instruction then previous filters will not be overwritten.{% endcomment %}
{% create_dictionary filters = blog:entity.blog_main tag:entity.tag_filter %}
{% copy_to_dictionary filters = pagination sorting request.post_params new_only %}
Examples
{% capture settings %}
inputs: posts
number: 5
style: 'two-tone'
sortable: false
original_entity: entity
{% endcapture %}
{% create_dictionary settings = *settings %}
{{ settings | inspect }}
{% capture unset_properties %}
{{inputname}}
number
sortable
{% endcapture %}
{% unset_dictionary settings *unset_properties style %}
{% var inputname = 'inputs' %}
{% set_dictionary settings = &inputname:posts number:posts.size sortable:true %}
{% for key in entity.dictionary_field %} --equivalent to {% for key in entity.dictionary_field.keys %}
- {{key}} = {{entity.dictionary_field.values[key]}}
{% endfor %}
{% if entity.dictionary_field.is_valid %}
{% if entity.dictionary_field.custom_key_name %}
Custom Key Value: {{entity.dictionary_field.custom_key_name}}
{% endif %}
{% if entity.dictionary_field['custom_key_name2'] %}
Custom Key Value 2: {{entity.dictionary_field['custom_key_name2']}}
{% endif %}
{% endif %}
{% create_dictionary pagination = limit:5 page:2 %}
{% create_dictionary sorting = sort_by:"post_date" sort_direction: "desc" %}
{% comment %}This will create a new dictionary if it does not already exist. Any previous filters may be overwritten from request.post_params.{% endcomment %}
{% copy_to_dictionary filters = request.post_params pagination sorting %}
{% comment %}If you use the new_only instruction then previous filters will not be overwritten.{% endcomment %}
{% create_dictionary filters = blog:entity.blog_main tag:entity.tag_filter %}
{% copy_to_dictionary filters = pagination sorting request.post_params new_only %}