Upgrade Your Drupal Skills
We trained 1,000+ Drupal Developers over the last decade.
See Advanced Courses NAH, I know EnoughDrupal 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:
/**
* @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 use
s:
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.
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