Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

Bought Jack McDade's course on design. Going through it now...and it is SO well done!

— Justin Jackson, Transistor.fm

Terms Fieldtype

Allows you attach Taxonomy Terms to your content. They could be Tags, Categories, Colors, Flavors, you name it. We highly recommend learning more about Taxonomies before going any further.

Terms Fieldtype UI
The Terms Fieldtype in action!

Overview

Taxonomies are usually relationships established on the collection-configuration level. Make sure to read the Taxonomies documentation to understand how everything works.

Data Structure

If the field is being used for taxonomizing your content (ie. the field name matches the taxonomy handle), the term's slugs will be saved.

wildlife:
- kangaroo
- three-toed-sloth
- panda
- porg

However, if you just want to store references to taxonomy terms for other purposes, the term's IDs will be saved. See below for more detail.

A term ID is the taxonomy handle combined with the slug.
This way, you may reference terms from multiple taxonomies.

things_you_may_find_adorable:
- wildlife/panda
- people/the-elderly

Templating

As outlined in the Taxonomies Guide, term slugs will automatically be converted to Term objects which means
you will have all of the term's data available as variables.

<ul>
{{ wildlife }}
<li><a href="{{ url }}">{{ title }}</a></li>
{{ /wildlife }}
</ul>
<ul>
<li><a href="/wildlife/kangaroo">Kangaroo</a></li>
<li><a href="/wildlife/three-toed-sloth">Three Toed Sloth</a></li>
</ul>

Using terms without taxonomizing

The most common use for this fieldtype is to taxonomize, or "tag", your entry.

However, sometimes you have other ideas in mind for using taxonomy terms. For instance, you might have a "similar tags" field, or want to create an index of many different, unrelated things. In this case, you aren't tagging the entry itself at all.

When using the taxonomy field in this way, terms will get saved using IDs instead of slugs.

similar_things:
- categories/hats
- tags/delightful

These will not be automatically converted to Terms, since the field name does not match any taxonomy handle.
You will need to use the Relate Tag in your template to have these converted to Terms.

<ul>
{{ relate:similar_things }}
<li><a href="{{ url }}">{{ title }}</a></li>
{{ /relate:similar_things }}
</ul>
<ul>
<li><a href="/categories/hats">Hats</a></li>
<li><a href="/tags/delightful">Delightful</a></li>
</ul>

Options

max_items

integer

The maximum number of items that may be selected. Setting this to 1 will change the UI to a dropdown.

taxonomy

string

The handle of the Taxonomy from which to fetch Terms. Not needed when placed in the fieldset's taxonomies array. In that case, it'll get the taxonomy from the field name.

create

boolean *true*

By default you may create new terms. Set to false to only allow selecting from existing terms.

query_scopes

string

Allows you to specify a query scope which should be applied when retrieving selectable terms.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →