[5.x] Dictionaries

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   
       /**
        * Returns a key/value array of options.
        *
        * @param string|null $search
        * @return array
        */
       public function options(?string $search = null): array
       {
           return $this->getItems()
               ->when($search ?? false, function ($collection) use ($search) {
                   return $collection->filter(fn ($item) => str_contains($item['name'], $search));
               })
              ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
               ->all();
       }
   
      /**
        * Returns a single option.
        *
        * @param string $key
        * @return string|array
        */
       public function get(string $key): string|array
       {
           return $this->getItems()->firstWhere('slug', $key);
       }
   
       private function getItems(): Collection
       {
           return collect([
               ['name' => 'January', 'slug' => 'january'],
               ['name' => 'February', 'slug' => 'february'],
               ['name' => 'March', 'slug' => 'march'],
               // ...
           ]);
       }    
   }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

       protected function fieldItems()
       {
           return [
               'region' => [
                   'display' => __('Region'),
                   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
                   'type' => 'select',
                   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
               ],
           ];
       }
   
       public function get(string $key): string|array
       {
           $region = $this->context['region'];
   
           // ...
       }

[ebeauchamps]

Hello. Can we relate 2 (or more) dictionnaries? ie a Country dictionnary and a Province dictionnary (1 country with "n" provinces...and 1 province with "n" regional divisions, like counties)?

[duncanmcclean]

Hello. Can we relate 2 (or more) dictionnaries? ie a Country dictionnary and a Province dictionnary (1 country with "n" provinces...and 1 province with "n" regional divisions, like counties)?

Not with this version, however, it may be something we add later down the line.

It'd be more complicated to do since the "province" field would need to depend on the value from the "country" field, which we don't currently have an easy way to do without combining the fields, which is another can of worms 😅.

[jackmcdade]

Just gave this a go – works great! Love it <3