Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Content Types and Fields

Taxonomy and Entity References

Organize Drupal content with taxonomy vocabularies and terms, hierarchies and tags, and link content together with entity reference fields and reverse lookups.

Content rarely stands alone. An article has a category, an author, related articles, a cover image. Drupal expresses all of these links with one mechanism: entity reference fields. A special, very common case is taxonomy, Drupal's system for categories and tags. This lesson teaches both, so you can organize a site and let visitors navigate by topic.

You should be comfortable with entity types and bundles from Entities, Bundles and Fields and with adding fields from Content Types and Fields.

Taxonomy: vocabularies and terms

  • A vocabulary is a collection of terms, like "Topics" or "Campuses". It is a bundle of the taxonomy_term entity type.
  • A term is one entry: "Science", "Sports". It can have its own fields (a description, an image).
  • Terms can form a hierarchy (Science > Physics > Optics) with parents and children, or stay flat like tags.

Create a vocabulary at Structure > Taxonomy > Add vocabulary, then add terms with Add term, or type new terms directly in a content form when the reference field allows creating terms on the fly.

The standard installation includes a Tags vocabulary and a field_tags field on Article.

Entity reference fields

An entity reference field stores the ID of another entity. Add one with Create a new field > Reference > Taxonomy term (or Content, User, Media, and so on). During configuration you choose:

  • The type of item to reference (taxonomy term, node, user...).
  • Reference method: by default, "Default" with a sort and bundles list: limit choices to certain vocabularies or content types.
  • Create referenced entities if they don't already exist: useful for free-tagging.
  • Cardinality: one category or many tags.
  • Widget: autocomplete, autocomplete (tags style), select list, check boxes, radio buttons.

Remember the benefit: the reference is a relationship. If you rename the term "Sports" to "Athletics", every article using that term shows the new name, because the article stores the term's ID, not the word.

Showing references

On Manage display, choose a formatter for the reference field:

  • Label: prints the term name, optionally linking to the term page.
  • Rendered entity: renders the referenced entity with a view mode of your choice (for example the author as a small "card").
  • Entity ID: mostly for debugging.

Each taxonomy term has a page at /taxonomy/term/{tid}, produced by a View, listing content tagged with that term. You can customize or replace it with your own View (see Views Basics).

References in code

Real Drupal code, read-only:

PHP
<?php

$node = \Drupal::entityTypeManager()->getStorage('node')->load(5);

// Loop over the referenced terms.
foreach ($node->get('field_tags')->referencedEntities() as $term) {
  echo $term->label() . "\n";
}

// A single-value reference to a user.
$author = $node->get('field_reviewer')->entity;
echo $author?->getDisplayName();

The entity property loads the referenced entity for you, and referencedEntities() does the same for many values at once.

Reverse lookups

References point one way: the article knows its tags, the tag does not store which articles use it. To find "all articles with this tag", you query the relationship. In practice a View does it (filter by the term), or an entity query in code:

PHP
$ids = \Drupal::entityQuery('node')
  ->condition('type', 'article')
  ->condition('field_tags', 12)
  ->condition('status', 1)
  ->accessCheck(TRUE)
  ->execute();

Always call accessCheck(), so users only see what they may access.

Hierarchies

For hierarchical vocabularies, Drupal stores each term's parents. When you filter a View by a term, you can include its children ("depth") so that a page for Science also lists articles tagged Physics. Plan depth carefully; very deep trees are hard for editors to maintain.

References versus text fields

Do not store a category as free text. With a reference you get consistent spelling, easy renaming, filters, term pages and permissions. Use plain text only for values that are truly one-off, like a custom subtitle.

A reference model you can run

This stand-in stores terms and articles, resolves references and does the reverse lookup that a View would perform, including a depth-aware filter on a hierarchy.

JS Stand-in: terms, references and reverse lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that renaming a term in the terms object would change every article's displayed tag instantly, because articles only hold IDs.

A common trick: show "related articles" by counting shared tags. Drupal does this with a View that has a contextual filter on the current node's terms; the stand-in below shows the logic.

JS Stand-in: related content by shared tags

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Modeling checklist

  • Would an editor reuse this value? Make it a vocabulary.
  • Does the value have its own data (a speaker's bio)? Make it its own entity and reference it.
  • Is the list short and fixed? A List field may be simpler.
  • Do you need a hierarchy? Use parents; otherwise stay flat.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a taxonomy vocabulary?

    Vocabularies such as Tags or Topics hold the terms you assign to content.
  2. 2. What does an entity reference field store?

    Storing the ID means changes to the referenced entity show up everywhere it is used.
  3. 3. How do you find all articles that use a given tag?

    References are stored on the referencing side; reverse lookups are queries.
  4. 4. Why call accessCheck() in an entity query?

    Drupal requires you to state whether the query respects access, to avoid leaking restricted content.

Summary

  • Taxonomy organizes content into vocabularies of terms, flat or hierarchical.
  • Entity reference fields store IDs, so renames propagate; formatters decide how references appear.
  • Reverse lookups are queries, typically made with Views.
  • Use references instead of free text for reusable, filterable values.

Next: Media and Images