Form generation

You are here

  1. 7 includes/form.inc form_api
  2. 6 includes/form.inc form_api
  3. 8 core/includes/form.inc form_api

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.

Functions

Namesort descending Location Description
date_validate includes/form.inc Validates the date type to prevent invalid dates (e.g., February 30, 2006).
drupal_build_form includes/form.inc Builds and process a form based on a form id.
drupal_form_submit includes/form.inc Retrieves, populates, and processes a form.
drupal_get_form includes/form.inc Returns a renderable form array for a given form ID.
drupal_prepare_form includes/form.inc Prepares a structured form array.
drupal_process_form includes/form.inc Processes a form submission.
drupal_rebuild_form includes/form.inc Constructs a new $form from the information in $form_state.
drupal_redirect_form includes/form.inc Redirects the user to a URL after a form has been processed.
drupal_retrieve_form includes/form.inc Retrieves the structured array that defines a given form.
drupal_validate_form includes/form.inc Validates user-submitted form data in the $form_state array.
element_validate_integer includes/form.inc Form element validation handler for integer elements.
element_validate_integer_positive includes/form.inc Form element validation handler for integer elements that must be positive.
element_validate_number includes/form.inc Form element validation handler for number elements.
form_builder includes/form.inc Builds and processes all elements in the structured form array.
form_clear_error includes/form.inc Clears all errors against all form elements made by form_set_error().
form_error includes/form.inc Flags an element as having an error.
form_execute_handlers includes/form.inc Executes custom validation and submission handlers for a given form.
form_get_cache includes/form.inc Fetches a form from cache.
form_get_error includes/form.inc Returns the error message filed against the given form element.
form_get_errors includes/form.inc Returns an associative array of all errors.
form_get_options includes/form.inc Returns the indexes of a select element's options matching a given key.
form_load_include includes/form.inc Ensures an include file is loaded whenever the form is processed.
form_options_flatten includes/form.inc Allows PHP array processing of multiple select options with the same value.
form_pre_render_conditional_form_element includes/form.inc Adds form element theming to an element if its title or description is set.
form_pre_render_fieldset includes/form.inc Adds members of this group as actual elements for rendering.
form_process_actions includes/form.inc Processes a form actions container element.
form_process_checkbox includes/form.inc Sets the #checked property of a checkbox element.
form_process_checkboxes includes/form.inc Processes a checkboxes form element.
form_process_container includes/form.inc Processes a container element.
form_process_date includes/form.inc Expands a date element into year, month, and day select elements.
form_process_fieldset includes/form.inc Arranges fieldsets into groups.
form_process_machine_name includes/form.inc Processes a machine-readable name form element.
form_process_password_confirm includes/form.inc Expand a password_confirm field into two text boxes.
form_process_radios includes/form.inc Expands a radios element into individual radio elements.
form_process_select includes/form.inc Processes a select list form element.
form_process_tableselect includes/form.inc Creates checkbox or radio elements to populate a tableselect table.
form_process_vertical_tabs includes/form.inc Creates a group formatted as vertical tabs.
form_process_weight includes/form.inc Expands a weight element into a select element.
form_select_options includes/form.inc Converts a select form element's options array into HTML.
form_set_cache includes/form.inc Stores a form in the cache.
form_set_error includes/form.inc Files an error against a form element.
form_set_value includes/form.inc Changes submitted form values during form validation.
form_state_defaults includes/form.inc Retrieves default values for the $form_state array.
form_state_keys_no_cache includes/form.inc Returns an array of $form_state keys that shouldn't be cached.
form_state_values_clean includes/form.inc Removes internal Form API elements and buttons from submitted form values.
form_type_checkboxes_value includes/form.inc Determines the value for a checkboxes form element.
form_type_checkbox_value includes/form.inc Determines the value for a checkbox form element.
form_type_image_button_value includes/form.inc Determines the value for an image button form element.
form_type_password_confirm_value includes/form.inc Determines the value for a password_confirm form element.
form_type_radios_value includes/form.inc Form value callback: Determines the value for a #type radios form element.
form_type_select_value includes/form.inc Determines the value for a select form element.
form_type_tableselect_value includes/form.inc Determines the value for a tableselect form element.
form_type_textfield_value includes/form.inc Determines the value for a textfield form element.
form_type_token_value includes/form.inc Determines the value for form's token value.
form_validate_machine_name includes/form.inc Form element validation handler for machine_name elements.
map_month includes/form.inc Helper function for usage with drupal_map_assoc to display month names.
password_confirm_validate includes/form.inc Validates a password_confirm element.
theme_button includes/form.inc Returns HTML for a button form element.
theme_checkbox includes/form.inc Returns HTML for a checkbox form element.
theme_checkboxes includes/form.inc Returns HTML for a set of checkbox form elements.
theme_container includes/form.inc Returns HTML to wrap child elements in a container.
theme_date includes/form.inc Returns HTML for a date selection form element.
theme_fieldset includes/form.inc Returns HTML for a fieldset form element and its children.
theme_file includes/form.inc Returns HTML for a file upload form element.
theme_form includes/form.inc Returns HTML for a form.
theme_form_element includes/form.inc Returns HTML for a form element.
theme_form_element_label includes/form.inc Returns HTML for a form element label and required marker.
theme_form_required_marker includes/form.inc Returns HTML for a marker for required form elements.
theme_hidden includes/form.inc Returns HTML for a hidden form element.
theme_image_button includes/form.inc Returns HTML for an image button form element.
theme_password includes/form.inc Returns HTML for a password form element.
theme_radio includes/form.inc Returns HTML for a radio button form element.
theme_radios includes/form.inc Returns HTML for a set of radio button form elements.
theme_select includes/form.inc Returns HTML for a select form element.
theme_submit includes/form.inc Returns HTML for a submit button form element.
theme_tableselect includes/form.inc Returns HTML for a table with radio buttons or checkboxes.
theme_textarea includes/form.inc Returns HTML for a textarea form element.
theme_textfield includes/form.inc Returns HTML for a textfield form element.
theme_vertical_tabs includes/form.inc Returns HTML for an element's children fieldsets as vertical tabs.
weight_value includes/form.inc Sets the value for a weight element, with zero as a default.
_form_builder_handle_input_element includes/form.inc Adds the #name and #value properties of an input element before rendering.
_form_button_was_clicked includes/form.inc Determines if a given button triggered the form submission.
_form_element_triggered_scripted_submission includes/form.inc Detects if an element triggered the form submission via Ajax.
_form_options_flatten includes/form.inc Iterates over an array and returns a flat array with duplicate keys removed.
_form_set_class includes/form.inc Sets a form element's class attribute.
_form_validate includes/form.inc Performs validation on form elements.

File

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

Comments

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.

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 $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.

If needed build multistep form, then necessary to specify in $form_state the 'rebuild' value as TRUE:

<?php
function my_form_submit($form, &$form_state) {
...
 
$form_state['rebuild'] = TRUE
...
}
?>

To direct to the theme function, don't include '_theme':

$form['#theme'] = 'function_name';

IN hook_theme, you don't use 'variables', use 'render element' in order to get $form into the theming function:

function mymodule_theme($existing, $type, $theme, $path)  {
  return array(
    'function_name' => array(
      'render element' => 'form',
    ),
  );
}

function my_module_example_form_validate($form, &$form_state) {
  $input_value_we_are_checking = $form_state['values']['the_field_name'];
  if(!my_function_checking_if_this_is_okay($input_value_we_are_checking)){
    form_set_error('the_field_name', 'WRONG! Try again!');
  }
}

function my_function_checking_if_this_is_okay($value_to_check){
  if($value_to_check == "badonkadonk"){
    return TRUE;
  }else{
    return FALSE;
  }
}

This page provides a quick reference to all the Form API element types.

http://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/7

Im having an ajax error when uploading an image

I think Drupal form api, is nothing but a set of functions(off-course, that’s what api means) provided by Drupal as part of core functionality, since version 4.7, for us Drupal developers to create, validate and process our html forms, in a secure manner. When i say secure, i mean that you form data is almost free from injection attacks, but you do need to validate this data as per your own application requirements.