Creación de un tipo de campo en un módulo Drupal

Los tipos de campo definen las propiedades y el comportamiento de los campos. Los tipos de campo se definen como plugins, por lo que se recomienda revisar la API de plugins antes de comenzar a escribir un nuevo tipo de campo.

Para crear un tipo de campo en Drupal 8, necesitas una clase con la anotación FieldType.

La ubicación de la clase del tipo de campo debe ser MODULE_NAME/src/Plugin/Field/FieldType
Ejemplo: /modules/foo/src/Plugin/Field/FieldType/BazItem.php

El namespace de esta clase debe ser Drupal\MODULE_NAME\Plugin\Field\FieldType

<?php

namespace Drupal\MODULE_NAME\Plugin\Field\FieldType;

La anotación sobre la clase dentro del comentario de documentación debe incluir un identificador único, etiqueta y el formateador por defecto. El formateador por defecto es el identificador que se usará en la anotación de la clase formateadora de campo.

/**
 * Provee un tipo de campo baz.
 * 
 * @FieldType(
 *   id = "baz",
 *   label = @Translation("Campo Baz"),
 *   default_formatter = "baz_formatter",
 *   default_widget = "baz_widget",
 * )
 */

La clase debe implementar la interfaz FieldItemInterface y extender la clase FieldItemBase para una implementación común.

class BazItem extends FieldItemBase {

}

El método FieldItemInterface::schema() debe ser sobreescrito para indicar al sistema cómo almacenar los valores del campo:

/**
 * {@inheritdoc}
 */
public static function schema(FieldStorageDefinitionInterface $field_definition) {
  return array(
    // 'columns' contiene los valores que almacenará el campo
    'columns' => array(
      // Lista de valores que guardará el campo, en este caso un solo valor llamado 'value'
      'value' => array(
        'type' => 'text',
        'size' => 'tiny',
        'not null' => FALSE,
      ),
    ),
  );
}

Este método retorna un array con la especificación de columnas para el esquema API.

El método FieldItemInterface::propertyDefinitions() informa al sistema detalles más específicos de las propiedades de tu campo:

/**
 * {@inheritdoc}
 */
public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
  $properties = [];
  $properties['value'] = DataDefinition::create('string');

  return $properties;
}

El método Map::isEmpty (heredado por FieldItemBase) debe ser sobreescrito para indicarle al sistema cuándo un campo está vacío.

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

Configuraciones del campo

Las configuraciones de campo permiten que los usuarios ajusten el campo según sus necesidades. Si el campo tiene configuraciones, debes hacer tres pasos:

1. Sobre-escribir FieldItemBase::defaultFieldSettings() para definir valores por defecto
2. Crear un esquema de configuración para esas opciones
3. Crear un formulario para permitir que los usuarios modifiquen las configuraciones

Paso 1: Sobre-escribir FieldItemBase::defaultFieldSettings()

/**
 * {@inheritdoc}
 */
public static function defaultFieldSettings() {
  return [
    // Declara una única opción 'size' con valor por defecto 'large'
    'size' => 'large',
  ] + parent::defaultFieldSettings();
}

Paso 2: Crear esquema de configuración para las opciones

El esquema va en:

[RAIZ_DEL_MODULO]/config/schema/[NOMBRE_DEL_MODULO].schema.yml

En este archivo describes el tipo(s) de dato para las opciones creadas en defaultFieldSettings():

El paso 1 creó una opción llamada 'size' que guarda una cadena. El esquema será así:

field.field_settings.[ID_DEL_CAMPO]:
  type: mapping
  label: 'Configuraciones de FIELDNAME'
  mapping:
    size:
      type: string
      label: 'Tamaño'

Paso 3: Crear formulario para que los usuarios modifiquen configuraciones

Este formulario se crea sobreescribiendo FieldItemBase::fieldSettingsForm()

/**
 * {@inheritdoc}
 */
public function fieldSettingsForm(array $form, FormStateInterface $form_state) {
  
  $element = [];
  // La clave del elemento debe ser el nombre de la configuración
  $element['size'] = [
    '#title' => $this->t('Tamaño'),
    '#type' => 'select',
    '#options' => [
      'small' => $this->t('Pequeño'),
      'medium' => $this->t('Mediano'),
      'large' => $this->t('Grande'),
    ],
    '#default_value' => $this->getSetting('size'),
  ];

  return $element;
}

Ejemplo real

RgbItem del módulo field_example en el proyecto Examples:

namespace Drupal\field_example\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldDefinitionInterface;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\TypedData\DataDefinition;

/**
 * Implementación del plugin 'field_example_rgb'.
 *
 * @FieldType(
 *   id = "field_example_rgb",
 *   label = @Translation("Color ejemplo RGB"),
 *   module = "field_example",
 *   description = @Translation("Demuestra un campo compuesto por un color RGB."),
 *   default_widget = "field_example_text",
 *   default_formatter = "field_example_simple_text"
 * )
 */
class RgbItem extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function schema(FieldStorageDefinitionInterface $field_definition) {
    return array(
      'columns' => array(
        'value' => array(
          'type' => 'text',
          'size' => 'tiny',
          'not null' => FALSE,
        ),
      ),
    );
  }

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

  /**
   * {@inheritdoc}
   */
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('string')
      ->setLabel(t('Valor hexadecimal'));

    return $properties;
  }

}