{{ dictionary }}

dictionary Summary

Field containing a list of key-value pairs

dictionary Properties

Field containing a list of key-value pairs.

Field Type Description
object_type string Will always be "dictionary".
is_valid boolean True if there is at least one key-value pair.
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 containing all of the keys in the dictionary.
values object An object containing the keys and values of the dictionary.
count integer The number of key-value pairs in the dictionary.
value string The json representation of the values. For dictionary fields you do not typically care about this - use values instead.
output string The json representation of the values.
output_in_list string Same as output.
field_id string The identifier for this field.

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:

Examples

List all keys and values for a dictionary field

Copy
    {% for key in entity.dictionary_field %} --equivalent to {% for key in entity.dictionary_field.keys %}
  • {{key}} = {{entity.dictionary_field.values[key]}}
  • {% endfor %}

Working with specific dictionary field properties

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

Methods

{% create_dictionary %}

Creates a new editable dictionary with the given properties

{% create_dictionary
[var|set|assign] new_variable_name
 
The variable name to save the dictionary to. The variable will be saved using the "var" behavior unless "set" or "assign" are specified.
=
attribute:value
 
Include one or more attributes to set as properties on the dictionary.
...
%}

You may also include reference variables as properties, which will be dereferenced to their property names before setting the dictionary properties.

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 }}

{% set_dictionary %}

Sets properties on an editable dictionary object. If the dictionary is not editable this will throw an error. If the dictionary does not exist it will be created and saved to the specified varaible using the "var" behavior.

{% set_dictionary
dictionary_variable
 
The variable that references the dictionary to set the properties on.
=
attribute:value
 
Include one or more attributes to set as properties on the dictionary.
...
%}

You may also include reference variables as properties, which will be dereferenced to their property names before setting the dictionary properties.

Set Dictionary Properties

Copy
{% 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 is not editable this will throw an error. If the dictionary does not exist an empty one will be created and saved to the specified varaible using the "var" behavior.

{% unset_dictionary
dictionary_variable
 
The variable that references the dictionary to remove the properties from.
property_name
 
Include one or more properties to remove
...
%}

Unset Dictionary Properties

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

{% copy_to_dictionary %}

Copies properties from one or more copyable objects (see below) to an editable dictionary object. If the dictionary is not editable this will throw an error. If the dictionary does not exist then one will be created and saved to the specified varaible using the "var" behavior.

{% copy_to_dictionary
dictionary_variable
 
The variable that references the dictionary to copy properties to.
=
copyable_object
 
Include one or more copyable objects to copy properties from
...
new_only
 
If specified existing properties will remain unchanged. If more than one copyable object has the same property name then the first property will be used. If new_only is not specified then the last property will be used.
%}

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
  • 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

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