[6.x] Taxonomy structures (hierarchies), routing, and more

[jackmcdade]

(I know, finally)

Taxonomies can now be hierarchical/orderable/nestable, using the same structure/tree model as collections. While in there, taxonomies also got the routing control, view scaffolding and API surface that collections have had for a while.

Enable a structure 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 use > and will create missing segments, but they won't re-parent a term that's already in the tree. A segment that doesn't exist in the tree yet is grafted in at the root so the child can nest under it.
• No expectsRoot. Terms don't have a collection-style root page.

Routing

Taxonomy and term URLs are now configurable per taxonomy, under Routing & URLs in the taxonomy config.

• Automagic — what you get today. Nestable taxonomies default to /{handle}/{parent_uri}/{slug}.
• Custom — your own pattern, per site if you want. {parent_uri} is the new placeholder for the ancestor path. A custom route is treated as a complete URL pattern, so a collection-scoped taxonomy no longer gets a second collection-prefixed URL for free.
• Disabled — the taxonomy and its terms stop having URLs entirely. $taxonomy->url() and friends return null, and the front-end responses 404.

A nestable term is still resolvable by slug anywhere under the taxonomy — its old flat URL, for instance — and permanently redirects (301) to the canonical nested one. Makes migrating an existing flat taxonomy painless.

Scaffolding

Taxonomies get a Scaffold Views screen, same as collections. It generates index and show views (nestable-aware — the stubs emit ancestors and children loops when the taxonomy is nestable) and writes template / term_template back onto the taxonomy.

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 }}

Also in here

New surface

• Link fieldtype gains a term type, alongside entries and assets, with a taxonomies config.
• REST: new GET /api/taxonomies/{taxonomy}/tree, matching the collection and nav tree endpoints. with_descendants=false on the collection-entries and term-entries endpoints.
• GraphQL: Taxonomy.structure with a tree(site:) field, and parent / children / ancestors / depth on TermInterface. with_descendants on the entries query.
• Permissions: a new reorder {taxonomy} terms, nested under edit {taxonomy} terms. Existing roles will need it granted.
• Events: TaxonomyTreeSaving / Saved / Deleted, wired into git automation and static cache invalidation.
• Trees are stored in content/trees/taxonomies/.

Behaviour changes

None of this is a breaking change, but a few things shift for existing sites.

• Renaming or deleting a term now matches stored values by slug equivalence rather than exact string. Values stored as raw titles (AC/DC for a term slugged ac-dc) are now rewritten or removed where 6.x left them dangling, and fields that store taxonomy::slug values are updated too — 6.x only matched a bare slug, so those were never touched.
• Term URL resolution was reworked. TermRepository::findByUri() matches against each taxonomy's term route now, rather than doing a uri-index lookup. Flat taxonomies go through the same path. No regression found, but it's worth knowing so a bug report is easy to place.
• Taxonomy trees enforce max depth server-side. Collections don't, anywhere. Deliberate — it's the one spot where parity with collections wasn't applied, so please don't "fix" it in either direction.
• A term blueprint using parent, children, ancestors or depth loses those handles to the structure once you enable a structure. Flat taxonomies keep the blueprint field and its fieldtype, so nothing changes on upgrade.

Fixes

• ?fields= is now honoured on the terms API show route, completing [6.x] REST API: honor fields param on entries and assets #15319 — which added ResolvesRequestedFields but only wired it into EntryResource and AssetResource.
• A bare {{ children }} no longer 500s on a term page. It 500s on released 6.x too — AugmentedTerm has never had a children key — so this isn't a regression being cleaned up, just a hole being filled.
• Multisite: a term referenced by an entry in a site the taxonomy isn't enabled in no longer resolves to an empty title-from-slug stub. That stub shadowed the real term, so edits made to it didn't stick. Term::find() prefers the taxonomy's own site now, and the terms store falls back to the term's actual file. Single-site installs can't be affected either way.
• Multisite: the taxonomy listing opens in a site the taxonomy actually has, rather than whichever site is globally selected. It also gets a site selector.
• Non-English sites: taxonomy values are slugged with the entry's site language now, matching what term creation already did. Without it you could end up with a duplicate empty "ghost" term holding the entries while the real term showed none. It's read/index-time only — nothing is rewritten on disk. If an entry stores a raw title rather than a slug (hand-written YAML, an import, an API write — the CP never does this) on a site whose language transliterates differently, the archive page for that term stops listing those entries. Store the slug rather than the title to fix it.

References

• Document taxonomy structures docs#1991
• Closes Hierarchical Taxonomies ideas#92
• Closes Scaffold taxonomy templates ideas#264
• Closes Ability to use the link field with taxonomy terms ideas#1053
• Closes Localizable Taxonomy Routes #2334.
• Ghost Taxonomies / Deleted Taxonomy not always deleting associations from entry #11264
• Neue Taxonomies #74
• Let's make taxonomies great again ideas#839
• Toggle between languages in Taxonomy view ideas#580.
• Hierarchical Taxonomy Support eloquent-driver#607