[6.x] Hierarchical Taxonomies

[jackmcdade]

(I know, finally)

Taxonomies can now be hierarchical, using the same structure/tree model as collections.

Enable it on a taxonomy, drag terms into a tree, and you get nested URLs, parent/children/ancestors/depth in tags, a CP tree view, and a parent relationship field on the publish form. Max depth 1 stays a flat reorderable list, same as collections.

See it in action – https://screen.studio/share/IeuqzNy2

A few constraints worth knowing:

• One global tree. Slugs stay unique per taxonomy (default locale); URI segments localize.
• Typed paths in a terms field will create missing segments, but they won't re-parent a term that's already in the tree.
• No expectsRoot. Terms don't have a collection-style root page.

Templating

Tree, same as nav/collection structures. Recursive children work the usual way. nav:taxonomy:… is an alias.

{{ structure:taxonomy:categories }}
    {{ title }}
    {{ if children }}{{ *recursive children* }}{{ /if }}
{{ /structure:taxonomy:categories }}

{{ structure for="taxonomy::categories" from="animals" max_depth="2" }}
    {{ title }} (depth {{ depth }})
{{ /structure }}

On a term, the tree is just variables:

{{ parent:title }}
{{ depth }}
{{ children }}{{ title }}{{ /children }}
{{ ancestors }}{{ title }}{{ /ancestors }}

List terms by branch with {{ taxonomy }}. parent without depth is direct children; add depth to go further. depth alone is top N levels of the whole tree.

{{ taxonomy from="categories" parent="animals" }}
    {{ title }}
{{ /taxonomy }}

{{ taxonomy from="categories" parent="animals" depth="2" }}
    {{ title }}
{{ /taxonomy }}

{{ taxonomy from="categories" depth="1" }}
    {{ title }}
{{ /taxonomy }}

Entry listings include the whole branch by default. Opt out with with_descendants="false".

{{ collection:blog taxonomy:categories="animals" }}
    {{ title }}
{{ /collection:blog }}

{{ collection:blog taxonomy:categories="animals" with_descendants="false" }}
    {{ title }}
{{ /collection:blog }}

Still needed

• Eloquent driver companion. Still in draft.
• Docs. Routing, the structure tag, with_descendants, the parent field, and the "typed paths don't re-parent" rule.

Test plan

• Create a hierarchical taxonomy, nest terms in the tree, confirm nested URLs and CP parent field
• Reparent from the publish form; reject self / descendant / max-depth
• Max-depth 1 taxonomy behaves as a flat reorderable list
• Terms field: typed nested path creates missing terms without moving existing ones
• Multi-site: one tree, localized URI segments, site selector on the tree
• {{ structure:taxonomy:… }} and collection/entry filters include descendants by default

Issues

Closes statamic/ideas#92
Closes statamic/ideas#264
Closes statamic/ideas#1053
Closes #2334.

Related: #74, statamic/ideas#839, statamic/ideas#580.

[jaygeorge]

Some minor text-contrast suggestions

[jaygeorge]

Hey Jack – nice work 🖖 !

Couple of things I came across UI-wise…

Attaching Multiple Taxonomies

Attaching multiple taxonomies flattens the hierarchical view, even if they're both hierarchical, like this:

Single taxonomy attached, and we get the tree view (sidebar):

Multiple taxonomies attached, and everything is flattened:

I wondered, if all attached terms are hierarchical, what if we could still keep the hierarchical view?

This unites some of the interface work I've been doing on multisite grouping, where the heading terms in uppercase are not selectable:

Double Chevrons

I wonder if it would be cleaner/more consistent with the rest of the UI to use a single chevron to indicate the hierarchy.

Before:

After:

Hierarchy icons

The return-carriage icons feel a little brutalist to my eyes, I wonder if we could use something from the Streamline set. Here's an example:

Before:

After:

Minor issue with text-contrast

I've made some suggestions in the review to pass AA for text colors.

[jasonvarga]

This is a really well-put-together feature — the reuse of the existing structure/tree machinery, the opt-in design, and the test coverage (~2,800 lines across routing, tree CRUD, grafting, reference updates, GraphQL, REST, scaffolding, permissions) are all great. CI is green and the branch merges cleanly.

Requesting changes for one regression and one likely multisite gap, both commented inline:

1. Flat-taxonomy values containing / get corrupted by the new reference-update logic in Terms::replaceValuesInArray()/valueRefersToTerm(). This needs to be gated to hierarchical taxonomies — details inline.
2. parent/depth params on the {{ taxonomy }} tag filter by default-locale slugs, which likely returns nothing on sites with localized term slugs.

The remaining inline comments are smaller notes/nits that don't block on their own.