This chapter is part of the Drupal Module Developer Guide.
This chapter builds on earlier chapters about controllers and Render API to introduce the Drupal Form API. It demonstrates how to define the fields of a form, handle validation of user input, and manage processing of submitted data. As well as how to alter the structure and behavior of forms provided by other modules.
Drupal's Form API (FAPI) is a comprehensive framework for managing forms within Drupal. The Form API extends the Render API, providing a structured approach to form creation, validation, and submission. It offers an abstraction layer over HTML forms and HTTP form handling, simplifying the process of capturing and processing user input securely and efficiently. Forms are integral to content management systems like Drupal, enabling user interactions ranging from content creation to configuration settings. For module developers, using the Form API is essential for building interactive and dynamic websites.
In this tutorial, we'll:
- Discuss the relationship between the Form API and the Render API.
- Highlight the significance of forms in Drupal and the role of the Form API in managing them.
- Outline the life cycle of a Drupal form, from definition to processing, including the role of form controllers.
By the end of this tutorial, you should grasp the fundamentals of the Form API and be prepared to construct and manage forms in Drupal modules.
The life cycle of a Drupal form, from initial request to final processing, involves multiple stages. This tutorial outlines these stages and the role of form controllers, which contain custom form handling logic.
In this tutorial, we'll:
- Define the role of a form controller.
- List the phases of form processing in Drupal and how to add custom logic to each.
- See how form controllers relate to routes for displaying full-page forms.
By the end of this tutorial, you should be able to explain the role of a form controller and how to get started creating a new one.
Settings forms are commonly used in Drupal modules to allow administrators to manage a module's configuration. This tutorial will guide you through creating a settings form for the Anytown weather forecast module, enabling site administrators to customize the location for weather forecasts.
In this tutorial, we'll:
- Define a new form controller for a settings form.
- Build a
$formarray with options for the settings form. - Associate the form with a route and menu item.
By the end of this tutorial, you'll have a custom settings form that administrators can access.
We must validate user input entered in forms to ensure data integrity and security. In our Anytown module, we need to verify that the location input for the weather forecast API is a valid 5-digit ZIP code.
In this tutorial, we'll:
- Add a
validateForm()method to the form controller. - Ensure the
locationfield contains a 5-digit ZIP code. - Display an error if validation fails.
By the end of this tutorial, you'll know how to add custom validation logic to a form.
The submitForm() method in a form controller is responsible for handling submitted data. This method can save data to the database (including updating configuration), trigger workflows based on user input, and redirect users after form processing. By the time data reaches submitForm(), it has been validated and is ready for use.
In this tutorial, we'll:
- Add a
submitForm()method to the form controller. - Save user-provided settings to the database.
- Confirm successful data submission to the user.
By the end of this tutorial, you'll understand how to implement custom submit handling logic in a form.
One of the most powerful features of Drupal's Form API is the ability to alter nearly any aspect of the build, validate, or submit workflow in your custom code. Implementing hook_form_alter is a common task for Drupal module developers, allowing them to modify forms to customize administrative or user-facing interfaces.
In this tutorial, we'll:
- Explore the purpose and use case for
hook_form_alterand related hooks. - Learn how to target specific forms.
- Discover how to identify the form you wish to alter.
By the end of this tutorial, you should be able to select and implement the appropriate form alter hook to modify any form in Drupal.
Let's combine our knowledge of implementing hooks and hook_form_alter() to customize a form built by another module, the user registration form. For the Anytown Farmer's Market site's user registration form, we want to introduce 2 new features: a mandatory "Accept terms of use" checkbox and custom validation to prevent registration with the username "anytown".
In this tutorial, we'll:
- Identify the form ID of the user registration form.
- Incorporate new elements into the user registration form.
- Implement additional validation logic.
By the end of this tutorial, you should be able to use hook_form_alter() to customize any existing Drupal form.
