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.
Name | Location | Description |
---|---|---|
_drupal_form_id |
drupal/ |
Determines the form ID. |
drupal_get_form |
drupal/ |
Returns a renderable form array for a given form ID. |
drupal_build_form |
drupal/ |
Builds and processes a form for a given form ID. |
form_state_defaults |
drupal/ |
Retrieves default values for the $form_state array. |
drupal_rebuild_form |
drupal/ |
Constructs a new $form from the information in $form_state. |
form_get_cache |
drupal/ |
Fetches a form from the cache. |
form_set_cache |
drupal/ |
Stores a form in the cache. |
form_state_keys_no_cache |
drupal/ |
Returns an array of $form_state keys that shouldn't be cached. |
form_load_include |
drupal/ |
Ensures an include file is loaded whenever the form is processed. |
drupal_form_submit |
drupal/ |
Retrieves, populates, and processes a form. |
drupal_retrieve_form |
drupal/ |
Retrieves the structured array that defines a given form. |
drupal_process_form |
drupal/ |
Processes a form submission. |
drupal_prepare_form |
drupal/ |
Prepares a structured form array. |
drupal_validate_form |
drupal/ |
Validates user-submitted form data in the $form_state array. |
drupal_redirect_form |
drupal/ |
Redirects the user to a URL after a form has been processed. |
_form_validate |
drupal/ |
Performs validation on form elements. |
form_execute_handlers |
drupal/ |
Executes custom validation and submission handlers for a given form. |
form_set_error |
drupal/ |
Files an error against a form element. |
form_clear_error |
drupal/ |
Clears all errors against all form elements made by form_set_error(). |
form_get_errors |
drupal/ |
Returns an associative array of all errors. |
form_get_error |
drupal/ |
Returns the error message filed against the given form element. |
form_error |
drupal/ |
Flags an element as having an error. |
form_builder |
drupal/ |
Builds and processes all elements in the structured form array. |
_form_builder_handle_input_element |
drupal/ |
Adds the #name and #value properties of an input element before rendering. |
_form_element_triggered_scripted_submission |
drupal/ |
Detects if an element triggered the form submission via Ajax. |
_form_button_was_clicked |
drupal/ |
Determines if a given button triggered the form submission. |
form_state_values_clean |
drupal/ |
Removes internal Form API elements and buttons from submitted form values. |
form_type_image_button_value |
drupal/ |
Determines the value for an image button form element. |
form_type_checkbox_value |
drupal/ |
Determines the value for a checkbox form element. |
form_type_checkboxes_value |
drupal/ |
Determines the value for a checkboxes form element. |
form_type_table_value |
drupal/ |
Determines the value of a table form element. |
form_type_radios_value |
drupal/ |
Form value callback: Determines the value for a #type radios form element. |
form_type_tableselect_value |
drupal/ |
Determines the value for a tableselect form element. |
form_type_password_confirm_value |
drupal/ |
Determines the value for a password_confirm form element. |
form_type_select_value |
drupal/ |
Determines the value for a select form element. |
form_type_textfield_value |
drupal/ |
Determines the value for a textfield form element. |
form_type_token_value |
drupal/ |
Determines the value for form's token value. |
form_set_value |
drupal/ |
Changes submitted form values during form validation. |
form_options_flatten |
drupal/ |
Allows PHP array processing of multiple select options with the same value. |
_form_options_flatten |
drupal/ |
Iterates over an array and returns a flat array with duplicate keys removed. |
form_process_select |
drupal/ |
Processes a select list form element. |
theme_select |
drupal/ |
Returns HTML for a select form element. |
form_select_options |
drupal/ |
Converts a select form element's options array into HTML. |
form_get_options |
drupal/ |
Returns the indexes of a select element's options matching a given key. |
theme_fieldset |
drupal/ |
Returns HTML for a fieldset form element and its children. |
theme_details |
drupal/ |
Returns HTML for a details form element and its children. |
form_pre_render_radio |
drupal/ |
Prepares a #type 'radio' render element for theme_input(). |
theme_radios |
drupal/ |
Returns HTML for a set of radio button form elements. |
form_process_password_confirm |
drupal/ |
Expand a password_confirm field into two text boxes. |
password_confirm_validate |
drupal/ |
Validates a password_confirm element. |
theme_date |
drupal/ |
Returns HTML for an #date form element. |
weight_value |
drupal/ |
Sets the value for a weight element, with zero as a default. |
form_process_radios |
drupal/ |
Expands a radios element into individual radio elements. |
form_pre_render_checkbox |
drupal/ |
Prepares a #type 'checkbox' render element for theme_input(). |
theme_checkboxes |
drupal/ |
Returns HTML for a set of checkbox form elements. |
form_pre_render_conditional_form_element |
drupal/ |
Adds form element theming to an element if its title or description is set. |
form_process_button |
drupal/ |
Processes a form button element. |
form_process_checkbox |
drupal/ |
Sets the #checked property of a checkbox element. |
form_process_checkboxes |
drupal/ |
Processes a checkboxes form element. |
form_process_actions |
drupal/ |
Processes a form actions container element. |
form_pre_render_actions_dropbutton |
drupal/ |
#pre_render callback for #type 'actions'. |
form_process_pattern |
drupal/ |
#process callback for #pattern form element property. |
form_validate_pattern |
drupal/ |
#element_validate callback for #pattern form element property. |
form_process_container |
drupal/ |
Processes a container element. |
theme_container |
drupal/ |
Returns HTML to wrap child elements in a container. |
theme_tableselect |
drupal/ |
Returns HTML for a table with radio buttons or checkboxes. |
form_process_tableselect |
drupal/ |
Creates checkbox or radio elements to populate a tableselect table. |
form_process_table |
drupal/ |
#process callback for #type 'table' to add tableselect support. |
form_validate_table |
drupal/ |
#element_validate callback for #type 'table'. |
form_process_machine_name |
drupal/ |
Processes a machine-readable name form element. |
form_validate_machine_name |
drupal/ |
Form element validation handler for machine_name elements. |
form_process_group |
drupal/ |
Arranges elements into groups. |
form_pre_render_details |
drupal/ |
Adds form element theming to details. |
form_pre_render_group |
drupal/ |
Adds members of this group as actual elements for rendering. |
form_process_vertical_tabs |
drupal/ |
Creates a group formatted as vertical tabs. |
form_pre_render_vertical_tabs |
drupal/ |
Prepares a vertical_tabs element for rendering. |
theme_vertical_tabs |
drupal/ |
Returns HTML for an element's children details as vertical tabs. |
form_process_autocomplete |
drupal/ |
Adds autocomplete functionality to elements with a valid #autocomplete_path. |
template_preprocess_input |
drupal/ |
Preprocesses variables for theme_input(). |
theme_input |
drupal/ |
Returns HTML for an input form element. |
form_pre_render_button |
drupal/ |
Prepares a #type 'button' render element for theme_input(). |
form_pre_render_image_button |
drupal/ |
Prepares a #type 'image_button' render element for theme_input(). |
form_pre_render_hidden |
drupal/ |
Prepares a #type 'hidden' render element for theme_input(). |
form_pre_render_textfield |
drupal/ |
Prepares a #type 'textfield' render element for theme_input(). |
form_pre_render_email |
drupal/ |
Prepares a #type 'email' render element for theme_input(). |
form_validate_email |
drupal/ |
Form element validation handler for #type 'email'. |
form_pre_render_tel |
drupal/ |
Prepares a #type 'tel' render element for theme_input(). |
form_pre_render_number |
drupal/ |
Prepares a #type 'number' render element for theme_input(). |
form_pre_render_range |
drupal/ |
Prepares a #type 'range' render element for theme_input(). |
form_validate_number |
drupal/ |
Form element validation handler for #type 'number'. |
form_type_range_value |
drupal/ |
Determines the value for a range element. |
form_pre_render_url |
drupal/ |
Prepares a #type 'url' render element for theme_input(). |
form_pre_render_search |
drupal/ |
Prepares a #type 'search' render element for theme_input(). |
form_validate_url |
drupal/ |
Form element validation handler for #type 'url'. |
form_validate_color |
drupal/ |
Form element validation handler for #type 'color'. |
form_pre_render_color |
drupal/ |
Prepares a #type 'color' render element for theme_input(). |
theme_form |
drupal/ |
Returns HTML for a form. |
theme_textarea |
drupal/ |
Returns HTML for a textarea form element. |
form_pre_render_password |
drupal/ |
Prepares a #type 'password' render element for theme_input(). |
form_process_weight |
drupal/ |
Expands a weight element into a select element. |
form_pre_render_file |
drupal/ |
Prepares a #type 'file' render element for theme_input(). |
form_process_file |
drupal/ |
Processes a file upload element, make use of #multiple if present. |
theme_form_element |
drupal/ |
Returns HTML for a form element. |
theme_form_required_marker |
drupal/ |
Returns HTML for a marker for required form elements. |
theme_form_element_label |
drupal/ |
Returns HTML for a form element label and required marker. |
_form_set_attributes |
drupal/ |
Sets a form element's class attribute. |