Form API 2.

0: The Cheat Sheet Sample FormAPI Definition FormAPI “Magic Properties”

(For Drupal 5 and later) Drupal forms are defined as structured arrays, then
processed. #submit
A list of functions to be called to process the form after
FormAPI Functions function mymodule_form_page() { successful validation. Each function name should be the
return drupal_get_form(‘mymodule_form’); key to an array of parameters. For example:
drupal_get_form($form_id, [...]) }
Retrieves and builds the specified form, then validates, $form[‘#submit’][‘my_function’] = array();
processes, and displays it as appropriate. function mymodule_form() {
$form = array(); #validate
drupal_execute($form_id, $form_values, [...]) $form[‘fields’][‘field1’] = array(
‘#type’ => ‘textfield’, A list of functions to be called when validating form
Retrieves the specified form, populates it with the ‘#title’ => ‘A text field’, submissions. Follows the same format as the #submit
$form_values, then validates and processes it. ‘#description’ => ‘Enter text here’, property.
‘#default_value’ => ‘Untitled node’,
form_set_value($field, $value) ); #tree
Change the submission value of a given form $field. $form[‘fields’][‘field2’] = array( Preserve the hierarchial structure of the form’s fields
Should only be used in a form_id_validate() function. ‘#type’ => ‘radios’,
‘#title’ => ‘Radio buttons’, when building the $form_values array. Defaults to FALSE,
‘#options’ => array( and can be applied to the entire form or to specific form
form_set_error($field_name, $message) 1 => ‘Option 1’, elements.
Mark a given form field as containing an error. 2 => ‘Option 2’,
3 => ‘Option 3’ #parents
form_get_error($field) ),
‘#default_value’ => 1, A list of form element ids that controls where an
Get the error(s) for a specific form field.
); element’s value appears in the $form_values collection
form_get_errors() $form[‘fields’][‘#tree’] = TRUE; if #tree is TRUE. Handled automatically, but overridable.
$form[‘buttons’][‘submit’] = array(
Get all errors for the form currently being processed. ‘#type’ => ‘submit’, #post
‘#title’ => ‘Submit this form’
); Holds the the current set of $_POST values for the form.
FormAPI Callbacks and Hooks return $form;
} #theme
form_id_validate($form_id, $form_values) The name of the theming function used to render a form
Check form input for errors, then call form_set_error() if array to HTML. Can be set for the entire form, or for
any are found. Standard Drupal Element Types individual form elements. Defaults to theme_form_id().
form_id_submit($form_id, $form_values) Basic HTML elements: #base
Process input for a given form (called if no errors textfield, textarea, password, select, radios, When set, this value is used instead of $form_id to
are found). Should return a path to redirect to when checkboxes, radio, checkbox, file, hidden, fieldset, locate the default validation, submission, and theming
submission is complete. submit, button. functions for the form.
theme_form_id($form_id, $form) password_confirm #value
Override the default for a given collection of form Presents two password fields, and throws a validation A hard-coded value that overrides user input entered
elements. Should return the fully-rendered HTML to error if the data entered into both fields doesn’t match. into a form element. Applies only to individual elements,
represent the contents of the $form parameter. and should not be confused with #default_value.
weight
hook_form_alter($form_id, $form) Presents a combo box of numbers from -10 to 10. Useful #parameters
Add, remove, or modify fields for any form handled by for specifying Drupal sorting weights. A saved copy of the parameters passed into the form’s
Drupal. Check $form_id to see whether the form you’re builder function. Useful in hook_form_alter().
date
given is the one you want to modify.
Presents day/month/year options with date validation. #multistep
hook_forms($form_id, [...]) Activates more complex validation code for forms that
value
Return a list of form_ids implemented by your module, submit to themselves repeatedly (multi-page wizards or
Embeds a value in a form defintion that does not appear
and the functions to use when building and validating forms with‘click for more fields’ buttons, for example).
in the final rendered HTML, but can be read by other
them. Most modules will return a static list of forms they
form manipulation functions (validation, submission, #redirect
implement, but a module generating forms on the fly
form_altering, etc.) Overrides the redirection path returned by the
may examine the incoming $form_id, responding with
data when it sees a $form_id it can handle. form_id_submit() function. Can be set to FALSE to
prevent redirection entirely.
built by robots: http://www.lullabot.com