Hướng dẫn tạo Custom Field Formatter trong Drupal 8

In Drupal, field values are displayed to the end user via a field formatter. Formatters that come with fields are often pretty basic. If you want to change what a field displays, then the best way to do this is to write a custom formatter.

A field formatter in Drupal 7 can be created in a few ways: first with code or using the Custom Formatters module.

On the other hand, if you're using Display Suite, then you can create a "Display Suite Field" which is similar to a formatter.

But now it's time to learn how to create a field formatter in Drupal 8.

In this tutorial, we'll create a custom formatter for the link field that'll allow an editor to display an embedded YouTube video.

The link field will be used to store a YouTube URL and the formatter will be used to display the embedded video.

Now here comes the warning, the module that we'll create should be used only as an example. Do NOT use it on a real site. I want to keep this tutorial focused on how to create a formatter and not how to embed YouTube videos into Drupal.

You can grab a copy of the module directly from GitHub.

Here are extra resources about field formatters in Drupal 8:

• Drupal 8 Field API series part 1: field formatters
• Field formatters are now plugins (change record)

Step 1: Create Module

Before we can begin, we'll need to create a module called YouTube Formatter (youtube_formatter) and place it in the/modules directory.

In Drupal 8, you can add custom or contrib modules into /modules as well as /sites/*/modules. All of the core modules have been moved into /core, so in Drupal 8, don't touch anything in the /core directory.

1. Go into /modules and create a folder called youtube_formatter. Inside the module create the following two files:youtube_formatter.info.yml and youtube_formatter.module.

2. Open up youtube_formatter.info.yml and add the following:

name: YouTube Formatter
type: module
description: 'YouTube embed formatter for the link field.'
core: 8.x
dependencies:
  - field

3. Now, open up youtube_formatter.module and add the following:

<?php
 
/**
 * @file
 * Defines simple YouTube formatter for the link field.
 */

So far, we haven't done anything groundbreaking. All we've done is create an empty module. In the next section, we'll create the actual formatter.

Step 2: Create Formatter

Now it's time to implement the actual field formatter. We do this by defining a class called YouTubeLinkFormatter that extends the FormatterBase. Then in the class we'll use the viewElements() method to display the formatter.

1. Create a file called YouTubeLinkFormatter.php and place it in<module>/lib/Drupal/youtube_formatter/Plugin/Field/FieldFormatter/YouTubeLinkFormatter.php.

Open YouTubeLinkFormatter.php and add the following:

<?php
 
/**
 * @file
 * Contains \Drupal\youtube_formatter\Plugin\field\formatter\YouTubeLinkFormatter.
 */
 
namespace Drupal\youtube_formatter\Plugin\Field\FieldFormatter;
 
use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Field\FieldItemListInterface;

Make sure that the namespace is Drupal\youtube_formatter\Plugin\Field\FieldFormatter; and add the following two use statements: Drupal\Core\Field\FormatterBase; and Drupal\Core\Field\FieldItemListInterface;

2. Next we need to define the formatter using annotations. The annotations system is new in Drupal 8 and this is the equivalent of using hook_field_formatter_info in Drupal 7.

Add the following bit of code into YouTubeLinkFormatter.php.

/**
 * Plugin implementation of the 'youtube_link' formatter.
 *
 * @FieldFormatter(
 *   id = "youtube_link",
 *   label = @Translation("YouTube Formatter"),
 *   field_types = {
 *     "link"
 *   }
 * )
 */
class YouTubeLinkFormatter extends FormatterBase { }

The annotation attributes are pretty self-explanatory. All we've done is define an ID, label and which field type this formatter should be available on.

The field_types attribute is the most important part, if you don't add "link" then this formatter will not appear on the manage display page.

3. The last bit of work we'll do on the formatter is add the viewElements() method. This method is used to display the actual formatter and it's the only method required if your formatter class extends FormatterBase.

Add the following into the YouTubeLinkFormatter class:

/**
 * {@inheritdoc}
 */
public function viewElements(FieldItemListInterface $items) {
  $elements = array();
 
  foreach ($items as $delta => $item) {
    $url = $item->url;
    $elements[$delta] = array(
      '#theme' => 'youtube_link_formatter',
      '#url' => $url,
    );
  }
 
  return $elements;
}

The method is fairly simple, all we're doing is passing the URL property into a custom template that'll be used to display the embed HTML code.

Step 3: Create Template

Now that we've built the formatter, let's finish off the module by creating a custom template for it.

Instead of adding HTML code inside of the viewElements() method, we'll use a custom template. The template will be called youtube_link_formatter and it'll accept the URL as the single parameter.

1. Open up youtube_formatter.module and add the following function:

/**
 * Implements hook_theme().
 */
function youtube_formatter_theme() {
  return array(
    'youtube_link_formatter' => array(
      'variables' => array('url' => NULL),
      'template' => 'youtube-link-formatter',
    ),
  );
}

2. Create a folder in the module called templates and a file called youtube-link-formatter.html.twig.

In the .twig file, add the following:

<iframe width="560" height="315" src="{{ url }}" frameborder="0" allowfullscreen></iframe>

Our .twig template file is pretty simple. All we've done is add the iframe embed code and we're passing the {{ url }} variable into the src attribute.

Step 4: Test Formatter

Now that we've finished everything it's time to test the formatter. Go to your Drupal 8 site and install the Link and YouTube Formatter module.

Go and create a Link field on a content type, and in the manage display page you should be able to select "YouTube Formatter" as the formatter.

Once you've configured the formatter, create an article and enter a YouTube embed URL into the link field.

Example: http://www.youtube.com/embed/8uhNFoOnz_g

To keep this module simple, we won't perform any type of conversion on the URL. For the formatter to work you'll have to enter in the embed URL and not the page URL.

For example, here's the embed URL for a test video: http://www.youtube.com/embed/8uhNFoOnz_g and here's the URL to the video page: http://www.youtube.com/watch?v=8uhNFoOnz_g

In Drupal 8, field formatters are just as easy, if not easier, to create than in previous versions of Drupal. Also thanks to the new plugin system, each formatter has their own file which keeps things neat and tidy.