Functions to enable the processing and display of HTML forms.

Backdrop 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 backdrop_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 backdrop_form_submit() function.

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

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

$form = backdrop_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 = backdrop_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 backdrop_build_form() for documentation of $form_state keys.

File

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

Functions

Name Locationsort ascending Description
backdrop_get_form core/includes/form.inc Returns a renderable form array for a given form ID.
backdrop_build_form core/includes/form.inc Builds and processes a form for a given form ID.
form_state_defaults core/includes/form.inc Retrieves default values for the $form_state array.
backdrop_rebuild_form core/includes/form.inc Constructs a new $form from the information in $form_state.
form_get_cache core/includes/form.inc Fetches a form from the cache.
form_set_cache core/includes/form.inc Stores a form in the cache.
form_state_keys_no_cache core/includes/form.inc Returns an array of $form_state keys that shouldn't be cached.
form_load_include core/includes/form.inc Ensures an include file is loaded whenever the form is processed.
backdrop_form_submit core/includes/form.inc Retrieves, populates, and processes a form.
backdrop_retrieve_form core/includes/form.inc Retrieves the structured array that defines a given form.
backdrop_process_form core/includes/form.inc Processes a form submission.
backdrop_prepare_form core/includes/form.inc Prepares a structured form array.
_backdrop_invalid_token_set_form_error core/includes/form.inc Helper function to call form_set_error() if there is a token error.
backdrop_validate_form core/includes/form.inc Validates user-submitted form data in the $form_state array.
backdrop_redirect_form core/includes/form.inc Redirects the user to a URL after a form has been processed.
_form_validate core/includes/form.inc Performs validation on form elements.
form_execute_handlers core/includes/form.inc Executes custom validation and submission handlers for a given form.
form_set_error core/includes/form.inc Files an error against a form element.
form_clear_error core/includes/form.inc Clears all errors against all form elements made by form_set_error().
form_get_errors core/includes/form.inc Returns an associative array of all errors.
form_get_error core/includes/form.inc Returns the error message filed against the given form element.
form_error core/includes/form.inc Flags an element as having an error.
form_builder core/includes/form.inc Builds and processes all elements in the structured form array.
_form_builder_handle_input_element core/includes/form.inc Adds the #name and #value properties of an input element before rendering.
_form_element_triggered_scripted_submission core/includes/form.inc Detects if an element triggered the form submission via Ajax.
_form_button_was_clicked core/includes/form.inc Determines if a given button triggered the form submission.
form_state_values_clean core/includes/form.inc Removes internal Form API elements and buttons from submitted form values.
form_type_image_button_value core/includes/form.inc Determines the value for an image button form element.
form_type_checkbox_value core/includes/form.inc Determines the value for a checkbox form element.
form_type_checkboxes_value core/includes/form.inc Determines the value for a checkboxes form element.
form_type_radios_value core/includes/form.inc Form value callback: Determines the value for a #type radios form element.
form_type_tableselect_value core/includes/form.inc Determines the value for a tableselect form element.
form_type_password_confirm_value core/includes/form.inc Determines the value for a password_confirm form element.
form_type_select_value core/includes/form.inc Determines the value for a select form element.
form_type_textarea_value core/includes/form.inc Determines the value for a textarea form element.
form_type_textfield_value core/includes/form.inc Determines the value for a textfield form element.
form_type_token_value core/includes/form.inc Determines the value for form's token value.
form_set_value core/includes/form.inc Changes submitted form values during form validation.
form_options_flatten core/includes/form.inc Allows PHP array processing of multiple select options with the same value.
_form_options_flatten core/includes/form.inc Iterates over an array and returns a flat array with duplicate keys removed.
form_process_select core/includes/form.inc Processes a select list form element.
theme_select core/includes/form.inc Returns HTML for a select form element.
form_select_options core/includes/form.inc Converts an array of options into HTML, for use in select list form elements.
form_get_options core/includes/form.inc Returns the indexes of a select element's options matching a given key.
theme_fieldset core/includes/form.inc Returns HTML for a fieldset form element and its children.
theme_radio core/includes/form.inc Returns HTML for a radio button form element.
form_process_password_confirm core/includes/form.inc Expand a password_confirm field into two text boxes.
password_confirm_validate core/includes/form.inc Validates a password_confirm element.
theme_date core/includes/form.inc Returns HTML for a date selection form element.
form_process_date core/includes/form.inc Expands a date element into year, month, and day select elements.
date_validate core/includes/form.inc Validates the date type to prevent invalid dates (e.g., February 30, 2006).
map_month core/includes/form.inc Renders a month name for display.
theme_html_date core/includes/form.inc Returns html5 markup for a date input form element.
theme_html_time core/includes/form.inc Returns html5 markup for a time input form element.
theme_html_datetime core/includes/form.inc Returns html5 markup for a combined date and time form element.
form_process_html_datetime core/includes/form.inc Combine html_date and html_time form elements.
html_date_validate core/includes/form.inc Validate a date string.
html_date_or_time_value_callback core/includes/form.inc Element value callback for html_date and html_time elements.
html_time_validate core/includes/form.inc Validate a time string.
html_datetime_validate core/includes/form.inc Validate a combined date and time array.
weight_value core/includes/form.inc Sets the value for a weight element, with zero as a default.
form_process_radios core/includes/form.inc Expands a radios element into individual radio elements.
theme_checkbox core/includes/form.inc Returns HTML for a checkbox form element.
form_pre_render_conditional_form_element core/includes/form.inc Adds additional customization to a form element when its title or description is set.
form_process_checkbox core/includes/form.inc Sets the #checked property of a checkbox element.
form_process_checkboxes core/includes/form.inc Processes a checkboxes form element.
form_process_actions core/includes/form.inc Processes a form actions container element.
form_process_button core/includes/form.inc Processes a form button element.
form_process_container core/includes/form.inc Processes a container element.
theme_container core/includes/form.inc Returns HTML to wrap child elements in a container.
form_process_details core/includes/form.inc Processes a details element.
theme_details core/includes/form.inc Returns HTML to wrap children in a details element.
theme_tableselect core/includes/form.inc Returns HTML for a table with radio buttons or checkboxes.
form_process_tableselect core/includes/form.inc Creates checkbox or radio elements to populate a tableselect table.
form_process_machine_name core/includes/form.inc Processes a machine-readable name form element.
form_validate_machine_name core/includes/form.inc Form element validation handler for machine_name elements.
form_process_fieldset core/includes/form.inc Arranges fieldsets into groups.
form_pre_render_fieldset core/includes/form.inc Adds members of this group as actual elements for rendering.
form_process_vertical_tabs core/includes/form.inc Creates a group formatted as vertical tabs.
theme_vertical_tabs core/includes/form.inc Returns HTML for an element's children fieldsets as vertical tabs.
theme_submit core/includes/form.inc Returns HTML for a submit button form element.
theme_button core/includes/form.inc Returns HTML for a button form element.
theme_image_button core/includes/form.inc Returns HTML for an image button form element.
theme_hidden core/includes/form.inc Returns HTML for a hidden form element.
form_process_autocomplete core/includes/form.inc Process function to prepare autocomplete data.
theme_textfield core/includes/form.inc Returns HTML for a textfield form element.
theme_email core/includes/form.inc Returns HTML for an email form element.
form_validate_email core/includes/form.inc Form element validation handler for #type 'email'.
theme_search core/includes/form.inc Returns HTML for a search form element.
theme_tel core/includes/form.inc Returns HTML for a tel form element.
theme_url core/includes/form.inc Returns HTML for a URL form element.
form_validate_url core/includes/form.inc Form element validation handler for #type 'url'.
form_validate_color core/includes/form.inc Form element validation handler for #type 'color'.
theme_color core/includes/form.inc Returns HTML for a color form element.
theme_number core/includes/form.inc Returns HTML for a number form element.
form_validate_number core/includes/form.inc Form element validation handler for #type 'number'.
theme_range core/includes/form.inc Returns HTML for a range form element.
theme_form core/includes/form.inc Returns HTML for a form.
theme_textarea core/includes/form.inc Returns HTML for a textarea form element.
theme_password core/includes/form.inc Returns HTML for a password form element.
form_process_weight core/includes/form.inc Expands a weight element into a select element.
theme_file core/includes/form.inc Returns HTML for a file upload form element.
theme_form_element core/includes/form.inc Returns HTML for a form element.
theme_form_required_marker core/includes/form.inc Returns HTML for a marker for required form elements.
theme_form_element_label core/includes/form.inc Returns HTML for a form element label and required marker.
_form_set_class core/includes/form.inc Sets a form element's class attribute.