Dictionary Fieldtype

Overview

At a glance, the Dictionary fieldtype is similar to the Select fieldtype. However, with the Dictionary fieldtype, options aren't manually defined in a field's config, but rather returned from a PHP class (called a "dictionary").

This can prove to be pretty powerful, since it means you can read options from YAML or JSON files, or even hit an external API. It also makes it easier to share common select options between projects.

Data Storage

Dictionary fields will store the "key" of the chosen option or options.

For example, a dictionary might have items such as:

'jan' => 'January',
'feb' => 'February',
'mar' => 'March',

Your saved data will be:

select: jan

Templating

Dictionary fields will return the "option data" returned by the dictionary's get method. The shape of this data differs between dictionaries and is outlined below.

For example, using the built-in Countries dictionary, your template might look like this:

past_vacations:
  - USA
  - AUS
  - CAN
  - DEU
  - GBR

<ul>
    {{ past_vacations }}
        <li>{{ emoji }} {{ name }}</li>
    {{ /past_vacations }}
</ul>

<ul>
    <li>🇺🇸 United States</li>
    <li>🇦🇺 Australia</li>
    <li>🇨🇦 Canada</li>
    <li>🇩🇪 Germany</li>
    <li>🇬🇧 United Kingdom</li>
</ul>

Available Dictionaries

Statamic includes a few dictionaries straight out of the box.

File

This allows you point to a file located in your resources/dictionaries directory to populate the options. The file can be json, yaml, or csv.

Each option array should have label and value keys at the minimum. Any additional keys will be available when templating.

You may redefine which keys are used for the labels and values by providing them to your fieldtype config. In the following example, name is the label and id is the value.

[
    {"name": "Apple", "id": "apple", "emoji": "🍎"},
    {"name": "Banana", "id": "banana", "emoji": "🍌"},
    {"name": "Cherry", "id": "cherry", "emoji": "🍒"},
    ...
]

-
  handle: fruit
  field:
    type: dictionary
    dictionary:
      type: file
      filename: fruit.json
      label: name  # optional, defaults to "label"
      value: id    # optional, defaults to "value"

You may provide enhanced labels using basic Antlers syntax. For example, to include the emoji before the fruit name, you can do this:

label: '{{ emoji }} {{ name }}'

Countries

This provides a list of countries with their ISO codes, region, subregion, and flag emoji.

-
  handle: countries
  field:
    type: dictionary
    dictionary:
      type: countries
      region: 'oceania' # Optionally filter the countries by a region.
                        # Supported options are: africa, americas, asia, europe, oceania, polar

countries:
  - USA
  - AUS

{{ countries }}
  {{ emoji }} {{ name }}, {{ iso2 }}, {{ iso3 }}, {{ region }}, {{ subregion }}
{{ /countries }}

🇺🇸 United States, US, USA, Americas, Northern America
🇦🇺 Australia, AU, AUS, Oceania, Australia and New Zealand

Timezones

This provides a list of timezones and their UTC offsets.

-
  handle: timezones
  field:
    type: dictionary
    dictionary:
      type: timezones

timezones:
  - America/New_York
  - Australia/Sydney

{{ timezones }}
  {{ name }} {{ offset }}
{{ /timezones }}

America/New_York -04:00
Australia/Sydney +10:00

Currencies

This provides a list of currencies, with their codes, symbols, and decimals.

-
  handle: currencies
  field:
    type: dictionary
    dictionary:
      type: currencies

currencies:
  - USD
  - HUF

{{ currencies }}
  {{ name }}, {{ code }}, {{ symbol }}, {{ decimals }}
{{ /currencies }}

US Dollar, USD, $, 2
Hungarian Forint, HUF, Ft, 0

Custom Dictionaries

In many cases, using the native File dictionary can be all you need for something custom. However, it's possible to create an entirely custom dictionary that could read from files, APIs, or whatever you can think of.

Find out how to create a custom dictionary

Options

# When it's a dictionary without any config fields...
dictionary: countries
 
# When it's a dictionary with config fields...
dictionary:
  type: countries
  region: Europe