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