Building a custom widget for fieldsfor Drupal 8 , 9 , 10 , and 11

The strength of Drupal lies in its flexibility, and custom field widgets are a prime example of extending that flexibility to form input. Widgets act as the interface for field data entry, providing users with structured input forms tailored to their needs. This lesson teaches you how to create a custom widget, enhancing how data is captured within your content types.

What is a Field Widget?

A field widget is the UI component that allows users to input data into fields. It translates the structure of a field type into an interactive form element. While Drupal comes with several built-in widgets, building custom widgets enables you to provide unique and intuitive input methods suited for specific data, increasing usability and accuracy.

Creating Your Custom Field Widget

Continuing with our example of a geolocation field, let's build a custom widget that includes separate text fields for latitude and longitude entry.

Step 1: Define the Widget Plugin

Create a directory in your module for the widget plugin, such as src/Plugin/Field/FieldWidget. Then create a file named GeoLocationWidget.php to define the widget.

namespace Drupal\your_module\Plugin\Field\FieldWidget;

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

/**
 * Plugin implementation of the 'geolocation_widget' widget.
 *
 * @FieldWidget(
 *   id = "geolocation_widget",
 *   label = @Translation("Geolocation Widget"),
 *   field_types = {
 *     "geolocation"
 *   }
 * )
 */
class GeoLocationWidget extends WidgetBase {

    /**
     * {@inheritdoc}
     */
    public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
        $element['lat'] = [
            '#type' => 'textfield',
            '#title' => $this->t('Latitude'),
            '#default_value' => isset($items[$delta]->lat) ? $items[$delta]->lat : '',
            '#size' => 10,
        ];
        
        $element['lng'] = [
            '#type' => 'textfield',
            '#title' => $this->t('Longitude'),
            '#default_value' => isset($items[$delta]->lng) ? $items[$delta]->lng : '',
            '#size' => 10,
        ];

        return $element;
    }
}

In this code, we define a custom widget that provides text fields for entering latitude and longitude. The formElement method is where we build the form elements displayed to end users. Here, \$delta refers to the item position in the multiple items list, ensuring distinct inputs for each item position.

Step 2: Rendering the Widget

When users input data, this widget handles rendering the input elements and default values. It links customizable input methods directly to your field structure, providing dynamic data entry methodologies.

Configuring Your Widget

Once your widget is defined, it can be selected within the "Manage form display" tab for relevant content types. Here, site builders choose which widget to use, enabling them to customize input methods for enhanced usability and data accuracy.

Supporting Validation

You can add custom validation within the widget by implementing validators. These additions ensure data integrity by confirming the input meets specific requirements before being saved.

/**
 * Custom validation for geolocation coordinates.
 */
public function validateElements(array &$element, FormStateInterface $form_state) {
    foreach ($form_state->getValues() as $delta => $value) {
        if (!is_numeric($value['lat']) || !is_numeric($value['lng'])) {
            $form_state->setError($element, $this->t('The coordinates must be numeric values.'));
        }
    }
}

Such validations are essential for reducing user error and ensuring consistent data entry across diverse users and sessions.

Conclusion

Creating a custom widget adds an exciting layer of flexibility and control over how users interact with data entry forms in Drupal. By shaping the input experience and ensuring data integrity with widgets, you underpin robust module development within your site.

As you refine your Drupal expertise, our next lesson will focus on "Creating a Custom Formatter for Field Output," where you'll see how to creatively format and display the data captured through these customizable forms. Keep enhancing your Drupal development journey, one module component at a time!