[5.x] Dictionary tag

[ryanmitchell]

This PR adds a {{ dictionary }} tag to Antlers, allowing you to use dictionaries outside the field type.

Usage:

{{ dictionary:countries }}{{ label }} {{ value }}{{ /dictionary:countries }}

or

{{ dictionary handle="countries" }}{{ label }} {{ value }}{{ /dictionary}}

It also gets any ‘extra’ data:

{{ dictionary handle="countries" }}{{ emoji }} {{ value }}{{ /dictionary}}

Searching:

{{ dictionary:countries search="Aus" }}{{ label }} {{ value }}{{ /dictionary:countries }}

Passing config:

Any params passed that arent handle or search will be passed as config... eg

{{ dictionary:countries emojis="false" }}{{ label }} {{ value }}{{ /dictionary:countries }}

conditions, pagination, chunking and limiting:

It supports conditions, pagination, chunking and limiting eg

{{ dictionary:countries iso2:is="AUS" paginate="4" }}{{ label }} {{ value }}{{ /dictionary:countries }}

query scopes

You can also use query scopes:
{{ dictionary:countries query_scope="my_scope" }}{{ label }} {{ value }}{{ /dictionary:countries }}

Files:

Where this gets really powerful is pulling in arbitrary files and being able to filter, paginate and output them:
{{ dictionary:file filename="products.json" label="Name" value="Code" paginate="4" }}

Note:
Under the hood its using an Item query builder to allow filtering, ordering etc.

Closes statamic/ideas#1214.

[jasonvarga]

If you want to get all the data you can add supplement_data similar to search results

Do we think this would be a performance concern? I don't think so. Might as well just include the data all the time. It's already just sitting there.

The reason we do it in search is because we need to actually do separate lookups etc.

[ryanmitchell]

Sure, easily changed.

[jasonvarga]

This was a bit out of scope for the tag, but I added a new method to the dictionary class to get the options.

The way you had it:

• You would get all the options() which under the hood would get all the items.
• Then you would get() each option, which would get all the items again each time.

i.e. When listing the countries, it would re-read the array 250 times, one for each country.
Or if you had a json file with 1000 options it would re-read and re-parse the file 1000 times.

This wasn't your fault as there wasn't an alternative for you.

Now, it'll get the options just once.

[ryanmitchell]

Yeah I had noticed that and had considered adding an all() or something to dictionary but didn’t want to push the PR too far!