Form generation

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:

$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:

$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

NameLocationDescription
date_validateincludes/form.incValidates the date type to prevent invalid dates (e.g., February 30, 2006).
drupal_build_formincludes/form.incBuilds and process a form based on a form id.
drupal_form_submitincludes/form.incRetrieves, populates, and processes a form.
drupal_get_formincludes/form.incReturns a renderable form array for a given form ID.
drupal_prepare_formincludes/form.incPrepares a structured form array.
drupal_process_formincludes/form.incProcesses a form submission.
drupal_rebuild_formincludes/form.incConstructs a new $form from the information in $form_state.
drupal_redirect_formincludes/form.incRedirects the user to a URL after a form has been processed.
drupal_retrieve_formincludes/form.incRetrieves the structured array that defines a given form.
drupal_validate_formincludes/form.incValidates user-submitted form data in the $form_state array.
element_validate_integerincludes/form.incForm element validation handler for integer elements.
element_validate_integer_positiveincludes/form.incForm element validation handler for integer elements that must be positive.
element_validate_numberincludes/form.incForm element validation handler for number elements.
form_builderincludes/form.incBuilds and processes all elements in the structured form array.
form_clear_errorincludes/form.incClears all errors against all form elements made by form_set_error().
form_errorincludes/form.incFlags an element as having an error.
form_execute_handlersincludes/form.incExecutes custom validation and submission handlers for a given form.
form_get_cacheincludes/form.incFetches a form from cache.
form_get_errorincludes/form.incReturns the error message filed against the given form element.
form_get_errorsincludes/form.incReturns an associative array of all errors.
form_get_optionsincludes/form.incReturns the indexes of a select element's options matching a given key.
form_load_includeincludes/form.incEnsures an include file is loaded whenever the form is processed.
form_options_flattenincludes/form.incAllows PHP array processing of multiple select options with the same value.
form_pre_render_conditional_form_elementincludes/form.incAdds form element theming to an element if its title or description is set.
form_pre_render_fieldsetincludes/form.incAdds members of this group as actual elements for rendering.
form_process_actionsincludes/form.incProcesses a form actions container element.
form_process_checkboxincludes/form.incSets the #checked property of a checkbox element.
form_process_checkboxesincludes/form.incProcesses a checkboxes form element.
form_process_containerincludes/form.incProcesses a container element.
form_process_dateincludes/form.incExpands a date element into year, month, and day select elements.
form_process_fieldsetincludes/form.incArranges fieldsets into groups.
form_process_machine_nameincludes/form.incProcesses a machine-readable name form element.
form_process_password_confirmincludes/form.incExpand a password_confirm field into two text boxes.
form_process_radiosincludes/form.incExpands a radios element into individual radio elements.
form_process_selectincludes/form.incProcesses a select list form element.
form_process_tableselectincludes/form.incCreates checkbox or radio elements to populate a tableselect table.
form_process_vertical_tabsincludes/form.incCreates a group formatted as vertical tabs.
form_process_weightincludes/form.incExpands a weight element into a select element.
form_select_optionsincludes/form.incConverts a select form element's options array into HTML.
form_set_cacheincludes/form.incStores a form in the cache.
form_set_errorincludes/form.incFiles an error against a form element.
form_set_valueincludes/form.incChanges submitted form values during form validation.
form_state_defaultsincludes/form.incRetrieves default values for the $form_state array.
form_state_keys_no_cacheincludes/form.incReturns an array of $form_state keys that shouldn't be cached.
form_state_values_cleanincludes/form.incRemoves internal Form API elements and buttons from submitted form values.
form_type_checkboxes_valueincludes/form.incDetermines the value for a checkboxes form element.
form_type_checkbox_valueincludes/form.incDetermines the value for a checkbox form element.
form_type_image_button_valueincludes/form.incDetermines the value for an image button form element.
form_type_password_confirm_valueincludes/form.incDetermines the value for a password_confirm form element.
form_type_radios_valueincludes/form.incForm value callback: Determines the value for a #type radios form element.
form_type_select_valueincludes/form.incDetermines the value for a select form element.
form_type_tableselect_valueincludes/form.incDetermines the value for a tableselect form element.
form_type_textfield_valueincludes/form.incDetermines the value for a textfield form element.
form_type_token_valueincludes/form.incDetermines the value for form's token value.
form_validate_machine_nameincludes/form.incForm element validation handler for machine_name elements.
map_monthincludes/form.incHelper function for usage with drupal_map_assoc to display month names.
password_confirm_validateincludes/form.incValidates a password_confirm element.
theme_buttonincludes/form.incReturns HTML for a button form element.
theme_checkboxincludes/form.incReturns HTML for a checkbox form element.
theme_checkboxesincludes/form.incReturns HTML for a set of checkbox form elements.
theme_containerincludes/form.incReturns HTML to wrap child elements in a container.
theme_dateincludes/form.incReturns HTML for a date selection form element.
theme_fieldsetincludes/form.incReturns HTML for a fieldset form element and its children.
theme_fileincludes/form.incReturns HTML for a file upload form element.
theme_formincludes/form.incReturns HTML for a form.
theme_form_elementincludes/form.incReturns HTML for a form element.
theme_form_element_labelincludes/form.incReturns HTML for a form element label and required marker.
theme_form_required_markerincludes/form.incReturns HTML for a marker for required form elements.
theme_hiddenincludes/form.incReturns HTML for a hidden form element.
theme_image_buttonincludes/form.incReturns HTML for an image button form element.
theme_passwordincludes/form.incReturns HTML for a password form element.
theme_radioincludes/form.incReturns HTML for a radio button form element.
theme_radiosincludes/form.incReturns HTML for a set of radio button form elements.
theme_selectincludes/form.incReturns HTML for a select form element.
theme_submitincludes/form.incReturns HTML for a submit button form element.
theme_tableselectincludes/form.incReturns HTML for a table with radio buttons or checkboxes.
theme_textareaincludes/form.incReturns HTML for a textarea form element.
theme_textfieldincludes/form.incReturns HTML for a textfield form element.
theme_vertical_tabsincludes/form.incReturns HTML for an element's children fieldsets as vertical tabs.
weight_valueincludes/form.incSets the value for a weight element, with zero as a default.
_form_builder_handle_input_elementincludes/form.incAdds the #name and #value properties of an input element before rendering.
_form_button_was_clickedincludes/form.incDetermines if a given button triggered the form submission.
_form_element_triggered_scripted_submissionincludes/form.incDetects if an element triggered the form submission via Ajax.
_form_options_flattenincludes/form.incIterates over an array and returns a flat array with duplicate keys removed.
_form_set_classincludes/form.incSets a form element's class attribute.
_form_validateincludes/form.incPerforms validation on form elements.

File

includes/form.inc, line 26
Functions for form and batch generation and processing.