[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.

This round of changes have been addressed