Taxonomy term

A taxonomy term is one label inside a Drupal vocabulary, for example Carrots in a vocabulary of ingredients or Germany in a vocabulary of countries. Each term is a content entity with its own ID, a name, a description and a place in the vocabulary's hierarchy. Content points to terms through a reference field, and Drupal gives every term a page that lists what is tagged with it.

How a taxonomy term works in Drupal 11

The entity type is taxonomy_term. Its bundle is the vocabulary, and its ID key is tid. In Drupal 11.4.10 a term is revisionable and translatable, and it has these base fields:

• name, a required text of up to 255 characters;
• description, long text with a text format;
• parent, an entity reference with unlimited values, limited to terms of the same vocabulary;
• weight, an integer that orders terms in ascending order;
• status, shown on the form as Published.

The user guide adds that you can attach further fields to a term, such as an icon image. This is the part that separates a term from a plain tag string: it is an entity that can carry its own data.

The term page at /taxonomy/term/{tid} comes from core's taxonomy term view. Its header shows the term in the full view mode, and each row is a piece of tagged content in the teaser view mode. Viewing requires the View published content permission (access content) and a published term; edit and delete rights are granted per vocabulary through permissions such as "Edit terms" and "Delete terms".

Example

Take a vocabulary of ingredients. Under Structure › Taxonomy, choose Add terms for the vocabulary. Create Vegetables, then create Tomatoes and open its Relations section. Choose Vegetables under Parent terms and save. Tomatoes now sits under Vegetables, and the vocabulary's overview page shows the nesting. Both terms get pages at /taxonomy/term/{tid}, and each page lists the content tagged with that term.

Common mistakes

• Unpublishing a term and expecting visitors to keep the page. Without the administer permission, an unpublished term is not viewable, so its page is closed to anonymous visitors.
• Using the term name as an identifier. A name can be edited and translated. Code and configuration should refer to the ID or the UUID.

For marketing and content teams

Every term is a ready-made landing page. The page shows the term and the content tagged with it, so a clear name and a useful description matter. Check how each term page looks before you launch a tagging scheme, and use the Published checkbox to hold a term back until it is ready. For the wider picture of vocabularies and reference fields, see taxonomy.

Sources

• Drupal User Guide: Concept: Taxonomy
• Drupal User Guide: Setting up a taxonomy
• Term entity class, Drupal core 11.4.10
• TermForm, Drupal core 11.4.10
• TermDeleteForm, Drupal core 11.4.10
• TermAccessControlHandler, Drupal core 11.4.10
• TaxonomyPermissions, Drupal core 11.4.10
• OverviewTerms form, Drupal core 11.4.10
• Taxonomy term view, Drupal core 11.4.10