Building a form class extending FormBasefor Drupal 8 , 9 , 10 , and 11

In Drupal, creating custom forms is pivotal for module development. Forms allow users to input data, interact with features, and customize settings. This lesson will guide you through building a basic form class by extending FormBase. This foundation will empower you to construct more sophisticated forms in your modules.

Understanding FormBase

In Drupal, FormBase is an abstract class provided by the core Form API. It offers a blueprint for creating forms with essential methods to define, build, validate, and process form submissions. By extending FormBase, you inherit a structured approach to form building, ensuring consistency and reliability.

Why Use FormBase?

The FormBase pattern provides several benefits:

• Structured Methodology: It enforces a structured approach to defining and managing forms.
• Reusable Logic: Leverage consistent form handling across different functionalities within your module.
• Extensibility: Easily extend and adapt your form with additional fields and functionality.

Example Scenario: Configuring Weather Module Settings

Let’s build an administrative form for configuring the weather module, allowing administrators to set API keys and default location settings through a user-friendly interface.

Step 1: Create the Form Class

In your module’s src/Form directory, create a new PHP file named WeatherSettingsForm.php. Ensure this directory structure reflects the autoloading standard of PSR-4.

// weather_module/src/Form/WeatherSettingsForm.php

namespace Drupal\weather_module\Form;

use Drupal\Core\Form\FormBase;
use Drupal\Core\Form\FormStateInterface;

class WeatherSettingsForm extends FormBase {

  /**
   * {@inheritdoc}
   */
  public function getFormId() {
    return 'weather_settings_form';
  }

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    $config = $this->config('weather_module.settings');

    $form['api_key'] = [
      '#type' => 'textfield',
      '#title' => $this->t('API Key'),
      '#default_value' => $config->get('api_key'),
      '#description' => $this->t('Enter your weather API key.'),
      '#required' => TRUE,
    ];

    $form['default_location'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Default Location'),
      '#default_value' => $config->get('default_location'),
      '#description' => $this->t('Enter a default location for weather data.'),
      '#required' => TRUE,
    ];

    $form['submit'] = [
      '#type' => 'submit',
      '#value' => $this->t('Save settings'),
    ];

    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function submitForm(array &$form, FormStateInterface $form_state) {
    $this->config('weather_module.settings')
      ->set('api_key', $form_state->getValue('api_key'))
      ->set('default_location', $form_state->getValue('default_location'))
      ->save();

    $this->messenger()->addMessage($this->t('Weather settings have been saved.'));
  }
}

Step 2: Define Hook Links for Access

We need to provide a way for site administrators to access this form. Add a route in your module’s .routing.yml file:

// weather_module.routing.yml

weather_module.settings:
  path: '/admin/config/weather_module/settings'
  defaults:
    _form: '\Drupal\weather_module\Form\WeatherSettingsForm'
    _title: 'Weather Module Settings'
  requirements:
    _permission: 'administer site configuration'

Step 3: Verify the Form Display

Clear Drupal caches using drush cr, then navigate to your newly created route. You should see a form that enables configuring API keys and default location settings for the weather module.

Advantages of FormBase

Utilizing FormBase for building forms in your Drupal application leverages the power of the Form API. This approach ensures your forms are secure, consistent, and blend seamlessly within Drupal's administrative structure.

Conclusion and Next Steps

This lesson provided an introduction to building forms by extending FormBase. Understanding this pattern is essential for tapping into Drupal's advanced form-handling capabilities, setting the stage for further enhancements and refinements in your custom modules.

In the next lesson, we will explore "Adding fields (text, select, checkbox) to forms", where you will learn how to introduce various form elements to enhance data input and user interactions.

Stay curious, and I'll meet you in the next module development lesson!