Field formatter

A field formatter is the Drupal plugin that turns a field's stored values into page output, such as plain text or the label of a referenced item.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

A field formatter is the part of a field that controls how its values are displayed when the entity is shown. You pick it per field and per view mode on the Manage display page. A long text field can be shown trimmed or in full, and a term reference as plain text or as a link, depending on the formatter.

How field formatters work in Drupal 11

A field has a type, and that type can name a default formatter. The Field UI lets a site builder choose another formatter that supports the type. For each view mode the page offers a Label setting (whether and how to show the label), a formatter drop-down, a gear icon for the formatter's settings, and a drag handle for the order of the fields. Choosing Hidden in the formatter drop-down, or dragging the field into the Disabled section, removes the field from that view mode.

In code, a formatter is a plugin:

  • It carries the FieldFormatter attribute with an id, a label and a field_types list of the field types it supports.
  • It implements FormatterInterface, usually by extending FormatterBase, and lives in Drupal\{module}\Plugin\Field\FieldFormatter.
  • Its viewElements() method receives the field items and a language code and returns a render array with one child per value, keyed by consecutive numbers from 0. The view() method builds the fully themed field, including the label.
  • settingsForm() and settingsSummary() provide the gear-icon form and the one-line summary. isApplicable() tells whether the formatter fits a given field definition.

Core examples: the string formatter (labeled Plain text) supports the string and uri field types and has a setting to link the output to the entity. The entity_reference_label formatter (labeled Label) displays the label of the referenced entities. Contributed modules can add more formatters. The Field API describes the plugin system as a whole.

Example

The Drupal User Guide improves the display of a Vendor content type. Go to Structure › Content types, open the menu beside Vendor and choose Manage display. In the Label column, select Hidden for Main image and Vendor URL. Click the gear icon of Vendor URL, clear the link text trimming and check Open link in new window. Click Update, reorder the fields, and click Save. The guide says to clear the cache if the changes do not appear.

Common mistakes

  • Changing only the default display. A view mode that uses custom settings ignores the default. Check the Custom display settings section and switch to the view mode you are looking at, such as teaser.
  • Mixing up the two Hidden options. The Label setting hides the label; the formatter drop-down hides the field.
  • Looking for the setting on the edit form. The edit form belongs to the widget. A formatter works on the output of the page.
  • Not seeing a change. Clear the cache before concluding that the setting failed, as the user guide advises.

For marketing and content teams

Formatters decide how the same content looks in different places: full in an article, shortened in a list. If a field shows too much, too little or the wrong label, the fix can be a formatter setting rather than a content edit. Ask your site builder to change it on Manage display. If no formatter produces the output you want, a developer can write one as a plugin.

With DXPR

DXPR Builder is a field formatter. On Manage display you change the Format of a formatted text field, such as Body, from Default to DXPR Builder. After that, every item of the content type opens the visual builder for editors who have permission. The setup guide lists the steps. See DXPR Builder.

Sources

Questions about Field formatter

The widget is the control on the edit form where an editor enters the data. The formatter produces the output when the entity is displayed. You set them on two different pages: Manage form display for widgets and Manage display for formatters.

Go to Structure › Content types, open the menu beside the content type and choose Manage display. Pick the formatter in the drop-down for the field. A gear icon opens the formatter's settings when it has any.

Yes. Each view mode can use the default display settings or its own custom settings, and a field can have a different formatter in each view mode. Turn on custom settings for the view mode in the Custom display settings section of Manage display.

On Manage display, choose Hidden in the Label column for that field. The formatter drop-down also has a Hidden choice, but that one removes the whole field from the view mode.

Related terms

All Drupal terms from A to Z