Erstellen eines Widgets für ein Feld

Feld-Widgets werden verwendet, um ein Feld innerhalb von Formularen darzustellen. Feld-Widgets werden als Plugins definiert, daher empfiehlt es sich, die Plugin-API zu studieren, bevor man einen neuen Feldtyp schreibt.

Um ein Feld-Widget in Drupal 8 zu erstellen, benötigen Sie eine Klasse mit der Annotation FieldWidget.

Der Speicherort der Widget-Klasse sollte /[MODULNAME]/src/Plugin/Field/FieldWidget sein. Zum Beispiel: /foo/src/Plugin/Field/FieldWidget/BarWidget.php.

Der Namespace dieser Klasse sollte [MODULNAME]\Plugin\Field\FieldWidget sein. Zum Beispiel: \Drupal\foo\Plugin\Field\FieldWidget.

Die Annotation über der Klasse muss eine eindeutige ID, eine Beschriftung und ein Array der Feldtypen enthalten, die das Widget unterstützt.

/**
 * Ein Widget namens Bar.
 *
 * @FieldWidget(
 *   id = "bar",
 *   label = @Translation("Bar widget"),
 *   field_types = {
 *     "baz",
 *     "string"
 *   }
 * )
 */

Die Klasse muss das Interface WidgetInterface implementieren. Sie kann WidgetBase erweitern, um eine allgemeine Implementierung zu nutzen. Die einzige zwingend notwendige Methode ist ::formElement(), die die tatsächlichen Formularelemente zurückgeben muss, die Ihr Widget darstellen.

use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Field\WidgetBase;
use Drupal\Core\Form\FormStateInterface;

// ...
class BarWidget extends WidgetBase {

  /**
   * {@inheritdoc}
   */
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
    $element = [];
    // Erstelle das Render-Array für das Element.
    return $element;
  }

}

Widget-Einstellungen

Wenn Ihr Widget zusätzliche Einstellungen benötigt, sind drei Schritte erforderlich:

• Überschreiben Sie PluginSettingsBase::defaultSettings(), um Standardwerte zu definieren
• Erstellen Sie ein Konfigurationsschema für die Einstellungen
• Erstellen Sie ein Formular, um Benutzern die Änderung der Einstellungen zu ermöglichen

Schritt 1: Überschreiben Sie PluginSettingsBase::defaultSettings(), um Standardwerte zu setzen

/**
 * {@inheritdoc}
 */
 public static function defaultSettings() {
  return [
    // Erstelle die benutzerdefinierte Einstellung 'size' mit
    // dem Standardwert 60
    'size' => 60,
  ] + parent::defaultSettings();
}

Schritt 2: Erstellen Sie ein Konfigurationsschema für Ihre Einstellungen

Das Konfigurationsschema befindet sich in:

/[MODULNAME]/config/schema/[MODULNAME].schema.yml

Dort beschreiben Sie die Datentypen der Einstellungen aus defaultSettings():

Schritt 1 hat die Einstellung 'size' als Integer definiert. Das Schema sieht so aus:

field.widget.settings.[WIDGET-ID]:
  type: mapping
  label: 'WIDGET-NAME Widget Einstellungen'
  mapping:
    size:
      type: integer
      label: 'Größe'

Schritt 3: Erstellen Sie ein Formular, mit dem Benutzer Einstellungen anpassen können

Das Formular wird durch Überschreiben von WidgetBase::settingsForm() erzeugt.

/**
 * {@inheritdoc}
 */
public function settingsForm(array $form, FormStateInterface $form_state) {
  $element['size'] = [
    '#type' => 'number',
    '#title' => $this->t('Größe des Textfeldes'),
    '#default_value' => $this->getSetting('size'),
    '#required' => TRUE,
    '#min' => 1,
  ];

  return $element;
}

Sie können die ausgewählten Einstellungen auch in der Zusammenfassung des Widgets anzeigen lassen:

/**
 * {@inheritdoc}
 */
public function settingsSummary() {
  $summary = [];

  $summary[] = $this->t('Textfeldgröße: @size', ['@size' => $this->getSetting('size')]);

  return $summary;
}

Um Einstellungen im Widget zu verwenden, können Sie die Methode getSetting() aufrufen:

class BarWidget extends WidgetBase implements WidgetInterface {

class BarWidget extends WidgetBase implements WidgetInterface {

  /**
   * {@inheritdoc}
   */
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
    $element['value'] = $element + [
      '#type' => 'textfield',
      '#default_value' => isset($items[$delta]->value) ? $items[$delta]->value : NULL,
      '#size' => $this->getSetting('size'),
    ];

    return $element;
  }

}

Beispiel-Widget

TextWidget aus dem Modul field_example aus dem Examples-Modul:

namespace Drupal\field_example\Plugin\Field\FieldWidget;

use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Field\WidgetBase;
use Drupal\Core\Form\FormStateInterface;

/**
 * Plugin-Implementierung des Widgets 'field_example_text'.
 *
 * @FieldWidget(
 *   id = "field_example_text",
 *   module = "field_example",
 *   label = @Translation("RGB-Wert als #ffffff"),
 *   field_types = {
 *     "field_example_rgb"
 *   }
 * )
 */
class TextWidget extends WidgetBase {

  /**
   * {@inheritdoc}
   */
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
    $value = isset($items[$delta]->value) ? $items[$delta]->value : '';
    $element += [
      '#type' => 'textfield',
      '#default_value' => $value,
      '#size' => 7,
      '#maxlength' => 7,
      '#element_validate' => [
        [static::class, 'validate'],
      ],
    ];
    return ['value' => $element];
  }

  /**
   * Validiert das Farb-Textfeld.
   */
  public static function validate($element, FormStateInterface $form_state) {
    $value = $element['#value'];
    if (strlen($value) == 0) {
      $form_state->setValueForElement($element, '');
      return;
    }
    if (!preg_match('/^#([a-f0-9]{6})$/iD', strtolower($value))) {
      $form_state->setError($element, t("Die Farbe muss ein 6-stelliger Hexadezimalwert sein, geeignet für CSS."));
    }
  }

}