Form generation

  1. 7.x drupal/includes/form.inc form_api
  2. 6.x drupal/includes/form.inc form_api
  3. 8.x drupal/core/includes/form.inc form_api

Describes how to generate and manipulate forms and process form submissions.

Drupal provides a Form API in order to achieve consistency in its form processing and presentation, while simplifying code and reducing the amount of HTML that must be explicitly generated by a module.

Creating forms

Forms are defined as classes that implement the \Drupal\Core\Form\FormInterface and are built using the \Drupal\Core\Form\FormBuilder class. Drupal provides a couple of utility classes that can be extended as a starting point for most basic forms, the most commonly used of which is \Drupal\Core\Form\FormBase. FormBuilder handles the low level processing of forms such as rendering the necessary HTML, initial processing of incoming $_POST data, and delegating to your implementation of FormInterface for validation and processing of submitted data.

Here is an example of a Form class:

namespace Drupal\mymodule\Form;

use Drupal\Core\Form\FormBase;

class ExampleForm extends FormBase {
  public function getFormId() {
    // Unique ID of the form.
    return 'example_form';
  }

  public function buildForm(array $form, array &$form_state) {
    // Create a $form API array.
    $form['phone_number'] = array(
      '#type' => 'tel',
      '#title' => $this->t('Your phone number')
    );
    return $form;
  }

  public function validateForm(array &$form, array &$form_state) {
    // Validate submitted form data.
  }

  public function submitForm(array &$form, array &$form_state) {
    // Handle submitted form data.
  }
}

Retrieving and displaying forms

\Drupal::formBuilder()->getForm() should be used to handle retrieving, processing, and displaying a rendered HTML form. Given the ExampleForm defined above, \Drupal::formBuilder()->getForm('Drupal\mymodule\Form\ExampleForm') would return the rendered HTML of the form defined by ExampleForm::buildForm(), or call the validateForm() and submitForm(), methods depending on the current processing state.

The argument to \Drupal::formBuilder()->getForm() is the name of a class that implements FormBuilderInterface. Any additional arguments passed to the getForm() method will be passed along as additional arguments to the ExampleForm::buildForm() method.

For example:

$extra = '612-123-4567';
$form = \Drupal::formBuilder()->getForm('Drupal\mymodule\Form\ExampleForm', $extra);
...
public function buildForm(array $form, array &$form_state, $extra = NULL)
  $form['phone_number'] = array(
    '#type' => 'tel',
    '#title' => $this->t('Your phone number'),
    '#value' => $extra,
  );
  return $form;
}

Alternatively, forms can be built directly via the routing system which will take care of calling \Drupal::formBuilder()->getForm(). The following example demonstrates the use of a routing.yml file to display a form at the the given route.

example.form:
  path: '/example-form'
  defaults:
    _title: 'Example form'
    _form: '\Drupal\mymodule\Form\ExampleForm'

The $form argument to form-related functions is a structured array containing the elements and properties of the form. For information on the array components and format, and more detailed explanations of the Form API workflow, see the Form API reference and the Form API documentation section. In addition, there is a set of Form API tutorials in the Form Example Tutorial which provide basics all the way up through multistep forms.

In the form builder, validation, submission, and other form methods, $form_state is the primary influence on the processing of the form and is passed by reference to most methods, so they can use it to communicate with the form system and each other.

See \Drupal\Core\Form\FormBuilder::buildForm() for documentation of $form_state keys.

Functions

Namesort descending Location Description
drupal_form_submit Deprecated drupal/core/includes/form.inc Retrieves, populates, and processes a form.
drupal_get_destination drupal/core/includes/common.inc Prepares a 'destination' URL query parameter for use with url().
drupal_process_form Deprecated drupal/core/includes/form.inc Processes a form submission.
drupal_redirect_form Deprecated drupal/core/includes/form.inc Redirects the user to a URL after a form has been processed.
drupal_retrieve_form Deprecated drupal/core/includes/form.inc Retrieves the structured array that defines a given form.
form_builder Deprecated drupal/core/includes/form.inc Builds and processes all elements in the structured form array.
form_error Deprecated drupal/core/includes/form.inc Flags an element as having an error.
form_execute_handlers Deprecated drupal/core/includes/form.inc Executes custom validation and submission handlers for a given form.
form_get_cache Deprecated drupal/core/includes/form.inc Fetches a form from the cache.
form_get_error Deprecated drupal/core/includes/form.inc Returns the error message filed against the given form element.
form_get_errors Deprecated drupal/core/includes/form.inc Returns an associative array of all errors.
form_get_options drupal/core/includes/form.inc Returns the indexes of a select element's options matching a given key.
form_load_include drupal/core/includes/form.inc Ensures an include file is loaded whenever the form is processed.
form_options_flatten Deprecated drupal/core/includes/form.inc Allows PHP array processing of multiple select options with the same value.
form_pre_render_actions_dropbutton drupal/core/includes/form.inc #pre_render callback for #type 'actions'.
form_pre_render_button drupal/core/includes/form.inc Prepares a #type 'button' render element for theme_input().
form_pre_render_checkbox drupal/core/includes/form.inc Prepares a #type 'checkbox' render element for theme_input().
form_pre_render_color drupal/core/includes/form.inc Prepares a #type 'color' render element for theme_input().
form_pre_render_conditional_form_element drupal/core/includes/form.inc Adds form element theming to an element if its title or description is set.
form_pre_render_date drupal/core/includes/form.inc Adds form-specific attributes to a 'date' #type element.
form_pre_render_details drupal/core/includes/form.inc Adds form element theming to details.
form_pre_render_email drupal/core/includes/form.inc Prepares a #type 'email' render element for theme_input().
form_pre_render_file drupal/core/includes/form.inc Prepares a #type 'file' render element for theme_input().
form_pre_render_group drupal/core/includes/form.inc Adds members of this group as actual elements for rendering.
form_pre_render_hidden drupal/core/includes/form.inc Prepares a #type 'hidden' render element for theme_input().
form_pre_render_image_button drupal/core/includes/form.inc Prepares a #type 'image_button' render element for theme_input().
form_pre_render_number drupal/core/includes/form.inc Prepares a #type 'number' render element for theme_input().
form_pre_render_password drupal/core/includes/form.inc Prepares a #type 'password' render element for theme_input().
form_pre_render_radio drupal/core/includes/form.inc Prepares a #type 'radio' render element for theme_input().
form_pre_render_range drupal/core/includes/form.inc Prepares a #type 'range' render element for theme_input().
form_pre_render_search drupal/core/includes/form.inc Prepares a #type 'search' render element for theme_input().
form_pre_render_tel drupal/core/includes/form.inc Prepares a #type 'tel' render element for theme_input().
form_pre_render_textfield drupal/core/includes/form.inc Prepares a #type 'textfield' render element for theme_input().
form_pre_render_url drupal/core/includes/form.inc Prepares a #type 'url' render element for theme_input().
form_pre_render_vertical_tabs drupal/core/includes/form.inc Prepares a vertical_tabs element for rendering.
form_process_actions drupal/core/includes/form.inc Processes a form actions container element.
form_process_autocomplete drupal/core/includes/form.inc Adds autocomplete functionality to elements with a valid #autocomplete_route_name.
form_process_button drupal/core/includes/form.inc Processes a form button element.
form_process_checkbox drupal/core/includes/form.inc Sets the #checked property of a checkbox element.
form_process_checkboxes drupal/core/includes/form.inc Processes a checkboxes form element.
form_process_container drupal/core/includes/form.inc Processes a container element.
form_process_file drupal/core/includes/form.inc Processes a file upload element, make use of #multiple if present.
form_process_group drupal/core/includes/form.inc Arranges elements into groups.
form_process_machine_name drupal/core/includes/form.inc Processes a machine-readable name form element.
form_process_password_confirm drupal/core/includes/form.inc Expand a password_confirm field into two text boxes.
form_process_pattern drupal/core/includes/form.inc #process callback for #pattern form element property.
form_process_radios drupal/core/includes/form.inc Expands a radios element into individual radio elements.
form_process_select drupal/core/includes/form.inc Processes a select list form element.
form_process_table drupal/core/includes/form.inc #process callback for #type 'table' to add tableselect support.
form_process_tableselect drupal/core/includes/form.inc Creates checkbox or radio elements to populate a tableselect table.
form_process_vertical_tabs drupal/core/includes/form.inc Creates a group formatted as vertical tabs.
form_process_weight drupal/core/includes/form.inc Expands a weight element into a select element.
form_select_options drupal/core/includes/form.inc Converts a select form element's options array into HTML.
form_set_cache Deprecated drupal/core/includes/form.inc Stores a form in the cache.
form_set_error Deprecated drupal/core/includes/form.inc Files an error against a form element.
form_set_value Deprecated drupal/core/includes/form.inc Changes submitted form values during form validation.
form_state_values_clean drupal/core/includes/form.inc Removes internal Form API elements and buttons from submitted form values.
form_type_checkboxes_value drupal/core/includes/form.inc Determines the value for a checkboxes form element.
form_type_checkbox_value drupal/core/includes/form.inc Determines the value for a checkbox form element.
form_type_image_button_value drupal/core/includes/form.inc Determines the value for an image button form element.
form_type_password_confirm_value drupal/core/includes/form.inc Determines the value for a password_confirm form element.
form_type_radios_value drupal/core/includes/form.inc Form value callback: Determines the value for a #type radios form element.
form_type_range_value drupal/core/includes/form.inc Determines the value for a range element.
form_type_select_value drupal/core/includes/form.inc Determines the value for a select form element.
form_type_tableselect_value drupal/core/includes/form.inc Determines the value for a tableselect form element.
form_type_table_value drupal/core/includes/form.inc Determines the value of a table form element.
form_type_textfield_value drupal/core/includes/form.inc Determines the value for a textfield form element.
form_type_token_value drupal/core/includes/form.inc Determines the value for form's token value.
form_validate_color drupal/core/includes/form.inc Form element validation handler for #type 'color'.
form_validate_email drupal/core/includes/form.inc Form element validation handler for #type 'email'.
form_validate_machine_name drupal/core/includes/form.inc Form element validation handler for machine_name elements.
form_validate_number drupal/core/includes/form.inc Form element validation handler for #type 'number'.
form_validate_pattern drupal/core/includes/form.inc #element_validate callback for #pattern form element property.
form_validate_table drupal/core/includes/form.inc #element_validate callback for #type 'table'.
form_validate_url drupal/core/includes/form.inc Form element validation handler for #type 'url'.
password_confirm_validate drupal/core/includes/form.inc Validates a password_confirm element.
template_preprocess_checkboxes drupal/core/includes/form.inc Prepares variables for checkboxes templates.
template_preprocess_details drupal/core/includes/form.inc Prepares variables for details element templates.
template_preprocess_fieldset drupal/core/includes/form.inc Prepares variables for fieldset element templates.
template_preprocess_form drupal/core/includes/form.inc Prepares variables for form templates.
template_preprocess_form_element drupal/core/includes/form.inc Returns HTML for a form element. Prepares variables for form element templates.
template_preprocess_form_element_label drupal/core/includes/form.inc Prepares variables for form label templates.
template_preprocess_input drupal/core/includes/form.inc Prepares variables for input templates.
template_preprocess_radios drupal/core/includes/form.inc Prepares variables for radios templates.
template_preprocess_select drupal/core/includes/form.inc Prepares variables for select element templates.
template_preprocess_textarea drupal/core/includes/form.inc Prepares variables for textarea templates.
template_preprocess_vertical_tabs drupal/core/includes/form.inc Prepares variables for vertical tabs templates.
theme_tableselect drupal/core/includes/form.inc Returns HTML for a table with radio buttons or checkboxes.
weight_value drupal/core/includes/form.inc Sets the value for a weight element, with zero as a default.
_form_set_attributes drupal/core/includes/form.inc Sets a form element's class attribute.

Classes

Namesort descending Location Description
FormBase drupal/core/lib/Drupal/Core/Form/FormBase.php Provides a base class for forms.
FormBuilder drupal/core/lib/Drupal/Core/Form/FormBuilder.php Provides form building and processing.

Interfaces

Namesort descending Location Description
FormInterface drupal/core/lib/Drupal/Core/Form/FormInterface.php Provides an interface for a Form.

File

drupal/core/includes/form.inc, line 21
Functions for form and batch generation and processing.