Custom Formatters

The Custom Formatters module allows users to easily create custom Field Formatters through an admin UI without writing a custom module. Custom Formatters are exported as Drupal configuration entities.

For a full description of the module, visit the project page.

Submit bug reports and feature suggestions, or track changes in the issue queue.

Table of contents

• Requirements
• Installation
• Configuration
• Features
• Roadmap
• Maintainers

Requirements

• Drupal 10 or 11
• PHP 8.2+

The following modules are recommended:

• Token — Provides the token tree browser for the HTML + Tokens engine.
• Field tokens — Provides formatted field and field property tokens for the HTML + Token engine.
• CodeMirror Editor — Provides syntax-highlighted code editing for the PHP, HTML+Token, and Twig formatter engines, with context-aware autocomplete ({{, [, < triggers and Ctrl+Space) including structure-aware $settings['field'] / settings.field / [formatter_setting:field:raw] completions.
• Devel — Provides the Devel Generate sub-module for generating sample preview entities.

Installation

1. Download and install via Composer:

   composer require drupal/custom_formatters

2. Enable the module:

   drush en custom_formatters

Configuration

Read the manual at: drupal.org/node/2514412

Features

• Pluggable formatter engines:
  • Formatter Preset — Build formatters from existing field formatters with preset settings.
  • HTML + Tokens — A HTML based editor with Token support, including a Token tree browser when the Token module is installed.
  • PHP — A PHP based editor with support for multiple fields and multiple values.
  • Twig — A Twig based editor with support for multiple fields and multiple values.
• Per-instance formatter settings via Field UI — add configurable fields to a formatter via its "Manage fields" tab; settings appear inline in "Manage display" and are passed to engine templates as both rendered strings and raw unformatted values:
  • PHP: $settings['field_name'] (rendered), $raw_settings['field_name'] (raw getString() value).
  • Twig: {{ settings.field_name }} (rendered), {{ raw_settings.field_name }} (raw getString() value).
  • HTML+Token: [formatter_setting:field_name] (rendered), [formatter_setting:field_name:raw] (raw getString() value).
• Supports all fieldable entities, including but not limited to:
  • Drupal core — Comment, Node, Taxonomy term, User, and Media entities.
• Exportable as Drupal configuration entities.
• Live preview using real entities, with Devel Generate integration for generating sample entities when no real entities exist with the target field type.
• Integrates with:
  • Contextual links (Drupal core) — Adds a hover link for quick editing of Custom Formatters.
  • Token — Adds the Token tree browser to the HTML + Tokens engine with automatic entity reference token support.
  • Devel Generate (optional) — Generates sample entities with dummy field data for the live preview system when no real entities exist with the target field type.
  • Insert (optional) — Exposes custom formatters as Insert styles for image, file, and entity_reference fields, allowing formatted output to be inserted directly into WYSIWYG editors. Activate by installing the Insert module alongside Custom Formatters; no additional configuration required.

Roadmap

Planned features for future releases:

• Granular permissions — Per-engine permission gates, e.g. a separate permission to create PHP formatters.
• Export — Generate a standalone Drupal module from a custom formatter.
• Coder review integration — Inline PHPCS review of PHP formatter code against Drupal coding standards directly in the formatter edit form.
• Display Suite integration — Format Display Suite fields with custom formatters.
• JSON:API integration — Apply custom formatters to JSON:API field output.
• Field type management — Change a formatter's field types after creation; fall back to default formatter on deletion.

Maintainers

• Stuart Clark - deciphered
• Andrii Podanenko - podarok