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:
<?php
$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:
<?php
$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
| Name | Description |
|---|---|
| date_validate | Validates the date type to stop dates like February 30, 2006. |
| drupal_build_form | Build and process a form based on a form id. |
| drupal_form_submit | Retrieves, populates, and processes a form. |
| drupal_get_form | Wrapper for drupal_build_form() for use when $form_state is not needed. |
| drupal_prepare_form | Prepares a structured form array by adding required elements, executing any hook_form_alter functions, and optionally inserting a validation token to prevent tampering. |
| drupal_process_form | Processes a form submission. |
| drupal_rebuild_form | Constructs a new $form from the information in $form_state. |
| drupal_redirect_form | Redirects the user to a URL after a form has been processed. |
| drupal_retrieve_form | Retrieves the structured array that defines a given form. |
| drupal_validate_form | Validates user-submitted form data from the $form_state using the validate functions defined in a structured form array. |
| element_validate_integer | Helper form element validator: integer. |
| element_validate_integer_positive | Helper form element validator: integer > 0. |
| element_validate_number | Helper form element validator: number. |
| form_builder | Walk through the structured form array, adding any required properties to each element and mapping the incoming input data to the proper elements. Also, execute any #process handlers attached to a specific element. |
| form_clear_error | Clear all errors against all form elements made by form_set_error(). |
| form_error | Flag an element as having an error. |
| form_execute_handlers | A helper function used to execute custom validation and submission handlers for a given form. Button-specific handlers are checked first. If none exist, the function falls back to form-level handlers. |
| form_get_cache | Fetch a form from cache. |
| form_get_error | Returns the error message filed against the given form element. |
| form_get_errors | Return an associative array of all errors. |
| form_get_options | Traverses a select element's #option array looking for any values that hold the given key. Returns an array of indexes that match. |
| form_load_include | Loads an include file and makes sure it is loaded whenever the form is processed. |
| form_options_flatten | Allows PHP array processing of multiple select options with the same value. |
| form_pre_render_conditional_form_element | Add form_element theming to an element if title or description is set. |
| form_pre_render_fieldset | Adds members of this group as actual elements for rendering. |
| form_process_actions | Processes a form actions container element. |
| form_process_checkbox | Sets the #checked property of a checkbox element. |
| form_process_checkboxes | |
| form_process_container | Processes a container element. |
| form_process_date | Roll out a single date element. |
| form_process_fieldset | Adds fieldsets to the specified group or adds group members to this fieldset. |
| form_process_machine_name | Processes a machine-readable name form element. |
| form_process_password_confirm | Expand a password_confirm field into two text boxes. |
| form_process_radios | Roll out a single radios element to a list of radios, using the options array as index. |
| form_process_select | Processes a select list form element. |
| form_process_tableselect | Create the correct amount of checkbox or radio elements to populate the table. |
| form_process_vertical_tabs | Creates a group formatted as vertical tabs. |
| form_process_weight | Expand weight elements into selects. |
| form_select_options | Converts a select form element's options array into an HTML. |
| form_set_cache | Store a form in the cache. |
| form_set_error | Files an error against a form element. |
| form_set_value | Changes submitted form values in $form_state. |
| form_state_defaults | Retrieve default values for the $form_state array. |
| form_state_keys_no_cache | Returns an array of $form_state keys that shouldn't be cached. |
| form_state_values_clean | Removes internal Form API elements and buttons from submitted form values. |
| form_type_checkboxes_value | Helper function to determine the value for a checkboxes form element. |
| form_type_checkbox_value | Helper function to determine the value for a checkbox form element. |
| form_type_image_button_value | Helper function to determine the value for an image button form element. |
| form_type_password_confirm_value | Helper function to determine the value for a password_confirm form element. |
| form_type_select_value | Helper function to determine the value for a select form element. |
| form_type_tableselect_value | Helper function to determine the value for a tableselect form element. |
| form_type_textfield_value | Helper function to determine the value for a textfield form element. |
| form_type_token_value | Helper function to determine the value for form's token value. |
| form_validate_machine_name | Form element validation handler for #type 'machine_name'. |
| map_month | Helper function for usage with drupal_map_assoc to display month names. |
| password_confirm_validate | Validate password_confirm element. |
| theme_button | Returns HTML for a button form element. |
| theme_checkbox | Returns HTML for a checkbox form element. |
| theme_checkboxes | Returns HTML for a set of checkbox form elements. |
| theme_container | Returns HTML to wrap child elements in a container. |
| theme_date | Returns HTML for a date selection form element. |
| theme_fieldset | Returns HTML for a fieldset form element and its children. |
| theme_file | Returns HTML for a file upload form element. |
| theme_form | Returns HTML for a form. |
| theme_form_element | Returns HTML for a form element. |
| theme_form_element_label | Returns HTML for a form element label and required marker. |
| theme_form_required_marker | Returns HTML for a marker for required form elements. |
| theme_hidden | Returns HTML for a hidden form element. |
| theme_image_button | Returns HTML for an image button form element. |
| theme_password | Returns HTML for a password form element. |
| theme_radio | Returns HTML for a radio button form element. |
| theme_radios | Returns HTML for a set of radio button form elements. |
| theme_select | Returns HTML for a select form element. |
| theme_submit | Returns HTML for a submit button form element. |
| theme_tableselect | Returns HTML for a table with radio buttons or checkboxes. |
| theme_textarea | Returns HTML for a textarea form element. |
| theme_textfield | Returns HTML for a textfield form element. |
| theme_vertical_tabs | Returns HTML for an element's children fieldsets as vertical tabs. |
| weight_value | If no default value is set for weight select boxes, use 0. |
| _form_builder_handle_input_element | Populate the #value and #name properties of input elements so they can be processed and rendered. |
| _form_button_was_clicked | Helper function to handle the convoluted logic of button click detection. |
| _form_element_triggered_scripted_submission | Helper function to handle the convoluted logic of button click detection. |
| _form_options_flatten | Helper function for form_options_flatten(). |
| _form_set_class | Sets a form element's class attribute. |
| _form_validate | Performs validation on form elements. First ensures required fields are completed, #maxlength is not exceeded, and selected options were in the list of options given to the user. Then calls user-defined validators. |
File
- includes/
form.inc, line 22
Comments
drupal_render
You can use drupal_render($form) to print a form directly to a page if you have fetched it using drupal_get_form(mymodule_form).
Keep in mind that it is more advised to return the form and let the page builder render them in D7, instead of printing content directly to the page.
Form redirect with an "a name" HTML tag
If you want to redirect a form to a URL with an "A" element such as:
<A name="section1">Introduction</A>You need to set the form_state['redirect'] call like so:
<?php$form_state['redirect'] = array('somepath/somefile'. $dHashID, array('fragment' => 'section1'));
?>
I needed this funcionality when using jQuery UI tabs.
Mitch Schwenk
On a broader note, when
On a broader note, when $form_state['redirect'] is an array it should be populated with arguments appropriate for drupal_goto() - which is to say, the second element in the array can itself be an array holding all the properties expected by url()'s $options argument, including fragment, query, absolute, etc.
Multistep form
If needed build multistep form, then necessary to specify in $form_state the 'rebuild' value as TRUE:
<?phpfunction my_form_submit($form, &$form_state) {
...
$form_state['rebuild'] = TRUE;
...
}
?>
How to set the uid value at Validation
I tried bunch of things but nothing changes the uid.
I know i am getting drupal messages when opening the form and submitting the form but uid values are same.
<?php
function extra_form_alter(&$form, &$form_state, $form_id) {
switch($form_id){
case 'page_node_form':
drupal_set_message('Hey, we\'ve tapped into this form!');
$form['#validate'][] = 'node_validate_custom';
break;
}
}
function node_validate_custom($form, &$form_state){
// ... Validation Code
$a = 3;
//form_set_value( $form['uid'], $a, $form_state);
$form['uid']['#value'] = 3;
drupal_set_message('Hey, we\'ve tapped into validator too form!');
return $form;
// ... Other Code
}
?>