CMS

Drupal 8: Creating Custom Field Type/Plugin

Creating custom field type in Drupal 8 is like implementing plugin API, as fields are treated as the plugin in D8. If you are new to Drupal 8 and more comfortable to Drupal 7, then this comparison will give you a clear picture, how we can create custom field type in Drupal 8.

Drupal 8 plugins similar to Drupal 7 hooks

  • @FieldType = hook_field_info()
  • @FieldType = hook_field_schema()
  • @FieldFormatter = hook_field_formatter_info()
  • @FieldWidget = hook_field_widget_info()

A field is consist of three parts:

  1. Field Type: Type of field
  2. Field Formatter: Format of the field
  3. Field Widget: Widget of the field

We will discuss Field Type in detail below.

Field Type :

To create a new custom field type we need to follow the core plugin api implementation. The structure that we need to create as per Plugin API would be like this:

/modules/custom/my_custom_module/src/Plugin/Field/FieldType

In FieldType, we’ll create one php file which contains the definition of the field type.

Code Description:

First, we are providing annotation (@FieldType) for a plugin, which contains

id: Field id/machine name of the field,

label: Field Label,

description: Help text for the user to understand what is the usage of this field,

default widget: Contains the id of default widget

default formatter: Information about formatter

Class MyField contains 3 functions:

  1. propertyDefinitions(): This will contain all the fields for our custom field type.
  2. schema(): Schema function contains the DB schema to let the system know how to store the data of custom field type.
  3. isEmpty() : IsEmpty function will let system know,how to determine when the field is empty.

Apart from these functions, there are many more functions available to perform different operations.

Below is the list of functions which are very commonly used:

  • defaultStorageSettings() : This will define the storage level settings for the field.
  • defaultFieldSettings() : This will define the field level settings for the field.
  • storageSettingsForm() : This will return a form for the storage level settings.
  • fieldSettingsForm() : This will return a form for the field level settings.
  • generateSampleValue() : This will generate sample placeholder content.

Field Formatter

Field Formatter contains the definition of formatter, which decides, how the data to be viewed to the end users. To create our custom field formatter, we have to follow the structure:

/modules/custom/my_module/src/Plugin/Field/FieldFormatter

Under FieldFormatter folder, we’ll create one php file “MyFieldFormatter.php

Code:

Code Explanation:

We are using 2 core classes FormatterBaseFieldItemListInterface.

Annotation (@FieldFormatter) contains field formatter information like:

id: Machine name of formatter

label: Display text of formatter

field_type: Field for which we are creating formatter

Class MyFieldFormatter contains 3 functions:

  • defaultSettings() : Define the default settings for the formatter.
  • settingsSummary() : This function returns a short summary of the formatter settings.
  • viewElements(): This method defines, how a field is going to be displayed on the page. We have so many attributes available to use in this function such as theme, type, markup etc.

Field Widget

In this section, we will discuss the field widget.

The structure for creating a field widget is:

/modules/custom/my_module/src/Plugin/Field/FieldWidget

Code :

Code Description:

Here we are using 3 core classes:

  • FieldItemListInterface
  • WidgetBase
  • FormStateInterface

Annotation (@FieldWidget) will be the same as we used for field type and field formatter.

  • id = widget id/machine name.
  • label = title text for widget.
  • field_type = name of the field type, for which we are creating a widget.

We are extending the “WidgetBase” class to create our custom widget. By Implementing “formElement” function, we are creating a form, which provides the form interface to the end user to edit our custom field type. In our code, we are just providing one text field, but this function is having a lot of potentials to create complex form.

Apart from this function, we have a lot more functions available to provide different functionality as per the requirement.

Some commonly used functions are:

  • defaultSettings() : Define the default settings for the field/plugin.
  • settingsForm(): This function returns a form to configure the settings of the widget.
  • settingsSummary(): This function will return the summary text for the widget.

Final Output:

The field will appear in the list of available field types on field settings form of the entities.

Here is the sample field rendering.

Summary

By developing all the 3 plugins, field type, field formatter and field widget, we can achieve our fully functional custom field type. One important point to be considered here is to use the @annotation, as using annotation is the only way to let Drupal know, what exactly this class/function is going to do.

Reading Links

To get more details on Field API please visit the following link, FieldItemBase API.

Here are some more interesting links:

About The Author