Form API in Drupal 8

The Drupal 8 Form API is largely similar to the Drupal 7 Form API. The forms are still represented with nested render array structures and there is a separate validation and submission step. There are some new (HTML 5) elements available and the integration of these components into the rest of the Drupal system changed a bit.

New (HTML 5) elements

Check out system_element_info() for all the core provided elements. There are new HTML 5 elements like '#type' => 'tel', '#type' => 'email', '#type' => 'number', '#type' => 'date', '#type' => 'url', '#type' => 'search', '#type' => 'range', etc. Using these elements as opposed to requesting data in plain textfields is preferable because devices can pull up the proper input methods for them, such as when a telephone number is requested, the dialpad would show up on a device.

Comparison of Form Building Modules

Drupal has a lot of modules aimed at helping site builders and users add forms to their sites. What follows is a rough comparison of 4 of them. If there are any I've missed, please add them.

Webform

Webform is a module designed to allow you to add custom forms to the front-end of your site. Each form is stored against a node, so you add new forms to your site as if you were adding content. It's useful for things like Survey websites or just where you want a couple of forms that differ from the standard contact form.

Pros

  • Webform has been around for a long time, its very well established and has a big following.
  • Webform can make a wide variety of forms with lots of different elements available.
  • Webforms inherit all the cool access stuff that nodes have.

Cons

  • Webform submissions are stored in their own custom way - not using any of the standard drupal API's.
  • Drupal 7 has lots of cool Field Types available in contrib that webform cannot utilise.
  • There is little or no integration with alot of modules because the submissions do not use entities.
  • Webform cannot (without some magic) be used to edit nodes or comments.

Using form_alter to change the default value of a date

If you need to set a default value for an exposed views filter, you can do it like this:

this example code will set a ranged date to have a default value of -30 days for the start date, and today for the end date

Forms API - Modify Forms with hook_form_alter()

Drupal 7 forms that modules create can be changed by other modules and even themes with the help of Drupal FAPI hooks system. See Drupal 7 Hooks for a list of Drupal system hooks. The hook that allows to edit the existing forms is hook_form_alter. See the hook_form_alter() documentation at Drupal API site.

The syntax is hook_form_alter(&$form, &$form_state, $form_id).

In this hook call, $form is the array of form elements (see Drupal 7 Form API Overview article). $form_state has the keyed array of the state of the form, that can change on form submission or in multi-step forms. And an important parameter is $form_id, which has in it the unique name of the form. Drupal core will cycle through all the registered forms, passing their initial array, state, and unique id to this hook function.

Example:

Creating a builder function to generate a form

Form workflow usually follows these stages:

  1. Declaration of a form and its elements in a function
  2. Modification of existing forms with the FAPI hook system
  3. Theming of forms
  4. Form validation and submission

Forms are represented as arrays in form builder functions. Each item within the $form array on api.drupal.org corresponds either to a form element (an input or other HTML on the rendered form) or an element property (meta-data used by FAPI during the rendering or processing of elements). A property has a key name that begins with a "#", while an element does not.

Example

In this example, we have a module named mymodule and we want to declare a form builder function in it. The form declaration function receives at least two parameters:

  • $form - An array of elements and element properties
  • &$form_state - An array containing information about the current state of this form while a user is filling it out and submitting it. Importantly, this includes the values that the user may have entered into the form.

This simple form has a text field for the user name and a submit button.

<?php
/**
* Create a new form
*/

Multi-step forms

<< mforms project page

Installation and configuration

Mforms is a library, so by itself it does not provide any functionality (besides the real-life examples in the mforms example module). Therefore there is no configuration or installation besides enabling the module in the module list.

Basic usage

Included module mforms_example contains several real life examples that are documented in code. To find out what it does visit /mforms page after you enable mforms_example module.

Mforms architecture

For faster dive into mforms here is the basic architecture:

Prerequisites

STORE_KEY - not just identifies the storage slot for submitted values, it represents the identifier of whole multi-step form implementation.

Steps file - The file where individual form steps with their validate and submit callbacks reside. See mforms_example/mforms/mforms_example.session_store_example.inc for demonstration. This file must be named in the following pattern: MODULE_NAME.STORE_KEY.inc and placed in "mforms" directory of the module in which you are implementing the multi step form.

Store object - MformsIstore implementation responsible for storing submitted values and internal mforms data needed to control the stepping process.

Pages

Subscribe with RSS Subscribe to RSS - form api