Création d’un type de champ dans un module Drupal

Les types de champs définissent les propriétés et le comportement des champs. Les types de champs sont définis comme des plugins, il est donc recommandé de se familiariser avec l’API des plugins avant de créer un nouveau type de champ.

Pour créer un type de champ dans Drupal 8, vous avez besoin d’une classe avec une annotation FieldType.

Emplacement de la classe du type de champ : MODULE_NAME/src/Plugin/Field/FieldType
Exemple : /modules/foo/src/Plugin/Field/FieldType/BazItem.php

Namespace de cette classe : Drupal\MODULE_NAME\Plugin\Field\FieldType

<?php

namespace Drupal\MODULE_NAME\Plugin\Field\FieldType;

L’annotation au-dessus de la classe dans le commentaire de documentation doit inclure un identifiant unique, un label et un formateur par défaut. Le formateur par défaut sera l’identifiant utilisé dans l’annotation de la classe du formateur de champ.

/**
 * Fournit un type de champ baz.
 * 
 * @FieldType(
 *   id = "baz",
 *   label = @Translation("Champ Baz"),
 *   default_formatter = "baz_formatter",
 *   default_widget = "baz_widget",
 * )
 */

La classe doit implémenter l’interface FieldItemInterface et étendre FieldItemBase pour une implémentation commune.

class BazItem extends FieldItemBase {

}

FieldItemInterface::schema() doit être surchargée pour indiquer au système comment stocker les valeurs du champ :

/**
 * {@inheritdoc}
 */
public static function schema(FieldStorageDefinitionInterface $field_definition) {
  return [
    // 'columns' contient les valeurs que le champ stockera.
    'columns' => [
      // Ce champ ne stocke qu’une seule valeur, 'value'.
      'value' => [
        'type' => 'text',
        'size' => 'tiny',
        'not null' => FALSE,
      ],
    ],
  ];
}

Cette méthode retourne un tableau de spécifications des colonnes pour l’API schema.

La méthode FieldItemInterface::propertyDefinitions() renseigne le système sur les propriétés du champ :

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

  return $properties;
}

La méthode Map::isEmpty (héritée par FieldItemBase) doit être surchargée pour indiquer comment déterminer si un champ est vide :

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

Paramètres du champ

Les paramètres du champ permettent à l’utilisateur de configurer le champ selon ses besoins. S’il y a des paramètres, trois étapes sont nécessaires :

1. Surcharger FieldItemBase::defaultFieldSettings() pour définir les valeurs par défaut.
2. Créer un schéma de configuration pour ces paramètres.
3. Créer un formulaire permettant aux utilisateurs de modifier les paramètres.

Étape 1 : surcharger FieldItemBase::defaultFieldSettings()

/**
 * {@inheritdoc}
 */
public static function defaultFieldSettings() {
  return [
    // Déclare un paramètre 'size' avec la valeur par défaut 'large'.
    'size' => 'large',
  ] + parent::defaultFieldSettings();
}

Étape 2 : créer le schéma de configuration

Le schéma va dans :

[MODULE ROOT]/config/schema/[MODULE_NAME].schema.yml

Ce fichier décrit le type des données de configuration créées dans defaultFieldSettings(). Par exemple, pour le paramètre « size » (une chaîne) :

field.field_settings.[FIELD ID]:
  type: mapping
  label: 'Paramètres FIELDNAME'
  mapping:
    size:
      type: string
      label: 'Taille'

Étape 3 : créer le formulaire de modification des paramètres

Vous créez ce formulaire en surchargeant FieldItemBase::fieldSettingsForm() :

/**
 * {@inheritdoc}
 */
public function fieldSettingsForm(array $form, FormStateInterface $form_state) {

  $element = [];
  // La clé de l’élément doit correspondre au nom du paramètre.
  $element['size'] = [
    '#title' => $this->t('Size'),
    '#type' => 'select',
    '#options' => [
      'small' => $this->t('Small'),
      'medium' => $this->t('Medium'),
      'large' => $this->t('Large'),
    ],
    '#default_value' => $this->getSetting('size'),
  ];

  return $element;
}

Exemple concret

RgbItem du module field_example dans le projet d’exemples :

namespace Drupal\field_example\Plugin\Field\FieldType;

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

/**
 * Plugin implementation of the 'field_example_rgb' field type.
 *
 * @FieldType(
 *   id = "field_example_rgb",
 *   label = @Translation("Example Color RGB"),
 *   module = "field_example",
 *   description = @Translation("Demonstrates a field composed of an RGB color."),
 *   default_widget = "field_example_text",
 *   default_formatter = "field_example_simple_text"
 * )
 */
class RgbItem extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function schema(FieldStorageDefinitionInterface $field_definition) {
    return [
      'columns' => [
        'value' => [
          '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('Hex value'));

    return $properties;
  }

}