Drupal e-Commerce API

Form generation

• Drupal 6.x
• Drupal 7.x

Functions to enable the processing and display of HTML forms.

Drupal uses these functions to achieve consistency in its form processing and presentation, while simplifying code and reducing the amount of HTML that must be explicitly generated by modules.

The primary function used with forms is drupal_get_form(), which is used for forms presented interactively to a user. Forms can also be built and submitted programmatically without any user input using the drupal_form_submit() function.

drupal_get_form() handles retrieving, processing, and displaying a rendered HTML form for modules automatically.

Here is an example of how to use drupal_get_form() and a form builder function:

<?php

$form = drupal_get_form('my_module_example_form');
...
function my_module_example_form($form, &$form_state) {
$form['submit'] = array(
'#type' => 'submit',
'#value' => t('Submit'),
);
return $form;
}
function my_module_example_form_validate($form, &$form_state) {
// Validation logic.
}
function my_module_example_form_submit($form, &$form_state) {
// Submission logic.
}

?>

Or with any number of additional arguments:

<?php

$extra = "extra";
$form = drupal_get_form('my_module_example_form', $extra);
...
function my_module_example_form($form, &$form_state, $extra) {
$form['submit'] = array(
'#type' => 'submit',
'#value' => $extra,
);
return $form;
}

?>

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 section of the handbook. 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 functions, $form_state is the primary influence on the processing of the form and is passed by reference to most functions, so they use it to communicate with the form system and each other.

The $form_state keys are:

• 'values': An associative array of values submitted to the form. The validation functions and submit functions use this array for nearly all their decision making. (Note that #tree determines whether the values are a flat array or an array whose structure parallels the $form array.)
• 'rebuild': If the submit function sets $form_state['rebuild'] to TRUE, submission is not completed and instead the form is rebuilt using any information that the submit function has made available to the form builder function via $form_state. This is commonly used for wizard-style multi-step forms, add-more buttons, and the like. For further information see drupal_build_form().
• 'redirect': a URL that will be used to redirect the form on submission. See drupal_redirect_form() for complete information.
• 'storage': $form_state['storage'] is not a special key, and no specific support is provided for it in the Form API, but by tradition it was the location where application-specific data was stored for communication between the submit, validation, and form builder functions, especially in a multi-step-style form. Form implementations may use any key(s) within $form_state (other than the keys listed here and other reserved ones used by Form API internals) for this kind of storage. The recommended way to ensure that the chosen key doesn't conflict with ones used by the Form API or other modules is to use the module name as the key name or a prefix for the key name. For example, the Node module uses $form_state['node'] in node editing forms to store information about the node being edited, and this information stays available across successive clicks of the "Preview" button as well as when the "Save" button is finally clicked.
• 'temporary': Since values for all non-reserved keys in $form_state persist throughout a multistep form sequence, the Form API provides the 'temporary' key for modules to use for communicating information across form-related functions during a single page request only. There is no use-case for this functionality in core.
• 'triggering_element': (read-only) The form element that triggered submission. This is the same as the deprecated $form_state['clicked_button']. It is the element that caused submission, which may or may not be a button (in the case of AJAX forms.) This is often used to distinguish between various buttons in a submit handler, and is also used in AJAX handlers.
• 'cache': The typical form workflow involves two page requests. During the first page request, a form is built and returned for the user to fill in. Then the user fills the form in and submits it, triggering a second page request in which the form must be built and processed. By default, $form and $form_state are built from scratch during each of these page requests. In some special use-cases, it is necessary or desired to persist the $form and $form_state variables from the initial page request to the one that processes the submission. A form builder function can set 'cache' to TRUE to do this. One example where this is needed is to handle AJAX submissions, so ajax_process_form() sets this for all forms that include an element with a #ajax property. (In AJAX, the handler has no way to build the form itself, so must rely on the cached version created on each page load, so it's a classic example of this use case.) Note that the persistence of $form and $form_state across successive submissions of a multi-step form happens automatically regardless of the value for 'cache'.
• 'input': The array of values as they were submitted by the user. These are raw and unvalidated, so should not be used without a thorough understanding of security implications. In almost all cases, code should use the data in the 'values' array exclusively. The most common use of this key is for multi-step forms that need to clear some of the user input when setting 'rebuild'.

Functions