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.

File

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

Functions

Namesort descending Location Description
drupal_build_form drupal/core/includes/form.inc Builds and processes a form for a given form ID.
drupal_form_submit drupal/core/includes/form.inc Retrieves, populates, and processes a form.
drupal_get_form drupal/core/includes/form.inc Returns a renderable form array for a given form ID.
drupal_prepare_form drupal/core/includes/form.inc Prepares a structured form array.
drupal_process_form drupal/core/includes/form.inc Processes a form submission.
drupal_rebuild_form drupal/core/includes/form.inc Constructs a new $form from the information in $form_state.
drupal_redirect_form drupal/core/includes/form.inc Redirects the user to a URL after a form has been processed.
drupal_retrieve_form drupal/core/includes/form.inc Retrieves the structured array that defines a given form.
drupal_validate_form drupal/core/includes/form.inc Validates user-submitted form data in the $form_state array.
form_builder drupal/core/includes/form.inc Builds and processes all elements in the structured form array.
form_clear_error drupal/core/includes/form.inc Clears all errors against all form elements made by form_set_error().
form_error drupal/core/includes/form.inc Flags an element as having an error.
form_execute_handlers drupal/core/includes/form.inc Executes custom validation and submission handlers for a given form.
form_get_cache drupal/core/includes/form.inc Fetches a form from the cache.
form_get_error drupal/core/includes/form.inc Returns the error message filed against the given form element.
form_get_errors 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 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_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_path.
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 drupal/core/includes/form.inc Stores a form in the cache.
form_set_error drupal/core/includes/form.inc Files an error against a form element.
form_set_value drupal/core/includes/form.inc Changes submitted form values during form validation.
form_state_defaults drupal/core/includes/form.inc Retrieves default values for the $form_state array.
form_state_keys_no_cache drupal/core/includes/form.inc Returns an array of $form_state keys that shouldn't be cached.
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_input drupal/core/includes/form.inc Preprocesses variables for theme_input().
theme_checkboxes drupal/core/includes/form.inc Returns HTML for a set of checkbox form elements.
theme_container drupal/core/includes/form.inc Returns HTML to wrap child elements in a container.
theme_date drupal/core/includes/form.inc Returns HTML for an #date form element.
theme_details drupal/core/includes/form.inc Returns HTML for a details form element and its children.
theme_fieldset drupal/core/includes/form.inc Returns HTML for a fieldset form element and its children.
theme_form drupal/core/includes/form.inc Returns HTML for a form.
theme_form_element drupal/core/includes/form.inc Returns HTML for a form element.
theme_form_element_label drupal/core/includes/form.inc Returns HTML for a form element label and required marker.
theme_form_required_marker drupal/core/includes/form.inc Returns HTML for a marker for required form elements.
theme_input drupal/core/includes/form.inc Returns HTML for an input form element.
theme_radios drupal/core/includes/form.inc Returns HTML for a set of radio button form elements.
theme_select drupal/core/includes/form.inc Returns HTML for a select form element.
theme_tableselect drupal/core/includes/form.inc Returns HTML for a table with radio buttons or checkboxes.
theme_textarea drupal/core/includes/form.inc Returns HTML for a textarea form element.
theme_vertical_tabs drupal/core/includes/form.inc Returns HTML for an element's children details as vertical tabs.
weight_value drupal/core/includes/form.inc Sets the value for a weight element, with zero as a default.
_drupal_form_id drupal/core/includes/form.inc Determines the form ID.
_form_builder_handle_input_element drupal/core/includes/form.inc Adds the #name and #value properties of an input element before rendering.
_form_button_was_clicked drupal/core/includes/form.inc Determines if a given button triggered the form submission.
_form_element_triggered_scripted_submission drupal/core/includes/form.inc Detects if an element triggered the form submission via Ajax.
_form_options_flatten drupal/core/includes/form.inc Iterates over an array and returns a flat array with duplicate keys removed.
_form_set_attributes drupal/core/includes/form.inc Sets a form element's class attribute.
_form_validate drupal/core/includes/form.inc Performs validation on form elements.