Drupal 8: Creating a custom field - Part 3: Field formatter

This is part 3 in my series of articles about creating a custom field. I recommend reading Part 1: Field type and Part 2: Field widget first, if you have not done so already.

After creating the field type and field widget it is now time to complete the set by creating the field formatter.

##a) Create the file
The field type must be located as follows:

<module_name>/lib/Drupal/<module_name>/Plugin/field/formatter/<field_formatter_name>.php
N.B. The field formatter name should be in CamelCase.

##b) Add Contains, namespace and use
In the newly created field type file add a brief comment to explain what it consists of:

<code class="language-php">
/**
 * @file
 * Contains \Drupal\module_name\Plugin\field\formatter\
 */
</code>

N.B. The "Contains..." line should match the location and name of this file.

Then add the namespace as follows:

<code class="language-php">
namespace Drupal\<module_name>\Plugin\field\formatter;
</code>

N.B. Again I must emphasise that it is vital for the namespace to match the location of the file otherwise it will not work.

Then add the following uses:

<code class="language-php">
use Drupal\field\Plugin\Type\Formatter\FormatterBase;
</code>

This provides the class that the field widget will extend.

<code class="language-php">
use Drupal\Core\Entity\Field\FieldItemListInterface;
</code>

This provides a variable type required within the field formatter class.

##c) Add formatter details annotation
The annotation should appear as follows:

<code class="language-php">
/**
 * Plugin implementation of the '<field_formatter_id>' formatter.
 *
 * @FieldFormatter(
 *   id = "<field_formatter_id>",
 *   label = @Translation("<field_formatter_label>"),
 *   field_types = {
 *     "<field_type_id>"
 *   }
 * )
 */
</code>

N.B. All text represented by a <placeholder> should be appropriately replaced according to requirements. The field_type_id must match the id of a field type and the field_formatter_id should match the default formatter specified in the field type (see Part 1 of this article).

##d) Add field formatter class
Create the field formatter class as follows:

<code class="language-php">
class <field_formatter_name> extends FormatterBase {

}
</code>

N.B. The <field_formatter_name> must match the name of this file (case-sensitive).

The field formatter class needs to contain the viewElements() function that defines how the field will be output:

<code class="language-php">
/**
 * {@inheritdoc}
 */
public function viewElements(FieldItemListInterface $items) {
   $elements = array();

   foreach ($items as $delta => $item) {
     $elements[$delta] = array(
       '#theme' => 'person_default',
       '#forename' => check_plain($item->forename),
       '#surname' => check_plain($item->surname),
       '#age' => check_plain($item->age),
     );
   }
  return $elements;
}
</code>

When writing a viewElements() function for a field with multiple columns I recommend using a custom theme (e.g. person_default) to avoid including markup within the code.

Here is a simple example, similar to that discussed above.

Once you have created a field type, a field widget and field formatter you now have a custom field type!

After you have saved the files (and cleared caches, of course!) you will find:

• the field type in the Field Type drop-down when adding a new field, under the Manage Fields tab.
• the field widget in the Widget drop-down under the Manage Form Display tab.
• the field formatter Format drop-down under the Manage Display tab.