[Phần 3] Drupal 8: Hướng dẫn tạo custom field - 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:

/**
 * @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.