Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

This course is the most refreshing take on teaching design that I've come across.

β€” MikaΓ«l SΓ©vigny, Developer

Dictionary Fieldtype

Give your users a list of options to choose from. Similar to the Select field, but allows you to read options from YAML or JSON files, or even hit external APIs.

Dictionary Fieldtype UI
The Dictionary Fieldtype in action!

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>
@foreach ($past_vacations as $vacation)
<li>{{ $vacation['emoji'] }} {{ $vacation['name'] }}</li>
@endforeach
</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
emojis: true # Whether flag emojis are in the labels. They're on by default.
countries:
- USA
- AUS
{{ countries }}
{{ emoji }} {{ name }}, {{ iso2 }}, {{ iso3 }}, {{ region }}, {{ subregion }}
{{ /countries }}
@foreach ($countries as $country)
{{ $country['emoji'] }} {{ $country['name'] }}, {{ $country['iso2'] }}, {{ $country['iso3'] }}, {{ $country['region'] }}, {{ $country['subregion'] }}
@endforeach
πŸ‡ΊπŸ‡Έ 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 }}
@foreach ($timezones as $timezone)
{{ $timezone['name'] }} {{ $timezone['offset'] }}
@endforeach
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 }}
@foreach ($currencies as $currency)
{{ $currency['name'] }}, {{ $currency['code'] }}, {{ $currency['symbol'] }}, {{ $currency['decimals'] }}
@endforeach
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

dictionary

array

Configure the dictionary to be used. You may also define any config values which should be passed along to the dictionary. The dictionary option accepts both string & array values:

# When it's a dictionary without any config fields...
dictionarycountries
 
# When it's a dictionary with config fields...
dictionary:
typecountries
regionEurope

placeholder

string

Set the non-selectable placeholder text. Default: none.

default

string

Set the default option key. Default: none.

max_items

integer

Cap the number of selections. Setting this to 1 will change the UI. Default: null (unlimited).

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →