Dictionary

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.

{% create_dictionary [var, set, or assign]? variable = attributes %}

{% create_dictionary
var, set, or assign
 
Optional. Specify either "var", "set" or "assign" to change which scope this create_dictionary is stored on. "var" is the default behavior.
variable
=
attributes
 
Key:value pairs with unique keys. May use the variable arguments syntax.
%}

Examples

Create Settings Dictionary

Copy
{% capture settings %}
inputs: posts
number: 5
style: 'two-tone'
sortable: false
original_entity: entity
{% endcapture %}
{% create_dictionary settings = *settings %}
{{ settings | inspect }}

Related

{% 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.

{% 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.

{% 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.

{% 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.

{% set_dictionary variable = attributes %}

{% set_dictionary
variable
=
attributes
 
Key:value pairs with unique keys. May use the variable arguments syntax.
%}

Examples

Set Dictionary Properties

Copy
{% var inputname = 'inputs' %}
{% set_dictionary settings = &inputname:posts number:posts.size sortable:true %}

Related

{% create_dictionary %}

Creates a new editable dictionary with the given properties.

{% 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.

{% 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.

{% 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.

{% unset_dictionary variable attributes %}

{% unset_dictionary
variable
attributes
 
One or more values. May use the variable arguments syntax. The properties to be removed from the dictionary</p>
%}

Examples

Unset Dictionary Properties

Copy
{% capture unset_properties %}
{{inputname}}
number
sortable
{% endcapture %}
{% unset_dictionary settings *unset_properties style %}

Related

{% create_dictionary %}

Creates a new editable dictionary with the given properties.

{% 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.

{% 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.

{% 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.

{% copy_to_dictionary variable = copyable_objects new_only? %}

{% copy_to_dictionary
variable
 
The name of the variable to save the new dictionary to. If there is already a dictionary with this name, the new properties will be copied to the existing dictionary
=
copyable_objects
 
One or more values. May use the variable arguments syntax. One or more copyable objects (e.g., dictionaries) to use when creating the new dictionary
new_only
 
If true, only copy keys that do not already exist
%}

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

Copy Dictionary

Copy
{% 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 %}

Related

{% create_dictionary %}

Creates a new editable dictionary with the given properties.

{% 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.

{% 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

Create Settings Dictionary

Copy
{% capture settings %}
inputs: posts
number: 5
style: 'two-tone'
sortable: false
original_entity: entity
{% endcapture %}
{% create_dictionary settings = *settings %}
{{ settings | inspect }}

Unset Dictionary Properties

Copy
{% capture unset_properties %}
{{inputname}}
number
sortable
{% endcapture %}
{% unset_dictionary settings *unset_properties style %}

Set Dictionary Properties

Copy
{% var inputname = 'inputs' %}
{% set_dictionary settings = &inputname:posts number:posts.size sortable:true %}

List all keys and values for a dictionary field

Copy
<ul>
{% for key in entity.dictionary_field %} --equivalent to {% for key in entity.dictionary_field.keys %}
<li><strong>{{key}}</strong> = {{entity.dictionary_field.values[key]}}</li>
{% endfor %}
</ul>

Working with specific dictionary field properties

Copy
{% if entity.dictionary_field.is_valid %}
{% if entity.dictionary_field.custom_key_name %}
<p>Custom Key Value: {{entity.dictionary_field.custom_key_name}}</p>
{% endif %}
{% if entity.dictionary_field['custom_key_name2'] %}
<p>Custom Key Value 2: {{entity.dictionary_field['custom_key_name2']}}</p>
{% endif %}
{% endif %}

Copy Dictionary

Copy
{% 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 %}