Using the Dictionary fieldtype in your Statamic front end forms
The Dictionary is a superb fieldtype in Statamic that can provide data-based single and multi select fields for your users: and out of the box includes Dictionaries like Countries, Locales and Timezones.
You can also create your own Dictionaries too, allowing you to create dynamic lists based on your own app's data: maybe it is from models in a Laravel app, or perhaps querying Statamic's content, or even getting data from an API.
The secret (that is not even a secret, but just sometimes forgotten) is that the Dictionary fieldtype can also work with your site's front end forms - in other words, Forms built via Blueprints in the Statamic CP.
So let’s take a quick look at the Dictionary fieldtype, and then spend some time making our own Dictionary, and also including our Dictionary's data within the email that gets sent when a Form Submission is created.
The Dictionary fieldtype is a hidden gem within Statamic, and can offer such a rich experience for your users, whether that is in the CP or on the front end.
Creating your own Dictionary
As always, you just need to ask nicely:
1php please make:dictionaryYou’ll be prompted for a name - in the video, I made a Dictionary called Entries, and will use that in this post too.
This will create the Dictionary within your app - app/Dictionaries/Entries.php for this example.
Label and value keys
Depending on where your data comes from, your label and value keys may be something other than label and value properties.
The generated code will give you two protected definitions, one for $labelKey and one for $valueKey - these are used to tell the Dictionary code what properties of each item to use for the label and value respectively.
1protected string $valueKey = 'abbr';2protected string $labelKey = 'name';In this example, the value is coming from the abbr property of an item, and the label from the name property. If you don’t need to re-map these, you can remove them from your Dictionary, and use the label and value defaults.
Adding items to the Dictionary
These can come from anywhere you want - maybe an API, maybe another part of your app, or even querying Statamic’s data.
I’ve used this example in a real-world app: the form on the frontend needed a dropdown where the user can select from a list of Jobs that are available - and these existed in the Jobs Collection as Entries.
While you could create a Select in your Form Blueprint, and manually include items to pick from, creating a Dictionary meant that when a new Job is added, the frontend form updates too - truly awesome and time saving.
The getItems() method returns an array of items - and each item can include whatever data you’re wanting. Check out the source code for Statamic’s included Dictionaries for some great examples.
In the video, I get a list of Entries from the Pages collection:
1return Entry::query() 2 ->where('collection', 'pages') 3 ->where('published', true) 4 ->get() 5 ->map(function (\Statamic\Entries\Entry $entry) { 6 return [ 7 'label' => $entry->title, 8 'value' => $entry->id, 9 'author' => $entry->author?->name ?? '',10 ];11 })12 ->toArray();Here we are getting the Title, ID and Author Name (if it exists) from the Entries in our Pages Collection.
These will be output in a Select field when we use our Entries Dictionary, and can be used either in the CP or on a front end Form. And yeah, bad example for CP usage: you could use the Entries fieldtype. But still, a good example for front end Forms.
Using the output in a Form Submission email
When a Dictionary fieldtype is submitted, we can access the Dictionary itself and get all of the information about the item.
By default, it will output the value. In our example that will be the Entry ID - a big UUID that is not really very user friendly to see.
Side note too… examples here are with Blade.
1<!-- Outputs a UUID, our Dictionary's "value" -->2<strong>{{ $item['display'] }}:</strong> {{ $item['value'] }}<br>But we can also get the label - the internal Value knows exactly what to do:
1<!-- Outputs the Entry Title, our Dictionary's "label" -->2<strong>{{ $item['display'] }}:</strong> {{ $item['value']->label() }}<br>And, we can also get the Dictionary Item too, so that we can access other properties, like the author:
1@php2$dictionaryItem = $item['value']->fieldtype()->dictionary()->get($item['value']->raw());3@endphp4<strong>{{ $item['display'] }}:</strong> {{ $item['value']->label() }}<br>5Author: {{ $dictionaryItem->extra()['author'] }}This will get the Item from the Dictionary, and using the Item’s extra() method, we then get access to all of the Item’s data as an array - so can simply get the author property.
And if you want the whole markdown.blade.php file in a copy-paste format from the video, check out:
1<x-mail::message> 2# New form submission 3 4Someone has taken the time to fill out a form on your website. Here are the details: 5 6<x-mail::panel> 7@foreach ($fields as $item) 8@if($item['fieldtype'] === 'dictionary') 9@php10$dictionaryItem = $item['value']->fieldtype()->dictionary()->get($item['value']->raw());11@endphp12<strong>{{ $item['display'] }}:</strong> {{ $item['value']->label() }}<br>13Author: {{ $dictionaryItem->extra()['author'] }}14@else15<strong>{{ $item['display'] }}:</strong> {{ $item['value'] }}<br>16@endif17@endforeach18</x-mail::panel>19</x-mail::message>Don’t forget: with your email templates like this, make sure you have no white spaces (i.e. indents). Yes, prettier with… but the renderer doesn’t like them.
As always, reading the docs is an essential place to start.
The Dictionary fieldtype, which is a core Statamic feature, unleashes a flexible ecosystem that allows us to create dynamic select fields for both the CP and front end forms. The best bit: all we have to do is write the Dictionary itself: Statamic already knows how to work with it.
No matter your data source, the Dictionary is one the most powerful yet incredibly subtle fieldtypes: and is definitely one of my favourites.