Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

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

Parent Feed: 

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:

/**
* @file
* Contains \Drupal\<module_name>\Plugin\field\formatter\<field_formatter_name>.
*/

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

Then add the namespace as follows:

namespace Drupal\<module_name>\Plugin\field\formatter;

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:

use Drupal\field\Plugin\Type\Formatter\FormatterBase;

This provides the class that the field widget will extend.

use Drupal\Core\Entity\Field\FieldItemListInterface;

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

c) Add formatter details annotation

The annotation should appear as follows:

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

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:

class <field_formatter_name> extends FormatterBase {

}

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:

  /**
* {@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;
}

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.
Author: 
Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web