A Field Formatter provides an easy way to format fields in Drupal. Many come with Drupal core and are available for use after site installation. Some common Field Formatters include Plain Text
, Label
, Entity ID
, and Rendered Entity
to name a few.
Field Formatters render fields in various ways. For example, I may want to render an email field as a clickable link that will open up an email client. By default, email fields have two field formatters that can be used, Plain Text
and Email
. The first option would of course just render the email as raw text printed to the page where the second would give us the result we're looking for.
To edit the formatter for a field, follow these steps:
Field Formatters also have specific settings you can use to fine tune the fields rendered results. These settings can be accessed and edited by clicking on the cog icon at the end of the row of that field. In the case of formatters like the Email
formatter, there are few or no settings at all. Of course, like many things in Drupal, you can make field formatters of your own!
To make a field formatter you must:
Drupal\{module_name}\Plugin\Field\FieldFormatter
namespace. Be sure to use the appropriate folder structure ({module_name}/src/Plugin/Field/FieldFormatter
).FormatterBase
class. Dont forget to add use Drupal\Core\Field\FormatterBase;
after the namespace. (Note: Field Formatter class names should be named according to its functionality and have "Formatter" as a suffix. An example would be BasicStringFormatter
which is responsible for the Plain Text
formatter.)/** * Plugin implementation of the 'basic_string' formatter. * * @FieldFormatter( * id = "basic_string", * label = @Translation("Plain text"), * field_types = { * "string_long", * "email" * }, * quickedit = { * "editor" = "plain_text" * } * ) */
viewElements
method can help us with this. We have access to it from the FormatterInterface
implemented by the FormatterBase
class. The FieldItemListInterface
must be used for the $items
parameter. Be sure to add use Drupal\Core\Field\FieldItemListInterface;
This function allows you to render field items, whether one or many, how ever you like. This may be something as simple as adding some markup to the output to using that output in JS to do something interesting! Here is how the Basic String Formatter uses this method:public function viewElements(FieldItemListInterface $items, $langcode) { $elements = []; foreach ($items as $delta => $item) { // The text value has no text format assigned to it, so the user input // should equal the output, including newlines. $elements[$delta] = [ '#type' => 'inline_template', '#template' => '{{ value|nl2br }}', '#context' => ['value' => $item->value], ]; } return $elements; }
Once you follow those steps, enable the module (if you have not already), and clear cache, you will have a basic working field formatter for use on the fields it is intended for.
For more information on Field Formatters, such as how to create formatter settings and more, check out the offical documentation on drupal.org.