Defining a custom field typefor Drupal 8 , 9 , 10 , and 11

Within Drupal's robust content management system, custom fields are pivotal in tailoring how data is structured and displayed. By defining custom field types, you provide content creators with specialized options that go beyond the standard offerings. In this lesson, we will walk through the process of setting up a custom field type, enhancing your site’s versatility and functionality.

Understanding the Field API

Drupal’s Field API facilitates the creation, manipulation, and storage of field data. It allows developers to define custom field types, add new storage formats, and specify how field data should be collected and processed. Leveraging this API, you can create content structures that are highly tailored to specific use cases.

Creating Your Custom Field Type

Let’s create a custom field type that stores coordinates for geographical locations. This field will accept both latitude and longitude values.

Step 1: Define the Field Type

Create a new directory in your module for the field type definition, usually at src/Plugin/Field/FieldType. Then, create a file named GeoLocationItem.php as follows:

namespace Drupal\your_module\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\TypedData\DataDefinition;

/**
 * Plugin implementation of the 'geolocation' field type.
 *
 * @FieldType(
 *   id = "geolocation",
 *   label = @Translation("Geolocation"),
 *   description = @Translation("Stores longitude and latitude as a pair."),
 *   default_widget = "geolocation_default",
 *   default_formatter = "geolocation_default"
 * )
 */
class GeoLocationItem extends FieldItemBase {

    /**
     * {@inheritdoc}
     */
    public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
        $properties['lat'] = DataDefinition::create('float')
            ->setLabel(t('Latitude'));
        $properties['lng'] = DataDefinition::create('float')
            ->setLabel(t('Longitude'));

        return $properties;
    }

    /**
     * {@inheritdoc}
     */
    public static function schema(FieldStorageDefinitionInterface $field_definition) {
        return [
            'columns' => [
                'lat' => [
                    'type' => 'float',
                ],
                'lng' => [
                    'type' => 'float',
                ],
            ],
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function isEmpty() {
        $lat = $this->get('lat')->getValue();
        $lng = $this->get('lng')->getValue();
        return $lat === NULL || $lng === NULL;
    }
}

In this code, we define a field type that includes both latitude and longitude properties, establishing a schema for database storage. The isEmpty method determines when the field is considered empty.

Step 2: Define a Field Widget

While the above code establishes the field's structure, to fully implement a custom field type you must provide a widget for UI interactions. We’ll explore defining custom widgets in the next lesson. For now, use Drupal’s default widget or any you might have already defined.

Step 3: Define a Field Formatter

Create a formatter to determine how the field data will be displayed. For instance, displaying coordinates as a text string.

namespace Drupal\your_module\Plugin\Field\FieldFormatter;

use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Field\FieldItemListInterface;

/**
 * Plugin implementation of the 'geolocation_default' formatter.
 *
 * @FieldFormatter(
 *   id = "geolocation_default",
 *   label = @Translation("Geolocation Default"),
 *   field_types = {
 *     "geolocation"
 *   }
 * )
 */
class GeoLocationDefaultFormatter extends FormatterBase {

    /**
     * {@inheritdoc}
     */
    public function viewElements(FieldItemListInterface $items, $langcode) {
        $elements = [];

        foreach ($items as $delta => $item) {
            $elements[$delta] = [
                '#markup' => $this->t('Lat: @lat, Lng: @lng', ['@lat' => $item->lat, '@lng' => $item->lng]),
            ];
        }

        return $elements;
    }
}

This formatter takes the latitude and longitude values and displays them in a simple string format. Formatters control the representation of field output in displays like views and node pages.

Adding the Field to a Content Type

Now that you've defined your custom field type, you can add it to any content type via the UI. When editing content types, you’ll find your "Geolocation" field available for use, further expanding your content model.

Conclusion

Defining a custom field type in Drupal can significantly enhance your site's data handling capabilities. With custom fields, you gain greater control over how content is stored and displayed, enabling more sophisticated and tailored site features.

As you continue with your Drupal journey, our next lesson will delve into "Building a Custom Widget for Fields," where you’ll learn how to create unique field input mechanisms. This will further empower Drupal users to capture data in innovative ways. Keep expanding your Drupal toolkit!