Form generation

  1. drupal
    1. 8
    2. 6
    3. 7

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 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 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.

See drupal_build_form() for documentation of $form_state keys.

Functions & methods

NameDescription
date_validateValidates the date type to stop dates like February 30, 2006.
drupal_build_formBuild and process a form based on a form id.
drupal_form_submitRetrieves, populates, and processes a form.
drupal_get_formWrapper for drupal_build_form() for use when $form_state is not needed.
drupal_prepare_formPrepares a structured form array by adding required elements, executing any hook_form_alter functions, and optionally inserting a validation token to prevent tampering.
drupal_process_formProcesses a form submission.
drupal_rebuild_formConstructs a new $form from the information in $form_state.
drupal_redirect_formRedirects the user to a URL after a form has been processed.
drupal_retrieve_formRetrieves the structured array that defines a given form.
drupal_validate_formValidates user-submitted form data from the $form_state using the validate functions defined in a structured form array.
element_validate_integerHelper form element validator: integer.
element_validate_integer_positiveHelper form element validator: integer > 0.
element_validate_numberHelper form element validator: number.
form_builderWalk through the structured form array, adding any required properties to each element and mapping the incoming input data to the proper elements. Also, execute any #process handlers attached to a specific element.
form_clear_errorClear all errors against all form elements made by form_set_error().
form_errorFlag an element as having an error.
form_execute_handlersA helper function used to execute custom validation and submission handlers for a given form. Button-specific handlers are checked first. If none exist, the function falls back to form-level handlers.
form_get_cacheFetch a form from cache.
form_get_errorReturns the error message filed against the given form element.
form_get_errorsReturn an associative array of all errors.
form_get_optionsTraverses a select element's #option array looking for any values that hold the given key. Returns an array of indexes that match.
form_load_includeLoads an include file and makes sure it is loaded whenever the form is processed.
form_options_flattenAllows PHP array processing of multiple select options with the same value.
form_pre_render_conditional_form_elementAdd form_element theming to an element if title or description is set.
form_pre_render_fieldsetAdds members of this group as actual elements for rendering.
form_process_actionsProcesses a form actions container element.
form_process_checkboxSets the #checked property of a checkbox element.
form_process_checkboxes
form_process_containerProcesses a container element.
form_process_dateRoll out a single date element.
form_process_fieldsetAdds fieldsets to the specified group or adds group members to this fieldset.
form_process_machine_nameProcesses a machine-readable name form element.
form_process_password_confirmExpand a password_confirm field into two text boxes.
form_process_radiosRoll out a single radios element to a list of radios, using the options array as index.
form_process_selectProcesses a select list form element.
form_process_tableselectCreate the correct amount of checkbox or radio elements to populate the table.
form_process_vertical_tabsCreates a group formatted as vertical tabs.
form_process_weightExpand weight elements into selects.
form_select_optionsConverts a select form element's options array into an HTML.
form_set_cacheStore a form in the cache.
form_set_errorFiles an error against a form element.
form_set_valueChange submitted form values during form validation.
form_state_defaultsRetrieve default values for the $form_state array.
form_state_keys_no_cacheReturns an array of $form_state keys that shouldn't be cached.
form_state_values_cleanRemoves internal Form API elements and buttons from submitted form values.
form_type_checkboxes_valueHelper function to determine the value for a checkboxes form element.
form_type_checkbox_valueHelper function to determine the value for a checkbox form element.
form_type_image_button_valueHelper function to determine the value for an image button form element.
form_type_password_confirm_valueHelper function to determine the value for a password_confirm form element.
form_type_select_valueHelper function to determine the value for a select form element.
form_type_tableselect_valueHelper function to determine the value for a tableselect form element.
form_type_textfield_valueHelper function to determine the value for a textfield form element.
form_type_token_valueHelper function to determine the value for form's token value.
form_validate_machine_nameForm element validation handler for #type 'machine_name'.
map_monthHelper function for usage with drupal_map_assoc to display month names.
password_confirm_validateValidate password_confirm element.
theme_buttonReturns HTML for a button form element.
theme_checkboxReturns HTML for a checkbox form element.
theme_checkboxesReturns HTML for a set of checkbox form elements.
theme_containerReturns HTML to wrap child elements in a container.
theme_dateReturns HTML for a date selection form element.
theme_fieldsetReturns HTML for a fieldset form element and its children.
theme_fileReturns HTML for a file upload form element.
theme_formReturns HTML for a form.
theme_form_elementReturns HTML for a form element.
theme_form_element_labelReturns HTML for a form element label and required marker.
theme_form_required_markerReturns HTML for a marker for required form elements.
theme_hiddenReturns HTML for a hidden form element.
theme_image_buttonReturns HTML for an image button form element.
theme_passwordReturns HTML for a password form element.
theme_radioReturns HTML for a radio button form element.
theme_radiosReturns HTML for a set of radio button form elements.
theme_selectReturns HTML for a select form element.
theme_submitReturns HTML for a submit button form element.
theme_tableselectReturns HTML for a table with radio buttons or checkboxes.
theme_textareaReturns HTML for a textarea form element.
theme_textfieldReturns HTML for a textfield form element.
theme_vertical_tabsReturns HTML for an element's children fieldsets as vertical tabs.
weight_valueIf no default value is set for weight select boxes, use 0.
_form_builder_handle_input_elementPopulate the #value and #name properties of input elements so they can be processed and rendered.
_form_button_was_clickedHelper function to handle the convoluted logic of button click detection.
_form_element_triggered_scripted_submissionHelper function to handle the convoluted logic of button click detection.
_form_options_flattenHelper function for form_options_flatten().
_form_set_classSets a form element's class attribute.
_form_validatePerforms validation on form elements. First ensures required fields are completed, #maxlength is not exceeded, and selected options were in the list of options given to the user. Then calls user-defined validators.

includes/form.inc, line 22