Home › API reference

forms_api_reference.html

Version 1.142 (checked in on 2010/12/11 at 23:59:38 by rfay)

This document provides a programmer's reference to the Drupal Form API. If you're interested in step-by-step documentation to help you write forms, please see the Form API QuickStart guide.

Skip to: Properties | Default Values | Elements

Form Controls

Legend:
X = attribute can be used with this type
- = this attribute is not applicable to this type

#type checkbox checkboxes date fieldset file machine_name managed_file password password_confirm radio radios select tableselect textarea textfield vertical_tabs weight
#access X X X X X X X X X X X X X X X X X
#after_build X X X X X X X X X X X X X X X X X
#ajax X X - - - X - - - X X X X X X - -
#array_parents X X X X X X X X X X X X X X X X X
#attached X X X X X X X X X X X X X X X X X
#attributes X X X X X X X X - X X X X X X - X
#autocomplete_path - - - - - X - - - - - - - - X - -
#collapsed - - - X - - - - - - - - - - - - -
#collapsible - - - X - - - - - - - - - - - - -
#cols - - - - - - - - - - - - - X - - -
#default_tab - - - - - - - - - - - - - - - X -
#default_value X X X - - X - - - X X X X X X - X
#delta - - - - - - - - - - - - - - - - X
#description X X X X X X X X X X X X - X X - X
#disabled X X X - X X X X X X X X - X X - X
#element_validate X X X X X X X X X X X X X X X X X
#empty - - - - - - - - - - - - X - - - -
#field_prefix - - - - - X - - - - - - - - X - -
#field_suffix - - - - - X - - - - - - - - X - -
#group - - - X - - - - - - - - - - - - -
#header - - - - - - - - - - - - X - - - -
#js_select - - - - - - - - - - - - X - - - -
#maxlength - - - - - X - X - - - - - - X - -
#multiple - - - - - - - - - - - X X - - - -
#options - X - - - - - - - - X X X - - - -
#parents X X X X X X X X X X X X X X X X X
#post_render X X X X X X X X X X X X X X X X X
#prefix X X X X X X X X X X X X X X X X X
#pre_render X X X X X X X X X X X X X X X X X
#process X X X X X X X X X X X X X X X X X
#required X X X - - X - X X X X X - X X - X
#resizable - - - - - - - - - - - - - X - - -
#return_value X - - - - - - - - X - - - - - - -
#rows - - - - - - - - - - - - - X - - -
#size - - - - - X - X X - - X - - X - -
#states X X X X X X X X X X X X X X X X X
#suffix X X X X X X X X X X X X X X X X X
#text_format - - - - - - - - - - - - - X X - -
#theme X X X X X X X X X X X X X X X X X
#theme_wrappers X X X X X X X X X X X X X X X X X
#title X X X X X X X X X X X X - X X - X
#title_display X X X X X X X X X X X X - X X - X
#tree X X X X X X X X X X X X X X X X X
#weight X X X X X X X X X X X X X X X X X

Special Elements

#type button image_button submit form hidden token markup item value
#access X X X X X X X X -
#action - - - X - - - - -
#after_build X X X X X X X X -
#ajax X X X - X - - - -
#attributes X X X X - - - - -
#button_type X X X - - - - - -
#default_value - - - - X X - - -
#description - - - - - - - X -
#disabled X X X - - - - - -
#element_validate X X X - X X X X -
#executes_submit_callback X X X - - - - - -
#limit_validation_errors X X X - - - - - -
#markup - - - - - - X X -
#method - - - X - - - - -
#name X - X - - - - - -
#parents X X X - X X X X -
#post_render X X X X X X X X -
#prefix X X X X X X X X -
#pre_render X X X X X X X X -
#process X X X X X X X X -
#return_value - X - - - - - - -
#src - X - - - - - - -
#submit X X X X - - - - -
#suffix X X X X X X X X -
#theme X X X X X X X X -
#theme_wrappers X X X X X X X X -
#title - - - - - - - X -
#title_display - - - - - - - X -
#tree X X X X X X X X -
#validate X X X X - - - - -
#value X X X - X X - - X
#weight X X X - X X X X -

Default Values

Every element automatically has these default values (see system_element_info()):

The following is a list of default values which do not need to be set (found in system_element_info):

 

Elements

Note that property names in bold are those that will generally need to be defined when creating this form element. Default values are indicated in parentheses next to property names, if they exist.

button

Description: Format an action button. When the button is pressed, the form will be submitted to Drupal, where it is validated and rebuilt. The submit handler is not invoked.

Properties: #access, #after_build, #ajax, #attributes, #button_type (default: submit), #disabled, #element_validate, #executes_submit_callback (default: FALSE), #limit_validation_errors, #name (default: op), #parents, #post_render, #prefix, #pre_render, #process, #submit, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #validate, #value, #weight

Usage example (node.module):

<?php
$form['preview'] = array(
  '#type' => 'button',
  '#value' => t('Preview'),
  '#weight' => 19,
);
 ?>

checkbox

Description: Format a checkbox.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #return_value (default: 1), #states, #suffix, #theme, #theme_wrappers, #title, #title_display (default: after), #tree, #type, #weight

Usage example (contact.module):

<?php
$form['copy'] = array(
  '#type' => 'checkbox',
  '#title' => t('Send me a copy.'),
);
?>

checkboxes

Description: Format a set of checkboxes. #options is an associative array, where the key is the #return_value of the checkbox and the value is displayed. The #options array can not have a 0 key, as it would not be possible to discern checked and unchecked states.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #description, #disabled, #element_validate, #options, #parents, #post_render, #prefix, #pre_render, #process, #required, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree (default: TRUE), #type, #weight

Usage example (node.module):

<?php
$form['node_options_'. $node->type] = array(
   '#type' => 'checkboxes',
  '#title' => t('Default options'),
  '#default_value' => variable_get('node_options_'. $node->type, array('status', 'promote')),
   '#options' => array(
    'status' => t('Published'),
    'moderate' => t('In moderation queue'),
    'promote' => t('Promoted to front page'),
    'sticky' => t('Sticky at top of lists'),
    'revision' => t('Create new revision'),
  ),
   '#description' => t('Users with the <em>administer nodes</em> permission will be able to override these options.'),
);
 ?>

date

Description: Format a date selection box. The #default_value will be today's date if no value is supplied. The format for the #default_value and the #return_value is an array with three elements with the keys: 'year', month', and 'day'. For example, array('year' => 2007, 'month' => 2, 'day' => 15)

Properties: #access, #after_build, #attributes, #default_value, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (profile.module):

<?php
$fields[$category][$field->name] = array(
  '#type' => 'date',
  '#title' => check_plain($field->title),
  '#default_value' => $edit[$field->name],
  '#description' => _profile_form_explanation($field),
  '#required' => $field->required
);
?>

fieldset

Description: Format a group of form items.

Properties: #access, #after_build, #attributes, #collapsed (default: FALSE), #collapsible (default: FALSE), #description, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (contact.module):

<?php
$form['contact'] = array(
  '#type' => 'fieldset',
  '#title' => t('Contact settings'),
  '#weight' => 5,
  '#collapsible' => TRUE,
  '#collapsed' => FALSE,
);
?>

file

Description: Format a file upload field.

Note: you will need to include $form['#attributes'] = array('enctype' => "multipart/form-data"); in your form. See this handbook page for an example http://drupal.org/node/111782.

Note: the #required property is not supported (setting it to true will always cause a validation error). Instead, you may want to use your own validation function to do checks on the $_FILES array with #required set to false. You will also have to add your own required asterisk if you would like one.

Properties: #access, #after_build, #attributes, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #size (default: 60), #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (upload.module):

<?php
$form['new']['upload'] = array(
  '#type' => 'file',
  '#title' => t('Attach new file'),
  '#size' => 40,
);
?>

form

Description: A form containing form elements

Properties: #access, #action (default: request_uri()), #after_build, #attributes, #method (default: 'post'), #post_render, #prefix, #pre_render, #process, #submit, #states, #suffix, #theme, #theme_wrappers, #tree, #validate

Usage example:

N/A

hidden

Description: Store data in a hidden form field.

Properties: #access, #after_build, #ajax, #default_value, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #value, #weight

Usage example (block.module):

<?php
$form['bid'] = array('#type' => 'hidden', '#value' => $bid);
?>

Note that if you plan to use JavaScript to change your hidden element's value, you will need to use the #default_value property rather than #value.

image_button

Description: Format a form submit button with an image.

Properties: #access, #after_build, #ajax, #attributes, #button_type (default: 'submit'), #disabled, #element_validate, #executes_submit_callback (default: TRUE), #limit_validation_errors, #parents, #post_render, #prefix, #pre_render, #process, #return_value (default: TRUE), #src, #submit, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #validate, #value, #weight

item

Description: Generate a display-only form element allowing for an optional title and description.

Note: since this is a read-only field, setting the #required property will do nothing except theme the form element to look as if it were actually required (i.e. by placing a red star next to the #title).

Properties: #access, #after_build, #description, #element_validate, #markup, #parents, #post_render, #prefix, #pre_render, #process, #required, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (contact.module):

<?php
 $form['from'] = array(
  '#type' => 'item',
  '#title' => t('From'),
  '#markup' => $user->name .' &lt;'. $user->mail .'&gt;',
);
 ?>

machine_name

Description: Format a single-line text field to store a unique machine-readable name.

Provides a form element to enter a machine name, which is validated to ensure that the name is unique and does not contain disallowed characters. All disallowed characters are replaced with a replacement character via JavaScript.

The element validation checks that the submitted value

  • does not contain the replacement character only
  • does not contain disallowed characters
  • is unique; i.e., does not already exist
  • does not exceed the maximum length (via #maxlength)
  • cannot be changed after creation (via #disabled)

Non-standard form element properties:

  • #machine_name: (array)
    • exists: A function name to invoke for checking whether a submitted machine name value already exists. The submitted value is passed as argument. In most cases, an existing API or menu argument function can be re-used. The callback is only invoked, if the submitted value differs from the element's #default_value
    • source: (optional) The #array_parents of the form element containing the human-readable name (i.e., as contained in the $form structure) to use as source for the machine name. Defaults to array('name').
    • label: (optional) A text to display as label for the machine name value after the human-readable name form element. Defaults to "Machine name".
    • replace_pattern: (optional) A regular expression (without delimiters) matching disallowed characters in the machine name. Defaults to '[^a-z0-9_]+'.
    • replace: (optional) A character to replace disallowed characters in the machine name via JavaScript. Defaults to '_' (underscore). When using a different character, 'replace_pattern' needs to be set accordingly.

Properties: #access, #after_build, #ajax, #attributes, #autocomplete_path (default: FALSE), #default_value, #description (default: 'A unique machine-readable name. Can only contain lowercase letters, numbers, and underscores.'), #disabled, #element_validate, #field_prefix, #field_suffix, #maxlength (default: 64), #parents, #post_render, #prefix, #pre_render, #process, #required (default: TRUE), #size (default: 60), #states, #suffix, #theme (default: 'textfield'), #theme_wrappers (default: 'form_element'), #title (default: 'Machine-readable name'), #title_display #tree, #type, #weight

Usage example (taxonomy.admin.inc):

<?php
$form['machine_name'] = array(
  '#type' => 'machine_name',
  '#default_value' => $vocabulary->machine_name,
  '#maxlength' => 21,
  '#machine_name' => array(
    'exists' => 'menu_edit_menu_name_exists',
  ),
);
?>

Usage example (menu.admin.inc):

<?php
$form['menu_name'] = array(
  '#type' => 'machine_name',
  '#title' => t('Menu name'),
  '#default_value' => $menu['menu_name'],
  '#maxlength' => MENU_MAX_MENU_NAME_LENGTH_UI,
  '#description' => t('A unique name to construct the URL for the menu. It must only contain lowercase letters, numbers and hyphens.'),
  '#machine_name' => array(
    'exists' => 'menu_edit_menu_name_exists',
    'source' => array('title'),
    'label' => t('URL path'),
    'replace_pattern' => '[^a-z0-9-]+',
    'replace' => '-',
  ),
  // A menu's machine name cannot be changed.
  '#disabled' => !empty($menu['old_name']) || isset($system_menus[$menu['menu_name']]),
);
?>

managed_file

Description: Provides a complete ajax/progress aware widget for uploading a file and saving it to the {files} table.

By default a simple upload button is provided for choosing the file to upload. Once a file has been chosen it can be explicitly uploaded via the "Upload" button. The upload is via AJAX and a progress meter is displayed. The form's validate and submit handlers receive a file object ID in $form_state['values'] that represents the ID of the new file in the {files} table.

The #managed_file element is expanded into a set of FAPI elements including two '#submit' buttons one for Upload one for Remove, a '#file' element and a handful of '#hidden' and '#markup' elements to handle progress indication and displaying of already uploaded files.

Note: New files are uploaded with a status of 0 and are treated as temporary files which are removed after 6 hours via cron. Your module is responsible for changing the $file objects status to FILE_STATUS_PERMANENT and saving the new status to the database. Something like the following within your submit handler should do the trick.

// Load the file via file.fid.
$file = file_load($form_state['values']['my_file_field']);
// Change status to permanent.
$file->status = FILE_STATUS_PERMANENT;
// Save.
file_save($file);

Once a file has been uploaded the file object's fid can be used as the #default_value for the form element. This will display an icon, a link to the file, and a remove button.

Clicking the remove button sets the value of the field to 0 and your module is responsible for actually removing the file from the files table and the file system using file_delete().

Non-standard form element properties:

  • #progress_indicator: options are 'none', 'bar', and 'throbber', default is 'throbber'.
  • #progress_message: (string) Progress message to display along with progress meter while a file is being uploaded. Defaults to NULL.
  • #upload_validators: (array) an array of callback functions to perform validation of uploaded files.
  • #upload_location (string) location on server where uploaded files should be stored. e.g.) 'public://files/my_files_director'

Properties: #access, #after_build, #array_parents, #attached, #attributes, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #title, #tree, #weight

Usage example (image_example.pages.inc.):

<?php
// Use the #managed_file FAPI element to upload an image file.
$form['image_example_image_fid'] = array(
  '#title' => t('Image'),
  '#type' => 'managed_file',
  '#description' => t('The uploaded image will be displayed on this page using the image style choosen below.'),
  '#default_value' => variable_get('image_example_image_fid', ''),
  '#upload_location' => 'public://image_example_images/',
);
?>

markup

Description: Generate generic markup for display inside forms. Note that there is no need to declare a form element as #type = 'markup', as this is the default type.

Note: if you use markup, if your content is not wrapped in tags (generally <p> or <div>), your content will fall outside of collapsed fieldsets.

Properties: #access, #after_build, #element_validate, #markup, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #weight

Usage example (contact.module):

<?php
$form['contact_information'] = array(
  '#markup' => variable_get('contact_form_information', t('You can leave us a message using the contact form below.')),
);
?>

password

Description: Format a single-line text field that does not display its contents visibly.

Properties: #access, #after_build, #ajax, #attributes, #description, #disabled, #element_validate, #maxlength (default: 128), #parents, #post_render, #prefix, #pre_render, #process, #required, #size (default: 60), #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (user.module):

<?php
$form['pass'] = array(
  '#type' => 'password',
  '#title' => t('Password'),
  '#maxlength' => 64,
  '#size' => 15,
);
?>

password_confirm

Description: Format a pair of password fields, which do not validate unless the two entered passwords match.

Properties: #access, #after_build, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #size (default: 60), #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (user.module):

<?php
$form['pass'] = array(
  '#type' => 'password_confirm',
  '#title' => t('Password'),
  '#size' => 25,
);
?>

radio

Description: Format a radio button.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #return_value, #states, #suffix, #theme, #theme_wrappers, #title, #title_display (default: after), #tree, #type, #weight

Usage example:

N/A

radios

Description: Format a set of radio buttons.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #description, #disabled, #element_validate, #options, #parents, #post_render, #prefix, #pre_render, #process, #required, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (comment.module):

<?php
$form['posting_settings']['comment_preview'] = array(
  '#type' => 'radios',
  '#title' => t('Preview comment'),
  '#default_value' => variable_get('comment_preview', 1),
  '#options' => array(t('Optional'), t('Required')),
);
?>

select

Description: Format a drop-down menu or scrolling selection box.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #description, #disabled, #element_validate, #multiple, #options, #parents, #post_render, #prefix, #pre_render, #process, #required, #size, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (system.module):

<?php
$form['feed']['feed_item_length'] = array(
   '#type' => 'select',
  '#title' => t('Display of XML feed items'),
  '#default_value' => variable_get('feed_item_length','teaser'),
   '#options' => array(
    'title' => t('Titles only'),
    'teaser' => t('Titles plus teaser'),
    'fulltext' => t('Full text'),
  ),
   '#description' => t('Global setting for the length of XML feed items that are output by default.'),
);
?>

submit

Description: Format a form submit button.

Properties: #access, #after_build, #ajax, #attributes, #button_type (default: 'submit'), #disabled, #element_validate, #executes_submit_callback (default: TRUE), #limit_validation_errors, #name (default: 'op'), #parents, #post_render, #prefix, #pre_render, #process, #submit, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #validate, #value, #weight

Usage example (locale.module):

<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>

tableselect

Description: Format a table of radios or checkboxes, where the columns are given by the #headers property, and the rows are the #options property. The choice of radios or checkboxes depends on the #multiple property, and JavaScript-enabled "check all" buttons are added if the #js_select property is TRUE.

Properties: #access, #after_build, #ajax, #attributes, #default_value, #element_validate, #empty, #header, #js_select, #multiple, #options, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #weight

Usage example (comment.admin.inc):

<?php
$form['comments'] = array(
  '#type' => 'tableselect',
  '#header' => $header,
  '#options' => $options,
  '#empty' => t('No comments available'),
);
 ?>

textarea

Description: Format a multiple-line text field.

Properties: #access, #after_build, #ajax, #attributes, #cols (default: 60), #default_value, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #resizable (default: TRUE), #rows (default: 5), #states, #suffix, #text_format, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (comment.module):

<?php
$form['comment'] = array(
  '#type' => 'textarea',
  '#title' => t('Comment'),
  '#default_value' => $default,
  '#text_format' => isset($edit->format) ? $edit->format : FILTER_FORMAT_DEFAULT),
  '#required' => TRUE
);
 ?>

textfield

Description: Format a single-line text field.

Properties: #access, #after_build, #ajax, #attributes, #autocomplete_path (default: FALSE), #default_value, #description, #disabled, #element_validate, #field_prefix, #field_suffix, #maxlength (default: 128), #parents, #post_render, #prefix, #pre_render, #process, #required, #size (default: 60), #states, #suffix, #text_format, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (forum.module):

<?php
$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Subject'),
  '#default_value' => $node->title,
  '#size' => 60,
  '#maxlength' => 128,
  '#required' => TRUE,
);
?>

token

Description: Store token data in a hidden form field (generally used to protect against cross-site forgeries). A token element is automatically added to each Drupal form by drupal_prepare_form(), so you don't generally have to add one yourself.

Properties: #access, #after_build, #default_value, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #value, #weight

value

Description: A form value that is internal to the form and never displayed to the screen.

Properties: #type, #value

Usage example (node.module):

<?php
$form['vid'] = array('#type' => 'value', '#value' => $node->vid);
?>

Note that as of Drupal 6, you can also simply store arbitrary variables in $form['#foo'] instead, as long as '#foo' does not conflict with any other internal property of the Form API.

vertical_tabs

Description: Format all child fieldsets as vertical tabs.

Properties: #access, #after_build, #default_tab, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #weight

weight

Description: Format a weight selection menu.

Properties: #access, #after_build, #attributes, #default_value, #delta (default: 10), #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render, #process, #required, #states, #suffix, #theme, #theme_wrappers, #title, #title_display, #tree, #type, #weight

Usage example (menu.module):

<?php
$form['weight'] = array(
  '#type' => 'weight',
  '#title' => t('Weight'),
  '#default_value' => $edit['weight'],
  '#delta' => 10,
  '#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>

Properties

#access

Used by: All elements and forms

Description: Whether the element is accessible or not; when FALSE, the element is not rendered and the user submitted value is not taken into consideration.

Values: TRUE or FALSE.

#action

Used by: form

Description: The path to which the form will be submitted.

Values: An internal path

Usage example (comment.module):

<?php
$form['#action'] = url('comment/reply/'. $edit['nid']);
 ?>

#after_build

Used by: All elements and forms

Description: An array of function names which will be called after the form or element is built.

Usage example (system.module):

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

<?php
$form['files']['file_directory_path'] = array(
   '#type' => 'textfield',
   '#title' => t('File system path'),
   '#default_value' => file_directory_path(),
   '#maxlength' => 255,
   '#description' => t('A file system path where the files will be stored. This directory has to exist and be writable by Drupal. If the download method is set to public this directory has to be relative to Drupal installation directory, and be accessible over the web. When download method is set to private this directory should not be accessible over the web. Changing this location after the site has been in use will cause problems so only change this setting on an existing site if you know what you are doing.'),
);
$form['#after_build'] = array('system_check_directory');

...

function system_check_directory($form_element, &$form_state) {
   file_check_directory($form_element['#value'], FILE_CREATE_DIRECTORY, $form_element['#parents'][0]);
   return $form_element;
}
 ?>

#ajax

Used by: button, checkbox, checkboxes, hidden, image button, password, radio, radios, select, submit, tableselect, textarea, textfield

An array of elements whose values control the behavior of the element with respect to the Drupal AJAX javascript methods.

AJAX (Asynchronous Javascript and XML) is a term used for dynamic communication between the browser and the server, without page reloads. A purist would insist that the Drupal technique is AHAH (Asychronous HTML and HTTP) because XML is not used. Until Drupal 7, AJAX was known as AHAH. In a nutshell an AJAX request follows these steps:

  1. Drupal builds a form element with a set of #ajax properties. The misc/ajax.js file is included on the page automatically.
  2. ajax.js finds all the form elements on the page that have an #ajax['callback'] or an #ajax['path'] set and adds an event handler for the #ajax['event'] set on that form element.
  3. When the #ajax['event'] occurs on the element (such as 'click'), the AJAX request is made to the Drupal path of the element's #ajax['path']. If an #ajax['callback'] has been specified (the normal case), the Drupal path will be system/ajax.
  4. Form information gets processed, and the function specified in #ajax['callback'] is called.  #ajax['callback'] can return either HTML, a renderable array, or an array of AJAX commands.
  5. While the user waits for the callback to execute a throbber or progress bar is shown as determined by #ajax['progress']. The result is returned to the original page containing the form element.
  6. ajax.js gets the result. If it is HTML and #ajax['wrapper'] is set, the HTML replaces the element specified by #ajax['wrapper']. If it is an array of AJAX commands, the commands are executed. and inserts the returned HTML into the #ajax['wrapper']. 

Example usages of basic AJAX and AJAX commands are provided in the Examples module.

#ajax['callback']

Description: Specifies the name of a callback function which will be called during an AJAX call. It can return HTML, a renderable array, or an array of AJAX Commands. This callback function is given the $form and $form_state parameters, allowing it to produce a result, which it returns for rendering.

Note: #ajax['callback'] and #ajax['path'] are mutually exclusive. 'callback' is easier to use and requires less code setup, but may not provide the capabilities required for some functions. When you can, use 'callback'.

Values: String containing a function name.

Usage example (poll.module):

<?php
/**
 * Implementation of hook_form().
 */
function poll_form(&$node, $form_state) {
  ...
  $form['choice_wrapper']['poll_more'] = array(
    '#type' => 'submit',
    '#value' => t('More choices'),
    '#description' => t("If the amount of boxes above isn't enough, click here to add more choices."),
    '#weight' => 1,
    '#submit' => array('poll_more_choices_submit'), // If no javascript action.
    '#ajax' => array(
      'callback' => 'poll_choice_js',
      'wrapper' => 'poll-choices',
      'method' => 'replace',
      'effect' => 'fade',
    ),
  );
  ...
}

/**
 * Menu callback for AJAX additions. Render the new poll choices.
 */
function poll_choice_js($form, $form_state) {
  return $form['choice_wrapper']['choice'];
}
?>

#ajax['effect']

Description: Specifies the effect used when adding the content from an AJAX request.

Values: String. Possible values: 'none' (default), 'fade', 'slide'. If the interface elements library is installed, any effect with the name effectToggle may also be used.

#ajax['event']

Description: When this event occurs to this element, Drupal will perform an HTTP request in the background via Javascript.

Values: String. Possible values: Any valid jQuery event, including 'mousedown' (for submit, imagebutton, and button), 'blur' (for textfield and textarea), 'change' (for select). Note that #ajax['event'] does not need to be explicitly specified. Although it can be manually set, usually the default value will be sufficient.

#ajax['keypress']

Description: If set to TRUE, then the element's #ajax['event'] will be triggered if the ENTER key is pressed while the element has focus.

#ajax['method']

Description: Modify the behavior of the returned HTML from an AJAX request when inserting into the #ajax['wrapper']. If not set, the returned HTML will replace the contents of the wrapper element, but it's also possible to use any of the available jQuery operations for DOM manipulation.

Values: String. Possible values: 'replace' (default), 'after', 'append', 'before', 'prepend'.

#ajax['path']

Description: This is the Drupal menu path for a callback function which will generate HTML and return the string of HTML to Drupal. The result will replace the div specified in #ajax['wrapper']. This property is infrequently used in Drupal 7 and higher, because it is set automatically if using the #ajax['callback'] property. When using #ajax['callback'] the path is automatically set to system/ajax, which provides a menu callback that can be used for many situations.

Note: 'path' and 'callback' are mutually exclusive.

Values: String containing a Drupal menu path.

Usage example (upload.module):

<?php
/**
* Implementation of hook_menu().
*/
function upload_menu() {
  $items['upload/js'] = array(
    'page callback' => 'upload_js',
    'access arguments' => array('upload files'),
    'type' => MENU_CALLBACK,
  );
  ...
  return $items;
}

...

function _upload_form($node) {
  ...
    $form['new']['attach'] = array(
      '#type' => 'submit',
      '#value' => t('Attach'),
      '#name' => 'attach',
      '#ajax' => array(
        'path' => 'upload/js',
        'wrapper' => 'attach-wrapper',
        'progress' => array('type' => 'bar', 'message' => t('Please wait...')),
      ),
      '#submit' => array('node_form_submit_build_node'),
    );
  ...
return $form;
?>

#ajax['path'] is set to 'upload/js', which has a menu item defined in the same module. Then the menu hook will call the 'upload_js' function which generates HTML and returns it to original page.

#ajax['progress']

Description: Choose either a throbber or progress bar that is displayed while awaiting a response from the callback, and add an optional message.

Values: Array.

Possible keys: 'type', 'message', 'url', 'interval'

Possible values:

  • #ajax['progress']['type'] String. Possible values: 'throbber' (default), 'bar'.
  • #ajax['progress']['message'] String. An optional message to the user; should be wrapped with t().
  • #ajax['progress']['url'] String. The optional callback path to use to determine how full the progress bar is (as defined in progress.js). Only useable when 'type' is 'progress'.
  • #ajax['progress']['interval'] String. The interval to be used in updating the progress bar (as defined in progress.js). Ony used if 'url' is defined and 'type' is 'progress'.

Usage example: see above usage in upload.module

#ajax['trigger_as']

Description: For a non-submit, non-button element, allows selection of the submit element which will be activated when the element is triggered. For example, if a select element is ajax-enabled, and it changes, an element identified by #ajax['trigger_as']['name'] or #ajax['trigger_as']['value'] will be used as the triggering element, especially for button-level validation.

Values: Array.

Possible values

  • array('name' => some_submit_or_button_name)
  • array('value' => some_submit_or_button_value)

Note that if #tree == TRUE, #name encodes the parents of the element in it, as when used with form_set_error(), i.e. "level1][level2][element".

#ajax['wrapper']

Description: This property defines the HTML id attribute of an element on the page which will be replaced by the html returned by the #ajax['path'] or #ajax['callback'] function. Usually, a div element is used as the wrapper, as it provides the most flexibility for placement of elements before, after, or inside of its HTML tags. This property is required for using AJAX requests in on a form element.  Note that the entire element with this ID is replaced, not just the contents of the element.

Values: String containg a valid id attribute of an HTML element on the same page. This must not contain the '#' character that a selector would have.

Usage example (upload.module):

    $form['new']['attach'] = array(
      '#type' => 'submit',
      '#value' => t('Attach'),
      '#name' => 'attach',
      '#ajax' => array(
        'path' => 'upload/js',
        'wrapper' => 'attach-wrapper',
        'progress' => array('type' => 'bar', 'message' => t('Please wait...')),
      ),
      '#submit' => array('node_form_submit_build_node'),
    );

#array_parents

Used by: All form elements

Description: (read-only, and mostly internal). The array of names of the element's parents (including itself) in the form. This will always match the structure of $form. It is different from #parents in that #parents lists only the structure used in $form_state['values'], which is flat unless #tree is set to TRUE. Please see the complete comparison between #parents and #array_parents.

#attached

Used by: All form elements

Description: Allows loading of CSS, Javascript, libraries, or custom types when the form is built.

Values: A keyed array of type => value pairs, where the type (most often 'css', 'js', and 'library') determines the loading technique, and the value provides the options presented to the loader function. See the example below and the loader functions drupal_add_css(), drupal_add_js(), etc.

See drupal_process_attached() for additional information.

Usage example (AJAX Example):

$form['#attached']['css'] = array(
drupal_get_path('module', 'ajax_example') . '/ajax_example.css',
);
$form['#attached']['js'] = array(
drupal_get_path('module', 'ajax_example') . '/ajax_example.js',
);

The above javascript #attach could also be written as:

$form['#attached']['js'] = array(
  drupal_get_path('module', 'ajax_example') . '/ajax_example.js' => array(
  'type' => 'file',
  ),
);

and inline javascript can be loaded with the javascript as the key of the array, as described in drupal_add_js()

#attributes

Used by: button, checkbox, checkboxes, date, fieldset, file, form, image_button, password, radio, radios, select, submit, tableselect, textarea, textfield, weight

Description: Additional HTML attributes, such as 'class' can be set using this mechanism.

Values: Any HTML attribute not covered by other properties, e.g. class (for control types), enctype (for forms).

Usage example (search.module):

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

<?php
$form['#attributes'] = array('class' => array('search-form'));
?>

#autocomplete_path

Used by: textfield

Description: The path the AJAX autocomplete script uses as the source for autocompletion.

Usage example (node.module):

<?php
$form['author']['name'] = array(
  '#type' => 'textfield',
  '#title' => t('Authored by'),
  '#maxlength' => 60,
  '#autocomplete_path' => 'user/autocomplete',
  '#default_value' => $node->name,
  '#weight' => -1,
);
?>

#built

Used by: form

Description: Used to ascertain whether or not a form element has been built yet.

Values: TRUE or FALSE

Usage example: INTERNAL. See the _form_builder function in form.inc.

#button_type

Used by: button, image_button, submit

Description: Adds a CSS class to the button, in the form form-[button_type_value]. Note that this does NOT set the HTML attribute type of the button.

Values: String

Usage example: (system.module):

$types['submit'] = array(
  '#input' => TRUE,
  '#name' => 'op',
  '#button_type' => 'submit',
  '#executes_submit_callback' => TRUE,
  '#limit_validation_errors' => FALSE,
  '#process' => array('ajax_process_form'),
  '#theme_wrappers' => array('button'),
);

#collapsed

Used by: fieldset

Description: Indicates whether or not the fieldset is collapsed by default. See #collapsible property.

Values: TRUE or FALSE

Usage example (block.module) :

<?php
$form['block'] = array(
  '#type' => 'fieldset',
  '#title' => t('Block configuration'),
  '#weight' => 3,
  '#collapsible' => TRUE,
  '#collapsed' => FALSE,
  '#tree' => TRUE,
);
?>

#collapsible

Used by: fieldset

Description: Indicates whether or not the fieldset can be collapsed with JavaScript. See #collapsed property.

Values: TRUE or FALSE

Usage example (block.module):

<?php
$form['block'] = array(
  '#type' => 'fieldset',
  '#title' => t('Block configuration'),
  '#weight' => 3,
  '#collapsible' => TRUE,
  '#collapsed' => FALSE,
  '#tree' => TRUE,
);
?>

#cols

Used by: textarea

Description: How many columns wide the textarea should be (see also #rows)

Values: A positive number

Usage example (aggregator.module):

<?php
$form['description'] = array(
  '#type' => 'textarea',
  '#title' => t('Description'),
  '#default_value' => $edit['description'],
  '#cols' => 60,
  '#rows' => 5,
);
?>

#default_tab

Used by: vertical_tabs

Description: The default tab to have open.

Values: Text giving the array key of the default tab.

#default_value

Used by: checkbox, checkboxes, date, hidden, radio, radios, select, tableselect, textarea, textfield, token, weight

Description: The value of the form element that will be displayed or selected initially if the form has not been submitted yet. Should NOT be confused with #value, which is a hard-coded value the user cannot change!

Values: Mixed

Usage example (forum.module):

<?php
$form['body'] = array(
  '#type' => 'textarea',
  '#title' => t('Body'),
  '#default_value' => $node->body,
  '#required' => TRUE,
);
?>

#delta

Used by: weight

Description: Number of weights to have selectable. For example, with $delta => 10, the weight selection box would display numbers from -10 to 10.

Values: A positive number

Usage example (menu.module):

<?php
$form['weight'] = array(
  '#type' => 'weight',
  '#title' => t('Weight'),
  '#default_value' => $edit['weight'],
  '#delta' => 10,
  '#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>

#description

Used by: checkbox, checkboxes, date, fieldset, file, item, password, password_confirm, radio, radios, select, textarea, textfield, weight

Description: The description of the form element. Make sure to enclose inside the t() function so this property can be translated.

Values: Mixed

Usage example (menu.module):

<?php
$form['weight'] = array(
  '#type' => 'weight',
  '#title' => t('Weight'),
  '#default_value' => $edit['weight'],
  '#delta' => 10,
  '#description' => t('Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'),
);
?>

#disabled

Used by: button, checkbox, checkboxes, date, file, image_button, password, password_confirm, radio, radios, select, submit, textarea, textfield, weight

Description: Disables (greys out) a form input element. Note that disabling a form field doesn't necessarily prevent someone from submitting a value through DOM manipulation. It just tells the browser not to accept input.

Values: TRUE or FALSE

Usage example (system.module):

<?php
      if (isset($disabled[$name])) {
        $form['theme_settings'][$name]['#disabled'] = TRUE;
      }
?>

#element_validate

Used by: any element

Description: A list of custom validation functions that need to be passed. The functions must use form_error() or form_set_error() to set an error if the validation fails.

Values: an array of function names to be called to validate this element (and/or its children).

A validation function for an element takes the element and the form state as parameters, and has the form:

function myelement_validate($element, &$form_state) {
   if (empty($element['#value'])) {
     form_error($element, t('This field is required.'));
   }
}

Usage example (filter.module):

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

<?php
  if (count($formats) > 1) {
    $form = array(
      '#type' => 'fieldset',
      '#title' => t('Input format'),
      '#collapsible' => TRUE,
      '#collapsed' => TRUE,
      '#weight' => $weight,
      '#element_validate' => array('filter_form_validate'),
    );
   ...
?>

#empty

Used by: tableselect

Description: Text to display if the #options property is empty.

Values: Text, enclosed in the t() translation function.

#error

INTERNAL. Indicates whether or not a form element has been flagged as having an error.

#executes_submit_callback

Used by: button, image_button, submit

Description: Indicates whether or not button should submit the form.

Values: TRUE or FALSE

#limit_validation_errors

Used by: button, image_button, submit

Description: Provides an array of sections which are parts of $form_state['values'] which should be validated, implying that sections which are not listed should not be validated. This is normally used in multistep forms in the case of a "back" button, for example, where '#limit_validation_errors' => array() would mean not to validate anything as form values on the current page are to be discarded anyway. #limit_validation_errors does not have any effect if #submit is not set. More discussion is in the form_set_error() documentation.

Values: array indicating sections of the $form_state['values'] which should be validated.

#field_prefix

Used by: textfield

Description: Text or code that is placed directly in front of the textfield. This can be used to prefix a textfield with a constant string.

Values: Mixed

Usage example (system.module):

<?php
$form['site_403'] = array(
  '#type' => 'textfield',
  '#title' => t('Default 403 (access denied) page'),
  '#default_value' => variable_get('site_403', ''),
  '#size' => 40,
  '#description' => t('This page is displayed when the requested document is denied to the current user. If unsure, specify nothing.'),
  '#field_prefix' => url(NULL, NULL, NULL, TRUE) . (variable_get('clean_url', 0) ? '' : '?q=')
);
?>

#field_suffix

Used by: textfield

Description: Text or code that is placed directly after a textfield. This can be used to add a unit to a textfield.

Values: Mixed

Usage example (system.module):

<?php
$form['settings_general']['upload_usersize_default'] = array(
  '#type' => 'textfield',
  '#title' => t('Default total file size per user'),
  '#default_value' => $upload_usersize_default,
  '#size' => 5,
  '#maxlength' => 5,
  '#description' => t('The default maximum size of all files a user can have on the site.'),
  '#field_suffix' => t('MB')
);
?>

#group

Used by: fieldset

Description: Specifies a group that can be used to group fieldsets into vertical tabs.

Values: A string where the value is used for the id of a form element with the #type of vertical_tabs.

Usage example (user.admin.inc):

<?php
$form['email'] = array(
  '#type' => 'vertical_tabs',
);
...
 $form['email_admin_created'] = array(
  '#type' => 'fieldset',
  '#title' => t('Welcome (new user created by administrator)'),
  '#collapsible' => TRUE,
  '#collapsed' => (variable_get('user_register', 1) != 0),
  '#description' => t('Edit the welcome e-mail messages sent to new member accounts created by an administrator.'),
  '#group' => 'email'
);
?>

#header

Used by: tableselect

Description: Column headers.

Values: Associative array where the keys are the field names to use for each column, and the values are the translated text to display for each column header.

#id

INTERNAL. Used to populate form elements' id property. In rare cases, you can set this value yourself on a form element, to override the default setting.

#input

INTERNAL. Indicates whether or not input is possible for this form element.

#js_select

Used by: tableselect

Description: Whether to include a select all checkbox.

Values: TRUE to add a select all box to each row of the table, FALSE to omit the select all box. Only applies if #multiple is also TRUE.

#markup

Used by: item, markup

Description: Used to set HTML that will be output on the form.

Values: Text (valid HTML)

Usage example (contact.module):

<?php
  $form['from'] = array(
    '#type' => 'item',
    '#title' => t('From'),
    '#markup' => check_plain($user->name) . ' &lt;' . check_plain($user->mail) . '&gt;',
  );
?>

#maxlength

Used by: password, textfield

Description: The maximum amount of characters to accept as input.

Values: A positive number.

Usage example (forum.module):

<?php
$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Subject'),
  '#default_value' => $node->title,
  '#size' => 60,
  '#maxlength' => 128,
  '#required' => TRUE,
);
?>

#method

Used by: form

Description: The HTTP method with which the form will be submitted.

Values: GET or POST. Default is POST.

Usage example (node.module):

<?php
$form['#method'] = 'post';
?>

#multiple

Used by: select, tableselect

Description: Indicates whether the user may select more than one item.

Values: TRUE or FALSE

Usage example (taxonomy.module):

<?php
 return array(
  '#type' => 'select',
  '#title' => $title,
  '#default_value' => $value,
  '#options' => $options,
  '#description' => $description,
  '#multiple' => $multiple,
  '#size' => $multiple ? min(12, count($options)) : 0,
  '#weight' => -15,
);
?>

#name

Used by: button, submit

Values: String.

#options

Used by: checkboxes, radios, select, tableselect

Description: Selectable options for a form element that allows multiple choices.

Values: An array in the form of array(t('Display value 1'), t('Display value 2')) or array('return_value1' => t('Display Value 1'), 'return_value2' => t('Display Value 2')) if specific return values are required.

Usage example (comment.module):

<?php
$form['posting_settings']['comment_preview'] = array(
  '#type' => 'radios',
  '#title' => t('Preview comment'),
  '#default_value' => variable_get('comment_preview', 1),
  '#options' => array(t('Optional'), t('Required')),
);
?>

#parents

Used by: All

Description: Identifies parent form elements. See #tree and #parents in the handbook and the complete comparison between #parents and #array_parents.

Values: An array of element names.

Usage example (comment.module):

<?php
$form['admin']['status'] = array(
  '#type' => 'radios',
  '#parents' => array('status'),
  '#title' => t('Status'),
  '#default_value' => $status,
  '#options' => array(t('Published'), t('Not published')),
  '#weight' => -1,
);
?>

#post_render

Used by: All elements and forms

Description: Function(s) to call after rendering in drupal_render() has occured. The named function is called with two arguments, the rendered element and its children. It returns the (potentially) altered) element content.

Values: An array of function names to call.

Usage example:

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

<?php
$form['admin']['#post_render'] = array('admin_form_html_cleanup');
?>

This example would call admin_form_html_cleanup($content, $element) after $element has been rendered to $content via drupal_render(). $content may then be modified and must be returned.

#prefix

Used by: All elements and forms.

Description: Text or markup to include before the form element. Also see #suffix.

Values: Mixed

Usage example (poll.module):

<?php
$form['choice'] = array(
  '#type' => 'fieldset',
  '#title' => t('Choices'),
  '#prefix' => '<div class="poll-form">',
  '#suffix' => '</div>',
  '#tree' => TRUE,
);
?>

#pre_render

Used by: All elements and forms.

Description: Function(s) to call before rendering in drupal_render() has occured. The function(s) provided in #pre_render receive the element as an argument and must return the altered element.

Values: An array of function names to call.

Usage example (filter.module):

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! As demonstrated here, you will probably want to add to the existing array rather than writing over it.

// Prepend #pre_render callback to replace field value with user notice
// prior to rendering.
if (!isset($element['value']['#pre_render'])) {
  $element['value']['#pre_render'] = array();
}
array_unshift($element['value']['#pre_render'], 'filter_form_access_denied');

...
function filter_form_access_denied($element) {
  $element['#value'] = t('This field has been disabled because you do not have sufficient permissions to edit it.');
  return $element;
}

This example would call filter_form_access_denied($element) before the $element has been rendered via drupal_render(). $element may then be modified and is returned for rendering.

#printed

INTERNAL. Used to determine whether or not a form element has been printed yet.

#process

Used by: All

Description: An array of functions that are called when an element is processed. Using this callback, modules can "register" further actions. For example the "radios" form type is expanded to multiple radio buttons using a processing function.

Values: Array of function names (strings)

Usage example (system.module) in system_element_info():

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

$type['radios'] = array('#input' => TRUE, '#process' => array('expand_radios'));

In this example, the function expand_radios is called; the entire radios element is passed in as the argument. This function adds new elements of type radio to the existing radios element array, with keys and values corresponding to the processed element's #options.

#processed

INTERNAL. Used to ascertain whether or not a form element has been processed (ie: expanded to multiple elements).

#required

Used by: checkbox, checkboxes, date, file, password, password_confirm, radio, radios, select, textarea, textfield, weight

Description: Indicates whether or not the element is required. This automatically validates for empty fields, and flags inputs as required. File fields are NOT allowed to be required.

Values: TRUE or FALSE

Usage example (forum.module):

<?php
$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Subject'),
  '#default_value' => $node->title,
  '#size' => 60,
  '#maxlength' => 128,
  '#required' => TRUE,
);
?>

#resizable

Used by: textarea

Description: Whether users should be allowed to resize the text area

Values: TRUE or FALSE

#return_value

Used by: checkbox, image_button, radio

Description: Value element should return when selected

Values: Mixed

Usage example (poll.module):

<?php
$form['morechoices'] = array(
  '#type' => 'checkbox',
  '#title' => t('Need more choices'),
  '#return_value' => 1,
  '#default_value' => 0,
  '#description' => t("If the amount of boxes above isn't enough, check this box and click the Preview button below to add some more."),
);
?>

#rows

Used by: textarea

Description: How many rows high the textarea should be (see also #cols)

Values: A positive number

Usage example (aggregator.module):

<?php
$form['description'] = array(
  '#type' => 'textarea',
  '#title' => t('Description'),
  '#default_value' => $edit['description'],
  '#cols' => 60,
  '#rows' => 5,
);
?>

#size

Used by: password, password_confirm, select, textfield

Description: Width of the textfield (in characters) or size of multiselect box (in lines).

Values: A positive number.

Usage example (comment.module):

<?php
        $form['admin']['homepage'] = array(
          '#type' => 'textfield',
          '#title' => t('Homepage'),
          '#maxlength' => 255,
          '#size' => 30,
          '#default_value' => $edit['homepage'],
        );
?>

#states

Used by: any element

Description:  Adds JavaScript to the element to allow it to have different active states.

Values: A structured array describing the different JavaScript states that can be applied to the element when certain conditions are met. Please read the extensive description of this feature at drupal_process_states().

Usage example

$form['email_canceled']['settings'] = array(
    '#type' => 'container',
    '#states' => array(
      // Hide the settings when the cancel notify checkbox is disabled.
      'invisible' => array(
        'input[name="email_canceled_toggle"]' => array('checked' => FALSE),
      ),
    ),
  );

#submit

Used by: button, image_button, submit, form

Description:  A list of custom submit functions that will be called when the element is submitted. This is usually to add additional submit functions to a form, or to use an alternate function rather than the default form validation function which is the form ID with _submit appended to it.

Values: An array of function names. Each such function will take $form and $form_state as parameters.

Usage example (node_form()):

if (!empty($node->nid) && node_access('delete', $node)) {
 $form['actions']['delete'] = array(
  '#type' => 'submit',
  '#value' => t('Delete'),
  '#weight' => 15,
  '#submit' => array('node_form_delete_submit'),
 );

#suffix

Used by: All elements and forms.

Description: Text or markup to include after the form element. Also see #prefix.

Values: Mixed

Usage example (poll.module):

<?php
$form['choice'] = array(
  '#type' => 'fieldset',
  '#title' => t('Choices'),
  '#prefix' => '<div class="poll-form">',
  '#suffix' => '</div>',
  '#tree' => TRUE,
);
?>

#theme

Used by: All elements and forms.

Description: Theme function to call for element. It must render this element and all of its child elements.

Values: The name of a theme function, without the initial theme_.

Usage example (upload.module):

<?php
$form['#theme'] = 'upload_form_new';
?>

#theme_wrappers

Used by: All elements and forms.

Description: Theme function to call for element, after the element and children are rendered, but before the #post_render functions are called.

Values: The name of a theme function, without the initial theme_.

Usage example (system.module from definition of default properties for a form):

<?php
$type['form'] = array( '#theme_wrappers' =>'form' );
?>

#title

Used by: checkbox, checkboxes, date, fieldset, file, item, password, password_confirm, radio, radios, select, textarea, textfield, weight

Description: The title of the form element. Make sure to enclose inside the t() function so this property can be translated.

Values: Mixed

Usage example (aggregator.module):

<?php
$form['description'] = array(
  '#type' => 'textarea',
  '#title' => t('Description'),
  '#default_value' => $edit['description'],
  '#cols' => 60,
  '#rows' => 5,
);
?>

#title_display

Used by: checkbox, checkboxes, date, fieldset, file, item, password, password_confirm, radio, radios, select, textarea, textfield, weight

Description: Indicates how the label should be rendered. The label includes the #title and the required marker, if #required. If the #title is empty but the field is #required, the label will contain only the required marker.

Values: String.

Possible values:

  • before: The label is output before the element. This is the default for most elements.
  • after: The label is output after the element. For example, this is used for radio and checkbox #type elements as set in system_elements().
  • invisible: #title is rendered as a label element before the form element in the page markup, and is made invisible with the Drupal 7 .element-invisible system CSS class (system.base.css). This makes #title remain available to screen-reader users, but hides it from being displayed visually in the browser.
  • attribute: Set the title attribute on the element to create a tooltip but output no label element. This is supported only for checkboxes and radios in form_pre_render_conditional_form_element(). It is used where a visual label is not needed, such as a table of checkboxes where the row and column provide the context. The tooltip will include the title and required marker.

Usage example (block.module):

<?php
$form['blocks'][$key]['weight'] = array(
 '#type' => 'weight',
 '#default_value' => $block['weight'],
 '#delta' => $weight_delta,
 '#title_display' => 'invisible',
 '#title' => t('Weight for @block block', array('@block' => $block['info'])),
);
?>

#tree

Used by: All

Description: Used to allow collections of form elements. Normally applied to the "parent" element, as the #tree property cascades to sub-elements. Use where you previously used ][ in form_ calls. For more information, see #tree and #parents in the handbook.

Values: TRUE or FALSE

Usage example (system.module):

<?php
$form['status'] = array(
  '#type' => 'checkboxes',
  '#default_value' => $status,
  '#options' => $options,
  '#tree' => TRUE,
);
 $required = array('block', 'filter', 'system', 'user', 'watchdog');
foreach ($required as $require) {
   $form['status'][$require] = array(
    '#type' => 'hidden',
    '#value' => 1,
    '#suffix' => t('required'),
  );
}
?>

#type

Used by: All

Description: Used to determine the type of form element.

Values: button, checkbox, checkboxes, date, fieldset, file, form, hidden, image_button, item, machine_name, markup, password, password_confirm, radio, radios, select, submit, tableselect, textarea, textfield, token, value, vertical_tabs, weight

Usage example (locale.module):

<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>

#validate

Used by: button, image_button, form, submit

Description: A list of custom validation functions that need to be passed.This is usually used to add additional validation functions to a form, or to use an alternate function rather than the default form validation function which is the form ID with _validate appended to it.

Values: An array of function names. Each such function will take $form and $form_state as parameters and should use form_set_error() if the form values do not pass validation. For example:

function test_form_validate($form, &$form_state) {
  if ($form_state['values']['name'] == '') {
    form_set_error('name', t('You must select a name for this group of settings.'));
  }
}

Usage example (node.module):

Note: If you are altering an existing form via hook_form_alter() or a similar means, be careful with this property! You will probably want to add to the existing array rather than writing over it, so don't follow this usage example exactly.

<?php
    // Node types:
    $types = array_map('check_plain', node_get_types('names'));
    $form['advanced']['type'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Only of the type(s)'),
      '#prefix' => '<div class="criterion">',
      '#suffix' => '</div>',
      '#options' => $types,
    );
    $form['advanced']['submit'] = array(
      '#type' => 'submit',
      '#value' => t('Advanced search'),
      '#prefix' => '<div class="action">',
      '#suffix' => '</div>',
    );

    $form['#validate'][] = 'node_search_validate';
?>

#validation_arguments

INTERNAL

#value

Used by: button, hidden, image_button, submit, token, value

Description: Used to set values that cannot be edited by the user. Should NOT be confused with #default_value, which is for form inputs where users can override the default value.

Values: Mixed (text or numbers)

Usage example (locale.module):

<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>

#weight

Used by: All elements.

Description: Used to sort the list of form elements before being output; lower numbers appear before higher numbers.

Values: A positive or negative number (integer or decimal)

Usage example (book.module):

<?php
$form['parent'] = array(
   '#type' => 'select',
  '#title' => t('Parent'),
  '#default_value' => ($node->parent ? $node->parent : arg(4)),
  '#options' => book_toc($node->nid),
  '#weight' => -15,
  '#description' => t('The parent that this page belongs in. Note that pages whose parent is &lt;top-level&gt; are regarded as independent, top-level books.'),
);
?>