Form API Overview
FreeDrupal's Form API is a set of interfaces, utility classes, and conventions that when combined together allow module developers to create forms that collect, validate, and process user-submitted data. The Form API is closely related to the Render API. It uses Render Arrays to define forms, and adds an additional level of workflow and processing to enhance the Render API with some features specific to handling forms.
Given that forms are one of the primary means of interacting with a Drupal site via the UI, understanding how the Form API works is a critical part of learning to develop modules for Drupal. While you may not need to know all the nitty-gritty details, every Drupal module developer is likely to encounter aspects of the Form API at some point. Understanding the basics should be considered required knowledge.
Theme developers are also likely to encounter some aspects of the Form API, as forms are inherently part of the look and feel of a site. Knowing how to make changes to the UX of a form is an important skill.
In this tutorial we'll:
- Describe what forms are and how they are used in Drupal
- Explain the relationship between Form API and the Render API
- List some of the benefits of using the Form API over generic HTML forms
By the end of this tutorial you should have a solid understanding of the role of the Form API in Drupal.
Eventually you'll want to do something with the information your form collects beyond just printing it to the screen. It's generally considered a best practice to keep business logic out of your form controller so that it can be reused. In order to accomplish that you'll generally define your business logic in a service, and then call out to that service from your form controller. Or, you can make use of one of the existing services provided by Drupal core to save data.
In this tutorial we'll:
- Use dependency injection to inject a service into a form controller
- Make use of a service injected into a form controller from within the
buildForm()
andsubmitForm()
methods
By the end of this tutorial you'll understand how to inject one or more services into your form controller and then make use of them.
You probably created a form with the intent of collecting user input and then doing something with that input. Using the submitForm()
method of our form class we can access the validated, and sanitized, user input data and make use of it for our own needs. We might do things like save the collected data as configuration, update an entity, or use it as part of a search query.
In this tutorial we'll:
- Demonstrate how to add a
submitForm()
method to a form controller class - Access the value(s) of form input elements via the
$form_state
object - Set a redirect after performing processing in a form submission handler
- Look at alternative ways to affect the submission handling of a form like
#submit
callbacks
By the end of this tutorial you should know how to access the values of a submitted form, and how to write custom processing code that gets invoked when the form passes validation.
Sometimes you need to add additional processing of input to forms where your module doesn't implement the form controller. In order to do this you can use the #submit
property of the root level $form
element, or of a specific button on a form, to add one or more callbacks. These functions, or methods, will be automatically called when the Form API is processing a submitted form and give your custom code an opportunity to do whatever it needs to do.
In this tutorial we'll:
- Look at alternative ways to affect the submission handling of a form like
#submit
callbacks
By the end of this tutorial you should know how to add a #submit
callback to an entire form, or a specific button in a form.
When you create a custom form for Drupal and your module defines the form controller, the best way to handle processing of submitted data is via the submitForm()
method of your controller. This method is called automatically by the Form API during the process of handling a user-submitted form. It can be used to save incoming data to the database, trigger a workflow based on user input, and instruct the Form API where to send the user after form processing has completed.
In this tutorial we'll:
- Demonstrate how to add a
submitForm()
method to a form controller class - Access the value(s) of form input elements via the
$form_state
object - Set a redirect after performing processing in a form submission handler
By the end of this tutorial you should know how to access the values of a submitted form, and how to write custom processing code inside of the submitForm()
method of a form controller.
When a form is submitted you'll need to check the data input by the user to ensure that it matches certain constraints, and to raise errors when necessary. Is the email address in the proper format? Is the title field long enough? Does the ASIN ID entered match a valid Amazon product? This process is called validation and is handled by a combination of the validateForm()
method of a form controller, and validation callbacks.
In this tutorial we'll:
- Explain the use case for both the
validateForm()
method of a form controller, and validation callbacks - Discuss additional uses for validation handlers beyond just checking the length of a text field, or format of a phone number field
By the end of this tutorial you should know how to start adding custom validation logic to any form in Drupal.
When working with forms that are not created by your code, where you're not implementing the form controller but rather interacting with the form via implementations of hook_form_alter()
, you can use the #validate
property of the root form element to add additional validation logic in the form of a callback function or method.
In this tutorial we'll:
- Implement a
#validate
callback that raises an error if specific conditions are not met
By the end of this tutorial you should know how to add custom validation logic to any form in Drupal by using a #validate
callback.
When your module defines the form and the form controller, you can add your validation logic as part of the form controller. This is done via the implementation of a validateForm()
method. The FormBuilder
service will automatically invoke this method at the appropriate time during the process of submitting a form. While the validateForm()
method is required by \Drupal\Core\Form\FormInterface
, an empty method will fulfill that requirement. It's up to you to provide appropriate validation code inside the method.
In this tutorial we'll:
- Use the
validateForm()
method of a form controller to verify user input - Demonstrate how to raise errors on a form element when it doesn't pass validation
By the end of this tutorial you should know how to validate your custom forms.
When defining a new FormElement
plugin, or if your constraints are only relevant for a single element, you can use the #element_validate
property of an individual element to specify additional validation callbacks.
In this tutorial we'll:
- Add an
#element_validate
callback to a single element in a form to perform validation of just that element.
By the end of this tutorial you should know how to add #element_validate
callbacks to any form element in Drupal.
How do you figure out what hooks are available to implement? How do you know which hook to implement to accomplish a task?
The list of hooks that are available to implement in your custom Drupal module varies depending on the modules enabled for a site. Each module can optionally invoke new hooks. There are also some hooks invoked by Drupal core subsystems like Form API that are always present. This can make it a little bit tricky sometimes to figure out what hooks are available, and which one to implement.
In this tutorial we'll look at:
- Different ways to get a list of available hooks
- Where to find the documentation for a hook so you can know if it's the one you want to implement
By the end of this tutorial you should be able to browse a list of hooks and their related documentation.
Hooks allow module developers to execute custom code at key moments during Drupal's request processing life cycle. They can be used to react to actions or conditions, alter forms and existing configuration, and extend Drupal in various ways. Knowing how to implement a hook is an essential skill for any Drupal developer. All hooks are implemented in the same way, so once you know how to implement one, you'll be able to implement any.
In this tutorial we'll:
- Define a recipe for implementing hooks
- Locate a hook's documentation
- Provide examples of both function-based and class-based hook implementations
By the end of this tutorial, you should be able to start implementing any hook in your custom code.
As a module developer you should define and invoke new hooks in your module in order to allow other developers -- or even future you -- to extend your module's functionality without hacking your module's code. This requires:
- Creating a new, unique, name for your hook
- Providing documentation for your hook
- Invoking the hook at critical points in your code
By the end of this tutorial you should have a better idea of when to define a new hook and know how to invoke a hook from your code.
What Are Hooks?
FreeHooks allow modules to alter and extend the behavior of Drupal core, or another module. They are one of the various ways that code components in Drupal can communicate with one another. Using hooks a module developer can change how core or another module works -- without changing the existing code. As a Drupal developer, understanding how to implement and invoke hooks is essential.
In this tutorial we'll:
- Define what hooks are and the types of hooks that exist
- Understand the use case for hooks
By the end of this tutorial you should be familiar with the concept of hooks and understand when you might want to implement a hook.
In this tutorial, we'll examine one the first files you'll need in order to create a Drupal module: the info file. Each module is required to have a MODULE.info.yml file to help Drupal identify that a bundle of code is a unique module. This specially-formatted YAML file tells Drupal about the module and provides other useful metadata. In this tutorial, we'll walk through both required and optional information you put in a module's info file.
Modules can provide action links to make common operations more readily available within a particular context. For example, a site administrator visiting the content management page may be interested in adding content. If you've ever noticed the Add content button on this page, that's an example of an action link. In this tutorial we'll take a look at how custom modules can provide these action links to make it easier for users to interact with our site.
Contextual links provide yet another method for Drupal module developers to add helpful links for site administrators to quickly navigate to commonly used tasks. In this tutorial we'll learn how to implement and render contextual links from a custom module. We will also look at a pair of alter hooks that can be used to tweak existing contextual links.
In this tutorial we will learn how to add menu links using a custom Drupal module. We will also look at the options available for configuring our new menu link. Lastly, we'll learn about using hook_menu_links_discovered_alter()
that can be used to add new menu links, or alter the behavior of existing ones.
Drupal provides module developers several different methods for creating the different types of links we see on a typical page. In this tutorial we'll see how these different types of links relate to each other, and when you might want to make use of them.
In this tutorial we'll provide an overview of the following concepts:
- Menu links
- Action links
- Local tasks
- Contextual links
If you've ever built or administered a Drupal site, the permissions page (/admin/people/permissions) is probably quite familiar.
If you're new to module development, you may wonder where these permissions come from, and how you can specify your own permissions. In this tutorial we'll answer those questions.
First, we'll look at how to define permissions from within a custom module. We'll examine techniques that enable you to provide specific (static) permissions as well as dynamic permissions, which depend on another piece of data, such as the name of a content type. By the end of this tutorial you will understand how to add both static and dynamic permissions to a custom module.
Knowing how to define a new plugin type will allow you to write modules that are more extensible, and more configurable. In doing so you'll learn more about best practices in decoupling code within your module, and get an in-depth look at how the plugin system works. Even if you're not defining a new plugin type in your own module, understanding how the system works will give you more insight into how many parts of Drupal work. This is essential knowledge for anyone developing modules for Drupal.
By the end of this tutorial you should be able to determine if defining a new plugin type is the right solution to your problem, and then understand the steps involved in doing so.