Same filename and directory in other branches
This document provides a programmer's reference to the Drupal Forms API. If you're interested in step-by-step documentation to help you write forms, please see the Forms 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 | password | radio | radios | select | textarea | textfield | weight |
---|---|---|---|---|---|---|---|---|---|---|---|---|
#access | 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 |
#attributes | X | X | X | X | X | X | X | X | X | X | X | X |
#autocomplete_path | - | - | - | - | - | - | - | - | - | - | X | - |
#base | ||||||||||||
#collapsed | - | - | - | X | - | - | - | - | - | - | - | - |
#collapsible | - | - | - | X | - | - | - | - | - | - | - | - |
#cols | - | - | - | - | - | - | - | - | - | X | - | - |
#default_value | 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 |
#disabled | X | X | X | - | X | X | X | X | X | X | X | X |
#field_prefix | - | - | - | - | - | - | - | - | - | - | X | - |
#field_suffix | - | - | - | - | - | - | - | - | - | - | X | - |
#maxlength | - | - | - | - | - | - | - | - | - | - | X | - |
#multiple | - | - | - | - | - | - | - | - | X | - | - | - |
#options | - | X | - | - | - | - | - | X | X | - | - | - |
#parents | ||||||||||||
#prefix | X | X | X | X | X | X | X | X | X | X | X | X |
#required | X | X | X | - | - | X | X | X | X | X | X | X |
#return_value | X | X | - | - | - | - | X | X | - | - | - | - |
#rows | - | - | - | - | - | - | - | - | - | X | - | - |
#size | - | - | - | - | - | - | - | - | X | - | X | - |
#suffix | X | X | X | X | X | X | X | X | X | X | X | X |
#theme | X | X | X | X | X | X | X | X | X | X | X | - |
#title | 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 |
#validate | ||||||||||||
#weight | X | X | X | X | X | X | X | X | X | X | X | X |
Special Elements
#type | button | form | hidden | markup | item | submit | value |
---|---|---|---|---|---|---|---|
#after_build | X | X | X | X | X | X | - |
#action | - | X | - | - | - | - | - |
#attributes | X | X | - | X | - | X | - |
#built | - | X | - | - | - | - | - |
#button_type | X | - | - | - | - | X | - |
#default_value | - | - | - | - | - | - | - |
#description | - | - | - | - | X | - | - |
#method | - | X | - | - | - | - | - |
#parents | - | - | - | - | - | - | - |
#prefix | X | X | X | X | X | X | - |
#redirect | - | X | - | - | - | - | - |
#required | - | - | - | - | X | - | - |
#return_value | - | - | - | - | - | - | - |
#submit | X | X | - | - | - | X | - |
#suffix | X | X | X | X | X | X | - |
#theme | X | X | X | X | X | X | - |
#title | - | - | - | - | X | - | - |
#tree | X | X | X | X | X | X | - |
#validate | |||||||
#value | X | X | X | X | X | X | X |
#weight | X | - | - | X | X | X | - |
Default Values
The following is a list of default values which do not need to be set (found in system_elements):
- button
- #name = 'op'
- #button_type = 'submit'
- #submit = FALSE
- checkbox
- #return_value = 1
- checkboxes
- #tree = 1
- fieldset
- #collapsible = FALSE
- #collapsed = FALSE
- file
- #size = 60
- form
- #method = 'post'
- #action = request_uri()
- markup
- item
- password
- #size = 30
- #maxlength = 64
- submit
- #name = 'op'
- #button_type = 'submit'
- #submit = TRUE
- textarea
- textfield
- #size = 60
- #maxlength = 128
- #autocomplete_path = FALSE
- weight
- #delta = 10
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: #attributes, #button_type (default: submit), #submit (default: FALSE), #name (default: op), #prefix, #suffix, #type. #value, #weight
Usage example (node.module):
<?php
$form['preview'] = array(
'#type' => 'button',
'#value' => t('Preview'),
'#weight' => 19,
);
?>
checkbox
Description: Format a checkbox.
Properties: #attributes, #default_value, #description, #prefix, #required, #return_value (default: 1), #suffix, #title, #type. #weight
Usage example (contact.module):
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: #attributes, #default_value, #description, #options, #prefix, #required, #suffix, #title, #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: #attributes, #default_value, #description, #prefix, #required, #suffix, #title, #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: #attributes, #collapsed (default: FALSE), #collapsible (default: FALSE), #description, #prefix, #suffix, #title, #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.
Properties: #attributes, #description, #prefix, #required, #size (default: 60), #suffix, #title, #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: #action (default: request_uri()), #attributes, #method (default: 'post'), #prefix, #submit, #suffix
Usage example:
N/A
hidden
Description: Store data in a hidden form field.
Properties: #prefix, #suffix, #type, #value
Usage example (block.module):
<?php
$form['bid'] = array('#type' => 'hidden', '#value' => $bid);
?>
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: #attributes, #prefix (default: ''), #suffix (default: ''), #type. #value, #weight
Usage example (contact.module):
<?php
$form['contact_information'] = array(
'#value' => variable_get('contact_form_information', t('You can leave us a message using the contact form below.')),
);
?>
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: #description, #prefix (default: ''), #required, #suffix (default: ''), #title, #type, #value, #weight
Usage example (contact.module):
<?php
$form['from'] = array(
'#type' => 'item',
'#title' => t('From'),
'#value' => $user->name .' <'. $user->mail .'>',
);
?>
password
Description: Format a single-line text field that does not display its contents visibly.
Properties: #attributes, #description, #maxlength (default: 30), #prefix, #required, #size (default: 64), #suffix, #title, #type. #weight
Usage example (user.module):
<?php
$form['pass'] = array(
'#type' => 'password',
'#title' => t('Password'),
'#maxlength' => 64,
'#size' => 15,
);
?>
radio
Description: Format a radio button.
Properties: #attributes, #default_value, #description, #prefix, #required, #suffix, #title, #type. #weight
Usage example:
N/A
radios
Description: Format a set of radio buttons.
Properties: #attributes, #default_value, #description, #options, #prefix, #required, #suffix, #title, #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: #attributes, #default_value, #description, #multiple, #options, #prefix, #required, #suffix, #title, #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: #attributes, #button_type (default: 'submit'), #submit (default: TRUE), #name (default: 'op'), #prefix, #suffix, #type. #value, #weight
Usage example (locale.module):
<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>
textarea
Description: Format a multiple-line text field.
Properties: #attributes, #cols (default: 60), #default_value, #description, #prefix, #required, #suffix, #title, #type. #rows (default: 5), #weight
Usage example (forum.module):
<?php
$form['body'] = array(
'#type' => 'textarea',
'#title' => t('Body'),
'#default_value' => $node->body,
'#required' => TRUE
);
?>
textfield
Description: Format a single-line text field.
Properties: #attributes, #autocomplete_path (default: FALSE), #default_value, #description, #field_prefix, #field_suffix, #maxlength (default: 128), #prefix, #required, #size (default: 60), #suffix, #title, #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,
);
?>
value
Description: A form value that is internal to the form and never displayed to the screen.
Usage example (node.module):
<?php
$form['vid'] = array('#type' => 'value', '#value' => $node->vid);
?>
weight
Description: Format a weight selection menu.
Properties: #attributes, #delta (default: 10), #default_value, #description, #prefix, #required, #suffix, #title, #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
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']);
?>
Do not forget the # before property names.
#after_build
An array of function names which will be called after the form is built. Example: node preview.
Usage example (system.module):
<?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) {
file_check_directory($form_element['#value'], FILE_CREATE_DIRECTORY, $form_element['#parents'][0]);
return $form_element;
}
?>
Property names without # signs causes havoc.
#attributes
Used by: button, checkbox, checkboxes, date, fieldset, file, form, markup, password, radio, radios, select, submit, 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):
<?php
$form['#attributes'] = array('class' => 'search-form');
?>
The # is mandatory before property names.
#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,
);
?>
It's very important that you do not forget the # before property names.
#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.
The first character of property names is #.
#base
Define an alternate base name for the validate and submit function names. Will be used if the functions corresponding to the form id do not exist.
Usage example (system.module):
<?php
$form['#base'] = 'system_settings_form';
?>
#button_type
Description: Indicates CSS class to use for button(form-button_type)
Values: submit, ???
Usage example: (system.module):
<?php
$type['submit'] = array(
'#input' => TRUE,
'#name' => 'op',
'#button_type' => 'submit',
'#submit' => TRUE,
);
?>
Developers should take care to not forget the first # character in property names.
#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,
);
?>
Child names do not have a # as first char, but property names do.
#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,
);
?>
One of the most important things about form API is not forgetting the # where it's appropriate.
#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,
);
?>
The first # lets form API decide between a property name and a child.
#default_value
Used by: button, checkbox, checkboxes, date, file, markup, password, radio, radios, select, submit, textarea, textfield, 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,
);
?>
How many different forms of warnings can I figure out to tell you that the first # in property names are important?
#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.'),
);
?>
One of the most common errors for 4.7 is leaving out the # in the beginning of property names.
#description
Used by: checkbox, checkboxes, date, fieldset, file, markup, password, 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: checkbox, checkboxes, date, file, password, radio, radios, select, textarea, textfield, weight
Description: Disables (greys out) a form input element.
Values: TRUE or FALSE
Usage example (system.module):
<?php
if (isset($disabled[$name])) {
$form['theme_settings'][$name]['#disabled'] = TRUE;
}
?>
It can not be stressed enough that property names begin with a #.
#error
INTERNAL. Indicates whether or not a form element has been flagged as having an error.
#id
INTERNAL. Used to populate form elements' id property.
#input
INTERNAL. Indicates whether or not input is possible for this form element.
#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')
);
#maxlength
Used by: 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,
);
?>
You can spare lots of debug time by not forgetting the # in the beginning of property names.
#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
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,
);
?>
By now, you probably know that the first character of property names is # but I thought some repetition can't hurt.
#name
INTERNAL. Refers to the name of an element ('foo' in $form['foo'])
#options
Used by: checkboxes, radios, select
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')),
);
?>
If you are fed up with comments about # being the first character of property names, then sorry, but it's important.
#parents
Used by: All
Description: Identifies parent form elements. See #tree and #parents in the handbook.
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,
);
?>
While the first character of the words parents and property is P, the first character of every property is #.
#prefix
Used by: button, checkbox, checkboxes, date, fieldset, file, form, hidden, markup, password, radio, radios, select, submit, textarea, textfield, weight
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,
);
?>
The correct prefix of a property name is the #.
#printed
INTERNAL. Used to determine whether or not a form element has been printed yet.
#process
INTERNAL. Used to modify a form element.
#processed
INTERNAL. Used to ascertain whether or not a form element has been processed (ie: expanded to multiple elements).
#redirect
Used by: form
Description: The default goto value after form is submitted. This value should be returned by a form's submit callback function, but altering another form's #redirect value by using hook_form_alter() can be useful to change where that form redirects after it is submitted. Also see #action.
Values: An internal path or an array of arguments to pass to url(). The value may also be set to FALSE
to prevent redirection after form submission.
Usage example (locale.inc):
<?php
$form['#redirect'] = 'node';
?>
<?php
$form['#redirect'] = array('user/login', 'destination=node');
?>
<?php
$form['#redirect'] = FALSE;
?>
Only heathens leave out the # before property names.
#required
Used by: checkbox, checkboxes, date, file, password, 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,
);
?>
You know what's absolutely required? The # in the beginning of property names.
#return_value
Used by: checkbox, checkboxes, radio, radios
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."),
);
?>
Let's make this remark short: #
#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,
);
?>
Your code will row with you if you forget the # in the beginning of property names.
#submit
Description: Indicates whether or not button should submit the form. When set for the form itself, indicates the submit handler for the form.
Values: TRUE or FALSE. For form, an array in the form array('submit_function_1' => array('arg1a', 'arg1b',..), 'submit_function_2' => array('arg2a', 'arg2b'..))
.
#size
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'],
);
?>
If you forget the # sign...
#suffix
Used by: button, checkbox, checkboxes, date, fieldset, file, form, hidden, markup, password, radio, radios, select, submit, textarea, textfield, weight
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,
);
?>
Suffix is almost suffer which will happen if you forget the # in the beginning of property names.
#theme
Used by: button, checkbox, checkboxes, date, fieldset, file, form, hidden, markup, password, radio, radios, select, submit, textarea, textfield
Description: Theme function to call for element.
Values: The name of a theme function, without the initial theme_.
Usage example (upload.module):
<?php
$form['#theme'] = 'upload_form_new';
?>
#title
Used by: checkbox, checkboxes, fieldset, date, file, password, 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,
);
?>
#tree
Used by: button, checkbox, checkboxes, date, fieldset, file, form, hidden, markup, password, radio, radios, select, submit, textarea, textfield, weight
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, markup, password, radio, radios, select, submit, textarea, textfield, value, weight
Usage example (locale.module):
<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>
#validate
Used by: ???
Description: A list of custom validation functions that need to be passed. Function declarations are written as thing_to_test, and thing_to_test is passed into #validate, which will indicate that that function needs to be passed.
Values: Mixed
Usage example (filter.module):
<?php
$form['format'][$format->format] = array(
'#type' => 'filter_format',
'#title' => $format->name,
'#default_value' => $value,
'#return_value' => $format->format,
'#parents' => array('format'),
'#description' => theme('filter_tips', _filter_tips($format->format, false)),
'#validate' => array('filter_form_validate' => array()),
);
?>
While #validate makes sure that user data is valid, nothing validates the form for missing # in the beginning of property name.
#validation_arguments
INTERNAL
#value
Used by: button, hidden, markup, submit
Description: Used to set values that cannot be edited by the user. Should NOT be confused with #default_value, which is for controls where users can override the pre-existing value.
Values: Mixed (text or numbers)
Usage example (locale.module):
<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>
#weight
Used by: button, checkbox, checkboxes, date, fieldset, file, markup, password, radio, radios, select, submit, textarea, textfield, weight
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 <top-level> are regarded as independent, top-level books.'),
);
?>
File
developer/topics/forms_api_reference.htmlView source
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Form API Reference</title> <style type="text/css"> h2 { border-bottom: 100% dashed 1px; } h3 { background-color: #dfedf7; } td { text-align: center; } .help { background-color: #ffc; } .x { background-color: #dfedf7; } .verified { background-color: #CFC; } .style1 {color: #0000bb} .style2 {color: #dd0000} .style3 {color: #007700} </style> </head> <body> <h1>Form API Reference</h1> <p>This document provides a programmer's reference to the Drupal Forms API. If you're interested in step-by-step documentation to help you write forms, please see the <a href="http://api.drupal.org/api/file/developer/topics/forms_api.html/5">Forms API QuickStart guide</a>.</p> <p>Skip to: <a href="#properties">Properties</a> | <a href="#element_default_values">Default Values</a> | <a href="#elements">Elements</a> </p> <h2>Form Controls </h2> <p><strong>Legend:</strong><br /> <strong>X</strong> = attribute can be used with this type<br /> <strong>-</strong> = this attribute is not applicable to this type</p> <table border="1"> <tr> <th scope="col"><a href="#type"><strong>#type</strong></a></th> <th scope="col"><a href="#checkbox">checkbox</a></th> <th scope="col"><a href="#checkboxes">checkboxes</a></th> <th scope="col"><a href="#date">date</a></th> <th scope="col"><a href="#fieldset">fieldset</a></th> <th scope="col"><a href="#file">file</a></th> <th scope="col"><a href="#password">password</a></th> <th scope="col"><a href="#radio">radio</a></th> <th scope="col"><a href="#radios">radios</a></th> <th scope="col"><a href="#select">select</a></th> <th scope="col"><a href="#textarea">textarea</a></th> <th scope="col"><a href="#textfield">textfield</a></th> <th scope="col"><a href="#weight">weight</a></th> </tr> <tr> <th scope="row"><a href="#access">#access</a></th> <td class="x"><strong>X</strong></td> <!-- checkbox --> <td class="x"><strong>X</strong></td> <!-- checkboxes --> <td class="x"><strong>X</strong></td> <!-- date --> <td class="x"><strong>X</strong></td> <!-- fieldset --> <td class="x"><strong>X</strong></td> <!-- file --> <td class="x"><strong>X</strong></td> <!-- password --> <td class="x"><strong>X</strong></td> <!-- radio --> <td class="x"><strong>X</strong></td> <!-- radios --> <td class="x"><strong>X</strong></td> <!-- select --> <td class="x"><strong>X</strong></td> <!-- textarea --> <td class="x"><strong>X</strong></td> <!-- textfield --> <td class="x"><strong>X</strong></td> <!-- weight --> </tr> <tr> <th scope="row"><a href="#after_build">#after_build</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#attributes">#attributes</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#autocomplete_path">#autocomplete_path</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr class="help"> <th scope="row"><a href="#base">#base</a></th> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <th scope="row"><a href="#collapsed">#collapsed</a></th> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#collapsible">#collapsible</a></th> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#cols">#cols</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#default_value">#default_value</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#delta">#delta</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#description">#description</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#disabled">#disabled</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td><strong>-</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#field_prefix">#field_prefix</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#field_suffix">#field_suffix</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#maxlength">#maxlength</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#multiple">#multiple</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#options">#options</a></th> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr class="help"> <th scope="row"><a href="#parents">#parents</a></th> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <th scope="row"><a href="#prefix">#prefix</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#required">#required</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#return_value">#return_value</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#rows">#rows</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#size">#size</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#suffix">#suffix</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#theme">#theme</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#title"><strong>#title</strong></a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#tree">#tree</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr class="help"> <th scope="row"><a href="#validate">#validate</a></th> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <th scope="row"><a href="#weightval">#weight</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> </table> <h2>Special Elements </h2> <table border="1"> <tr> <th scope="col"><a href="#type">#</a><a href="#type">type</a></th> <th scope="col"><a href="#button">button</a></th> <th scope="col"><a href="#form">form</a></th> <th scope="col"><a href="#hidden">hidden</a></th> <th scope="col"><a href="#markup">markup</a></th> <th scope="col"><a href="#item">item</a></th> <th scope="col"><a href="#submit">submit</a></th> <th scope="col"><a href="#val">value</a></th> </tr> <tr> <th scope="row"><a href="#after_build">#after_build</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#action">#action</a></th> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#attributes">#attributes</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#built">#built</a></th> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#button_type">#button_type</a></th> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#default_value">#default_value</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#description">#description</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#method">#method</a></th> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr class="help"> <th scope="row"><a href="#parents">#parents</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#prefix">#prefix</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#redirect">#redirect</a></th> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#required">#required</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#return_value">#return_value</a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#submit_property">#submit</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#suffix">#suffix</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#theme">#theme</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr> <th scope="row"><a href="#title"><strong>#title</strong></a></th> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> </tr> <tr> <th scope="row"><a href="#tree">#tree</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> <tr class="help"> <th scope="row"><a href="#validate">#validate</a></th> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> <td> </td> </tr> <tr> <th scope="row"><a href="#value">#value</a></th> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> </tr> <tr> <th scope="row"><a href="#weightval">#weight</a></th> <td class="x"><strong>X</strong></td> <td>-</td> <td>-</td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td class="x"><strong>X</strong></td> <td>-</td> </tr> </table> <h2><a name="element_default_values" id="element_default_values"></a>Default Values</h2> <p>The following is a list of default values which do not need to be set (found in system_elements):</p> <ul> <li><strong><a href="#button">button</a></strong> <ul> <li><a href="#name">#name</a> = 'op'</li> <li><a href="#button_type">#button_type</a> = 'submit'</li> <li><a href="#submit_property">#submit</a> = FALSE</li> </ul> </li> <li><strong><a href="#checkbox">checkbox</a></strong> <ul> <li><a href="#return_value">#return_value</a> = 1 </li> </ul> </li> <li><strong><a href="#checkboxes">checkboxes</a></strong> <ul> <li><a href="#tree">#tree</a> = 1 </li> </ul> </li> <li><a href="#fieldset"><strong>fieldset</strong></a> <ul> <li><a href="#collapsible">#collapsible</a> = FALSE</li> <li><a href="#collapsed">#collapsed</a> = FALSE </li> </ul> </li> <li><strong><a href="#file">file</a></strong> <ul> <li><a href="#size">#size</a> = 60 </li> </ul> </li> <li><strong><a href="#form">form</a> </strong> <ul> <li><a href="#method">#method</a> = 'post'</li> <li><a href="#action">#action</a> = request_uri()</li> </ul> </li> <li><a href="#markup"><strong>markup</strong></a> <ul> <li><a href="#prefix">#prefix</a> = '' </li> <li><a href="#suffix">#suffix</a> = '' </li> </ul> </li> <li><a href="#item"><strong>item</strong></a> <ul> <li><a href="#prefix">#prefix</a> = '' </li> <li><a href="#suffix">#suffix</a> = '' </li> </ul> </li> <li><strong><a href="#password">password</a> </strong> <ul> <li><a href="#size">#size</a> = 30</li> <li><a href="#maxlength">#maxlength</a> = 64 </li> </ul> </li> <li><strong><a href="#submit">submit</a></strong> <ul> <li><a href="#name">#name</a> = 'op'</li> <li><a href="#button_type">#button_type</a> = 'submit'</li> <li><a href="#submit_property">#submit</a> = TRUE</li> </ul> </li> <li><strong><a href="#textarea">textarea</a></strong> <ul> <li><a href="#cols">#cols</a> = 60 </li> <li><a href="#rows">#rows</a> = 5 </li> </ul> </li> <li><strong><a href="#textfield">textfield</a></strong> <ul> <li><a href="#size">#size</a> = 60</li> <li><a href="#maxlength">#maxlength</a> = 128</li> <li><a href="#autocomplete_path">#autocomplete_path</a> = FALSE</li> </ul> </li> <li><strong><a href="#weight">weight</a></strong> <ul> <li><a href="#delta">#delta</a> = 10 </li> </ul> </li> </ul> <p> </p> <h2><a name="elements" id="elements"></a>Elements</h2> <p>Note that property names in <strong>bold</strong> 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. </p> <h3><a name="button" id="button"></a>button</h3> <p> <strong>Description</strong>: 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.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#button_type">#button_type</a> (default: submit), <a href="#submit_property">#submit</a> (default: FALSE), <a href="#name">#name</a> (default: op), <a href="#prefix">#prefix</a>, <a href="#suffix">#suffix</a>, <a href="#type"><strong>#type</strong></a>. <a href="#value"><strong>#value</strong></a>, <a href="#weightval">#weight</a> </p> <p><strong>Usage example </strong>(<a href="http://api.drupal.org/api/file/modules/node/node.module/5">node.module</a>):</p> <div class="codeblock"> <p><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'preview'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'button'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#value' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Preview'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> </font><font color="#0000bb">19,<br /> </font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></p> </div> <h3><a name="checkbox" id="checkbox"></a>checkbox</h3> <p><strong>Description</strong>: Format a checkbox.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#return_value"><strong>#return_value</strong></a> (default: 1), <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/contact/contact.module/5">contact.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'copy'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'checkbox'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> t(</font><font color="#dd0000">'Send me a copy.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="checkboxes" id="checkboxes"></a>checkboxes</h3> <p><strong>Description</strong>: 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.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#options"><strong>#options</strong></a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#tree"><strong>#tree</strong></a> (default: TRUE), <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/node/node.module/5">node.module</a>):</p> <div class="codeblock"> <p><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'node_options_'</font><font color="#007700">. </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">type</font><font color="#007700">] = array(<br /> </font></font></code><code> <font color="#000000"><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'checkboxes'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Default options'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">variable_get</font><font color="#007700">(</font><font color="#dd0000">'node_options_'</font><font color="#007700">. </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">type,</font><font color="#007700"> array(</font><font color="#dd0000">'status'</font><font color="#007700">, </font><font color="#dd0000">'promote'</font><font color="#007700">)),<br /> </font> <font color="#dd0000">'#options' </font><font color="#007700">=> array(</font><font color="#dd0000"><br /> 'status' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Published'</font><font color="#007700">), </font><font color="#dd0000"><br /> 'moderate' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'In moderation queue'</font><font color="#007700">), </font><font color="#dd0000"><br /> 'promote' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Promoted to front page'</font><font color="#007700">),<br /> </font><font color="#dd0000">'sticky' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Sticky at top of lists'</font><font color="#007700">),</font><font color="#007700"><br /> </font><font color="#dd0000">'revision' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Create new revision'</font><font color="#007700">)</font>,<font color="#007700"><br /> ),</font><font color="#007700"><br /> </font> <font color="#dd0000">'#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Users with the <em>administer nodes</em> permission will be able to override these options.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></p> </div> <h3><a name="date" id="date"></a>date</h3> <p><strong>Description</strong>: 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, <code><font color="#007700">array(</font><font color="#dd0000">'year' </font><font color="#007700">=> </font><font color="#0000bb">2007</font><font color="#007700">, </font> <font color="#dd0000">'month' </font><font color="#007700">=> </font><font color="#0000bb">2</font><font color="#007700">, </font> <font color="#dd0000">'day' </font><font color="#007700">=> </font><font color="#0000bb">15</font><font color="#007700">)</font></code> </p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/profile/profile.module/5">profile.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $fields</font><font color="#007700">[</font><font color="#0000bb">$category</font><font color="#007700">][</font><font color="#0000bb">$field</font><font color="#007700">-></font><font color="#0000bb">name</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'date'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">check_plain</font><font color="#007700">(</font><font color="#0000bb">$field</font><font color="#007700">-></font><font color="#0000bb">title</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#0000bb">$field</font><font color="#007700">-></font><font color="#0000bb">name</font><font color="#007700">], </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">_profile_form_explanation</font><font color="#007700">(</font><font color="#0000bb">$field</font><font color="#007700">), </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">$field</font><font color="#007700">-></font><font color="#0000bb">required<br /> </font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="fieldset" id="fieldset"></a>fieldset</h3> <p><strong>Description</strong>: Format a group of form items.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#collapsed"><strong>#collapsed</strong></a> (default: FALSE), <a href="#collapsible"><strong>#collapsible</strong></a> (default: FALSE), <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/contact/contact.module/5">contact.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'contact'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'fieldset'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Contact settings'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> </font><font color="#0000bb">5</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsible' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsed' </font><font color="#007700">=> </font><font color="#0000bb">FALSE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="file" id="file"></a>file</h3> <p><strong>Description</strong>: Format a file upload field.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#size"><strong>#size</strong></a> (default: 60), <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/upload/upload.module/5">upload.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'new'</font><font color="#007700">][</font><font color="#dd0000">'upload'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'file'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Attach new file'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">40,<br /> </font><font color="#007700">);<br /> </font><font color="#0000bb">?></font> </font> </code></div> <h3><a name="form" id="form"></a>form</h3> <p><strong>Description</strong>: A form containing form elements </p> <p><strong>Properties</strong>: <a href="#action">#action</a> (default: request_uri()), <a href="#attributes">#attributes</a>, <a href="#method">#method</a> (default: 'post'), <a href="#prefix">#prefix</a>, <a href="#submit_property">#submit</a>, <a href="#suffix">#suffix</a></p> <p><strong>Usage example</strong>: </p> <p class="help">N/A</p> <h3><a name="hidden" id="hidden"></a>hidden</h3> <p><strong>Description</strong>: Store data in a hidden form field.</p> <p><strong>Properties</strong>: <a href="#prefix">#prefix</a>, <a href="#suffix">#suffix</a>, <a href="#type"><strong>#type</strong></a>, <a href="#value"><strong>#value</strong></a> </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/block/block.module/5">block.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'bid'</font><font color="#007700">] = array(</font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'hidden'</font><font color="#007700">, </font><font color="#dd0000">'#value' </font><font color="#007700">=> </font><font color="#0000bb">$bid</font><font color="#007700">);<br /> </font><font color="#0000bb">?></font> </font></code></div> <h3><a name="markup" id="markup"></a>markup</h3> <p><strong>Description</strong>: Generate generic markup for display inside forms. Note that there is <strong>no need to declare a form element as #type = 'markup'</strong>, as this is the default type. </p> <p>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.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#description"></a> <a href="#prefix">#prefix</a> (default: ''), <a href="#suffix">#suffix</a> (default: ''), <a href="#type">#type</a>. <a href="#value"><strong>#value</strong></a>, <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/contact/contact.module/5">contact.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'contact_information'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#value' </font><font color="#007700">=> </font><font color="#0000bb">variable_get</font><font color="#007700">(</font><font color="#dd0000">'contact_form_information'</font><font color="#007700">, </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'You can leave us a message using the contact form below.'</font><font color="#007700">)),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="item" id="item"></a>item</h3> <p><strong>Description</strong>: Generate a display-only form element allowing for an optional title and description. </p> <p>Note: since this is a read-only field, setting the <a href="#required">#required</a> 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 <a href="#title">#title</a>).</p> <p><strong>Properties</strong>: <a href="#description">#description</a>, <a href="#prefix">#prefix</a> (default: ''), <a href="#required">#required</a>, <a href="#suffix">#suffix</a> (default: ''), <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>, <a href="#value"><strong>#value</strong></a>, <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/contact.module/5">contact.module</a>):</p> <div class="codeblock"> <p><code><font color="#000000"> <font color="#0000bb"><?php<br /> </font></font></code><span class="style1"><code>$form[<span class="style2">'from'</span>] = <span class="style3">array(</span><br /> </code><code><span class="style2">'#type'</span> => <span class="style2">'item'</span>,<br /> <span class="style2">'#title'</span> => t(<span class="style2">'From'</span>),<br /> <span class="style2">'#value'</span> => $user->name .<span class="style2">' &lt;'</span>. $user->mail .<span class="style2">'&gt;'</span>,<br /> <span class="style3">);</span></code></span><code><font color="#000000"><font color="#007700"><br /> </font><font color="#0000bb">?></font></font></code></p> </div> <h3><a name="password" id="password"></a>password</h3> <p><strong>Description</strong>: Format a single-line text field that does not display its contents visibly.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#description">#description</a>, <a href="#maxlength"><strong>#maxlength</strong></a> (default: 30), <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#size"><strong>#size</strong></a> (default: 64), <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/user/user.module/5">user.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'pass'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'password'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Password'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">64</font><font color="#007700">, </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">15</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="radio" id="radio"></a>radio</h3> <p><strong>Description</strong>: Format a radio button.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong>: </p> <p class="help">N/A</p> <h3><a name="radios" id="radios"></a>radios</h3> <p><strong>Description</strong>: Format a set of radio buttons.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#options"><strong>#options</strong></a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">comment.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'posting_settings'</font><font color="#007700">][</font><font color="#dd0000">'comment_preview'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'radios'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Preview comment'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">variable_get</font><font color="#007700">(</font><font color="#dd0000">'comment_preview'</font><font color="#007700">, </font><font color="#0000bb">1</font><font color="#007700">), </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> array(</font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Optional'</font><font color="#007700">), </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Required'</font><font color="#007700">)),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="select" id="select"></a>select</h3> <p><strong>Description</strong>: Format a drop-down menu or scrolling selection box.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#multiple"><strong>#multiple</strong></a>, <a href="#options"><strong>#options</strong></a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'feed'</font><font color="#007700">][</font><font color="#dd0000">'feed_item_length'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000"> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'select'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Display of XML feed items'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">variable_get</font><font color="#007700">(</font><font color="#dd0000">'feed_item_length'</font><font color="#007700">,</font><font color="#dd0000">'teaser'</font><font color="#007700">),<br /> </font><font color="#dd0000"> '#options' </font><font color="#007700">=> array(</font><font color="#dd0000"><br /> 'title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Titles only'</font><font color="#007700">), </font><font color="#dd0000"><br /> 'teaser' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Titles plus teaser'</font><font color="#007700">), </font><font color="#dd0000"><br /> 'fulltext' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Full text'</font><font color="#007700">),<br /> ),<br /> </font><font color="#dd0000"> '#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Global setting for the length of XML feed items that are output by default.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="submit" id="submit"></a>submit</h3> <p><strong>Description</strong>: Format a form submit button.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#button_type">#button_type</a> (default: 'submit'), <a href="#submit_property">#submit</a> (default: TRUE), <a href="#name">#name</a> (default: 'op'), <a href="#prefix">#prefix</a>, <a href="#suffix">#suffix</a>, <a href="#type"><strong>#type</strong></a>. <a href="#value"><strong>#value</strong></a>, <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/locale/locale.module/5">locale.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'submit'</font><font color="#007700">] = array(</font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'submit'</font><font color="#007700">, </font><font color="#dd0000">'#value' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Import'</font><font color="#007700">));<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="textarea" id="textarea"></a>textarea</h3> <p><strong>Description</strong>: Format a multiple-line text field.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#cols"><strong>#cols</strong></a> (default: 60), <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#rows"><strong>#rows</strong></a> (default: 5), <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/forum/forum.module/5">forum.module</a>): </p> <div class="codeblock"> <p><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'body'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'textarea'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Body'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">body</font><font color="#007700">, </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">TRUE<br /> </font></font></code><code><font color="#000000"><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></p> </div> <h3><a name="textfield" id="textfield"></a>textfield</h3> <p><strong>Description</strong>: Format a single-line text field.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#autocomplete_path">#autocomplete_path</a> (default: FALSE), <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#field_prefix">#field_prefix</a>, <a href="#field_suffix">#field_suffix</a>, <a href="#maxlength"><strong>#maxlength</strong></a> (default: 128), <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#size"><strong>#size</strong></a> (default: 60), <a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/forum/forum.module/5">forum.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'title'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'textfield'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Subject'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">title</font><font color="#007700">, </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">128</font><font color="#007700">, </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="val" id="val"></a>value</h3> <p><strong>Description</strong>: A form value that is internal to the form and never displayed to the screen.</p> <p><strong>Properties</strong>: <a href="#type"><strong>#type</strong></a>, <a href="#value"><strong>#value</strong></a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/node/node.module/5">node.module</a>): </p> <p><code><font color="#000000"><font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'vid'</font><font color="#007700">] = </font><font color="#0000bb">array</font><font color="#007700">(</font><font color="#dd0000">'#type'</font> =><font color="#dd0000"> 'value'</font><font color="#007700">,</font> <font color="#dd0000">'#value' </font><font color="#007700">=></font><font color="#dd0000"> </font><font color="#0000bb">$node->vid</font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code> </p> <h3><a name="weight" id="weight"></a>weight</h3> <p><strong>Description</strong>: Format a weight selection menu.</p> <p><strong>Properties</strong>: <a href="#attributes">#attributes</a>, <a href="#delta"><strong>#delta</strong></a> (default: 10), <a href="#default_value"><strong>#default_value</strong></a>, <a href="#description">#description</a>, <a href="#prefix">#prefix</a>, <a href="#required">#required</a>, <a href="#suffix"> </a><a href="#suffix">#suffix</a>, <a href="#title"><strong>#title</strong></a>, <a href="#type"><strong>#type</strong></a>. <a href="#weightval">#weight</a></p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/menu/menu.module/5">menu.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'weight'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Weight'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#delta' </font><font color="#007700">=> </font><font color="#0000bb">10</font><font color="#007700">, </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h2><a name="properties" id="properties"></a>Properties</h2> <h3><a name="access" id="access"></a>#access</h3> <p><strong>Description</strong>: Whether the element is accessible or not, when FALSE, the element is not rendered and the user submitted value is not taken into consideration.</p> <p><strong>Values</strong>: TRUE or FALSE.</p> <h3><a name="action" id="action"></a>#action</h3> <p><strong>Used by</strong>: <a href="#form">form</a></p> <p><strong>Description</strong>: The path to which the form will be submitted.</p> <p><strong>Values</strong>: An internal path</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/comment/comment.module/5">comment.module</a>): </p> <div class="codeblock"> <p><code><font color="#000000"><font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'#action'</font><font color="#007700">] = </font><font color="#0000bb">url</font><font color="#007700">(</font><font color="#dd0000">'comment/reply/'</font><font color="#007700">. </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'nid'</font><font color="#007700">]);<br /> </font><font color="#0000bb">?></font></font></code><code> </code></p> <p>Do not forget the # before property names.</p> </div> <h3><a name="after_build" id="after_build"></a>#after_build</h3> <p>An array of function names which will be called after the form is built. Example: node preview.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"> <p><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'files'</font><font color="#007700">][</font><font color="#dd0000">'file_directory_path'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000"> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'textfield'</font><font color="#007700">,<br /> </font><font color="#dd0000"><code><font color="#000000"><font color="#dd0000"> </font></font></code>'#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'File system path'</font><font color="#007700">),<br /> </font><font color="#dd0000"><code><font color="#000000"><font color="#dd0000"> </font></font></code>'#default_value' </font><font color="#007700">=> </font><font color="#0000bb">file_directory_path</font><font color="#007700">(),<br /> </font><font color="#dd0000"><code><font color="#000000"><font color="#dd0000"> </font></font></code>'#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">255</font><font color="#007700">,<br /> </font><font color="#dd0000"><code><font color="#000000"><font color="#dd0000"> </font></font></code>'#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'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.'</font><font color="#007700">),<br />); </font><br /> <font color="#0000bb">$form</font><font color="#007700">[</font><font color="#dd0000">'#after_build'</font><font color="#007700">] = array(<font color="#dd0000">'system_check_directory'</font>);</font><br /> </font></code></p> <p><code><font color="#000000"><font color="#007700">...<br /> <br /> function </font><font color="#0000bb">system_check_directory</font><font color="#007700">(</font><font color="#0000bb">$form_element</font><font color="#007700">) {<br /> </font><font color="#0000bb"> file_check_directory</font><font color="#007700">(</font><font color="#0000bb">$form_element</font><font color="#007700">[</font><font color="#dd0000">'#value'</font><font color="#007700">], </font><font color="#0000bb">FILE_CREATE_DIRECTORY</font><font color="#007700">, </font><font color="#0000bb">$form_element</font><font color="#007700">[</font><font color="#dd0000">'#parents'</font><font color="#007700">][</font><font color="#0000bb">0</font><font color="#007700">]);<br /> </font><font color="#0000bb"> </font><font color="#007700">return </font><font color="#0000bb">$form_element</font><font color="#007700">;<br /> }</font><font color="#007700"><br /> </font><font color="#0000bb">?></font></font></code></p> </div> <p>Property names without # signs causes havoc.</p> <h3><a name="attributes" id="attributes"></a>#attributes</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: Additional HTML attributes, such as 'class' can be set using this mechanism.</p> <p><strong>Values</strong>: Any HTML attribute not covered by other properties, e.g. <strong>class </strong>(for control types), <strong>enctype </strong>(for forms).</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/search/search.module/5">search.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'#attributes'</font><font color="#007700">] = array(</font><font color="#dd0000">'class' </font><font color="#007700">=> </font><font color="#dd0000">'search-form'</font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></div> <p>The # is mandatory before property names.</p> <h3><a name="autocomplete_path" id="autocomplete_path"></a>#autocomplete_path</h3> <p><strong>Used by</strong>: <a href="#textfield">textfield</a> </p> <p><strong>Description</strong>: The path the AJAX autocomplete script uses as the source for autocompletion.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/node/node.module/5">node.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'author'</font><font color="#007700">][</font><font color="#dd0000">'name'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'textfield'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Authored by'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#autocomplete_path' </font><font color="#007700">=> </font><font color="#dd0000">'user/autocomplete'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">name</font><font color="#007700">, </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> -</font><font color="#0000bb">1,<br /> </font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></div> <p>It's very important that you do not forget the # before property names.</p> <h3><a name="built" id="built"></a>#built</h3> <p><strong>Used by</strong>: <a href="#form">form</a></p> <p><strong>Description</strong>: Used to ascertain whether or not a form element has been built yet.</p> <p><strong>Values</strong>: TRUE or FALSE </p> <p><strong>Usage example</strong>: INTERNAL. See the <a href="http://api.drupal.org/api/function/_form_builder/5">_form_builder</a> function in <a href="http://api.drupal.org/api/file/includes/form.inc/5">form.inc</a>. </p> <p>The first character of property names is #.</p> <h3><a name="base" id="base"></a>#base</h3> <p>Define an alternate base name for the validate and submit function names. Will be used if the functions corresponding to the form id do not exist.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"> <code><font color="#000000"><font color="#0000BB"><?php<br /> </font> <font color="#0000BB">$form</font><font color="#007700">[</font><font color="#DD0000">'#base'</font><font color="#007700">] = </font><font color="#DD0000">'system_settings_form'</font><font color="#007700">;<br /> </font><font color="#0000BB">?></font></font></code></div> <h3><a name="button_type" id="button_type"></a>#button_type</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#submit">submit</a></p> <p><strong>Description</strong>: Indicates CSS class to use for button(<strong>form-<em>button_type</em></strong>)</p> <p class="help"><strong>Values</strong>: submit, ??? </p> <p><strong>Usage example</strong>: (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $type</font><font color="#007700">[</font><font color="#dd0000">'submit'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#input' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#name' </font><font color="#007700">=> </font><font color="#dd0000">'op'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#button_type' </font><font color="#007700">=> </font><font color="#dd0000">'submit'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#submit' </font><font color="#007700">=> </font><font color="#0000bb">TRUE,<br /> </font><font color="#007700">);<br /> </font><font color="#0000bb">?></font></font></code></div> <p>Developers should take care to not forget the first # character in property names.</p> <h3><a name="collapsed" id="collapsed"></a>#collapsed</h3> <p><strong>Used by</strong>: <a href="#fieldset">fieldset</a></p> <p><strong>Description</strong>: Indicates whether or not the fieldset is collapsed by default. See <a href="#collapsible">#collapsible</a> property.</p> <p><strong>Values</strong>: TRUE or FALSE </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/block/block.module/5">block.module</a>) :</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'block'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'fieldset'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Block configuration'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> </font><font color="#0000bb">3</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsible' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsed' </font><font color="#007700">=> </font><font color="#0000bb">FALSE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#tree' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <p>Child names do not have a # as first char, but property names do.</p> <h3><a name="collapsible" id="collapsible"></a>#collapsible</h3> <p><strong>Used by</strong>: <a href="#fieldset">fieldset</a></p> <p><strong>Description</strong>: Indicates whether or not the fieldset can be collapsed with JavaScript. See <a href="#collapsed">#collapsed</a> property.</p> <p><strong>Values</strong>: TRUE or FALSE </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/block/block.module/5">block.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'block'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'fieldset'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Block configuration'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> </font><font color="#0000bb">3</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsible' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#collapsed' </font><font color="#007700">=> </font><font color="#0000bb">FALSE</font><font color="#007700">, </font><font color="#dd0000"><br /> '#tree' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <p>One of the most important things about form API is not forgetting the # where it's appropriate.</p> <h3><a name="cols" id="cols"></a>#cols</h3> <p><strong>Used by</strong>: <a href="#textarea">textarea</a></p> <p><strong>Description</strong>: How many columns wide the textarea should be (see also <a href="#rows">#rows</a>) </p> <p><strong>Values</strong>: A positive number </p> <p><strong>Usage example </strong>(<a href="http://api.drupal.org/api/file/modules/aggregator/aggregator.module/5">aggregator.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textarea'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Description'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#cols' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#rows' </font><font color="#007700">=> </font><font color="#0000bb">5</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <p>The first # lets form API decide between a property name and a child.</p> <h3><a name="default_value" id="default_value"></a>#default_value</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#file">file</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: The value of the form element that will be displayed or selected initially if the form has not been submitted yet. <strong>Should NOT be confused with</strong> <strong><a href="#value">#value</a></strong>, which is a hard-coded value the user cannot change!</p> <p><strong>Values</strong>: Mixed</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/forum/forum.module/5">forum.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'body'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textarea'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Body'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">body</font><font color="#007700">, </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <p>How many different forms of warnings can I figure out to tell you that the first # in property names are important?</p> <h3><a name="delta" id="delta"></a>#delta</h3> <p><strong>Used by</strong>: <a href="#weight">weight</a></p> <p><strong>Description</strong>: Number of weights to have selectable. For example, with $delta => 10, the weight selection box would display numbers from -10 to 10. </p> <p><strong>Values</strong>: A positive number </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/menu/menu.module/5">menu.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'weight'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Weight'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#delta' </font><font color="#007700">=> </font><font color="#0000bb">10</font><font color="#007700">, </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <p>One of the most common errors for 4.7 is leaving out the # in the beginning of property names.</p> <h3><a name="description" id="description"></a>#description</h3> <p><strong>Used by</strong>: <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: The description of the form element. Make sure to enclose inside the <a href="http://api.drupal.org/api/function/t/5">t</a>() function so this property can be translated.</p> <p><strong>Values</strong>: Mixed</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/menu/menu.module/5">menu.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'weight'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Weight'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'weight'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#delta' </font><font color="#007700">=> </font><font color="#0000bb">10</font><font color="#007700">, </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Optional. In the menu, the heavier items will sink and the lighter items will be positioned nearer the top.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="disabled" id="disabled"></a>#disabled</h3> <p><strong>Used by</strong>: <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#file">file</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: Disables (greys out) a form input element.</p> <p><strong>Values</strong>: TRUE or FALSE</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"><code><font color="#000000"><font color="#0000BB"><?php<br /> </font><font color="#007700">if (isset(</font><font color="#0000BB">$disabled</font><font color="#007700">[</font><font color="#0000BB">$name</font><font color="#007700">])) {<br /> </font><font color="#0000BB">$form</font><font color="#007700">[</font><font color="#DD0000">'theme_settings'</font><font color="#007700">][</font><font color="#0000BB">$name</font><font color="#007700">][</font><font color="#DD0000">'#disabled'</font><font color="#007700">] = </font><font color="#0000BB">TRUE</font><font color="#007700">;<br /> }<br /></font><font color="#0000BB">?></font></font></code></div> <p>It can not be stressed enough that property names begin with a #.</p> <h3 class="help"><a name="error" id="error"></a>#error</h3> <p>INTERNAL. Indicates whether or not a form element has been flagged as having an error.</p> <h3 class="help"><a name="id" id="id"></a>#id</h3> <p>INTERNAL. Used to populate form elements' id property.</p> <h3 class="help"><a name="input" id="input"></a>#input</h3> <p>INTERNAL. Indicates whether or not input is possible for this form element.</p> <h3><a name="field_prefix" id="field_prefix"></a>#field_prefix</h3> <p><strong>Used by</strong>: <a href="#textfield">textfield</a></p> <p><strong>Description</strong>: Text or code that is placed directly in front of the textfield. This can be used to prefix a textfield with a constant string.</p> <p><strong>Values</strong>: Mixed</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"><code><span style="color: #000000"><span style="color: #0000BB"><?php<br />$form</span><span style="color: #007700">[</span><span style="color: #DD0000">'site_403'</span><span style="color: #007700">] = array(<br /> </span><span style="color: #DD0000">'#type' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'textfield'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#title' </span><span style="color: #007700">=> </span><span style="color: #0000BB">t</span><span style="color: #007700">(</span><span style="color: #DD0000">'Default 403 (access denied) page'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'#default_value' </span><span style="color: #007700">=> </span><span style="color: #0000BB">variable_get</span><span style="color: #007700">(</span><span style="color: #DD0000">'site_403'</span><span style="color: #007700">, </span><span style="color: #DD0000">''</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'#size' </span><span style="color: #007700">=> </span><span style="color: #0000BB">40</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#description' </span><span style="color: #007700">=> </span><span style="color: #0000BB">t</span><span style="color: #007700">(</span><span style="color: #DD0000">'This page is displayed when the requested document is denied to the current user. If unsure, specify nothing.'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'#field_prefix' </span><span style="color: #007700">=> </span><span style="color: #0000BB">url</span><span style="color: #007700">(</span><span style="color: #0000BB">NULL</span><span style="color: #007700">, </span><span style="color: #0000BB">NULL</span><span style="color: #007700">, </span><span style="color: #0000BB">NULL</span><span style="color: #007700">, </span><span style="color: #0000BB">TRUE</span><span style="color: #007700">) . (</span><span style="color: #0000BB">variable_get</span><span style="color: #007700">(</span><span style="color: #DD0000">'clean_url'</span><span style="color: #007700">, </span><span style="color: #0000BB">0</span><span style="color: #007700">) ? </span><span style="color: #DD0000">'' </span><span style="color: #007700">: </span><span style="color: #DD0000">'?q='</span><span style="color: #007700">)<br />);<br /></span><span style="color: #0000BB">?></span></span></code></div> <h3><a name="field_suffix" id="field_suffix"></a>#field_suffix</h3> <p><strong>Used by</strong>: <a href="#textfield">textfield</a></p> <p><strong>Description</strong>: Text or code that is placed directly after a textfield. This can be used to add a unit to a textfield.</p> <p><strong>Values</strong>: Mixed</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/upload/upload.module/5">system.module</a>):</p> <div class="codeblock"><code><span style="color: #000000"><span style="color: #0000BB"><?php<br />$form</span><span style="color: #007700">[</span><span style="color: #DD0000">'settings_general'</span><span style="color: #007700">][</span><span style="color: #DD0000">'upload_usersize_default'</span><span style="color: #007700">] = array(<br /> </span><span style="color: #DD0000">'#type' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'textfield'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#title' </span><span style="color: #007700">=> </span><span style="color: #0000BB">t</span><span style="color: #007700">(</span><span style="color: #DD0000">'Default total file size per user'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'#default_value' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$upload_usersize_default</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#size' </span><span style="color: #007700">=> </span><span style="color: #0000BB">5</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#maxlength' </span><span style="color: #007700">=> </span><span style="color: #0000BB">5</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'#description' </span><span style="color: #007700">=> </span><span style="color: #0000BB">t</span><span style="color: #007700">(</span><span style="color: #DD0000">'The default maximum size of all files a user can have on the site.'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'#field_suffix' </span><span style="color: #007700">=> </span><span style="color: #0000BB">t</span><span style="color: #007700">(</span><span style="color: #DD0000">'MB'</span><span style="color: #007700">)<br />);</span></span></code></div> <h3><a name="maxlength" id="maxlength"></a>#maxlength</h3> <p><strong>Used by</strong>: <a href="#textfield">textfield</a></p> <p><strong>Description</strong>: The maximum amount of characters to accept as input.</p> <p><strong>Values</strong>: A positive number.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/forum/forum.module/5">forum.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'title'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textfield'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Subject'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">title</font><font color="#007700">, </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">128</font><font color="#007700">, </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>You can spare lots of debug time by not forgetting the # in the beginning of property names.</p> </div> <h3><a name="method" id="method"></a>#method</h3> <p><strong>Used by</strong>: <a href="#form">form</a></p> <p><strong>Description</strong>: The HTTP method with which the form will be submitted.</p> <p><strong>Values</strong>: GET or POST. Default is POST. </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/node/node.module/5">node.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'#method'</font><font color="#007700">] = </font><font color="#dd0000">'post'</font><font color="#007700">;<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="multiple" id="multiple"></a>#multiple</h3> <p><strong>Used by</strong>: <a href="#select">select</a></p> <p><strong>Description</strong>: Indicates whether the user may select more than one item.</p> <p><strong>Values</strong>: TRUE or FALSE</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/taxonomy/taxonomy.module/5">taxonomy.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> </font><font color="#007700">return array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'select'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">$title</font><font color="#007700">, </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$value</font><font color="#007700">, </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> </font><font color="#0000bb">$options</font><font color="#007700">, </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">$description</font><font color="#007700">, </font><font color="#dd0000"><br /> '#multiple' </font><font color="#007700">=> </font><font color="#0000bb">$multiple</font><font color="#007700">, </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">$multiple </font><font color="#007700">? </font><font color="#0000bb">min</font><font color="#007700">(</font><font color="#0000bb">12</font><font color="#007700">, </font><font color="#0000bb">count</font><font color="#007700">(</font><font color="#0000bb">$options</font><font color="#007700">)) </font><font color="#dd0000"> </font><font color="#007700">: </font><font color="#0000bb">0</font><font color="#007700">,<br /> </font><font color="#dd0000">'#weight' </font><font color="#007700">=> -</font><font color="#0000bb">15</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>By now, you probably know that the first character of property names is # but I thought some repetition can't hurt.</p> </div> <h3 class="help"><a name="name" id="name"></a>#name</h3> <p>INTERNAL. Refers to the name of an element ('foo' in $form['foo']) </p> <h3><a name="options" id="options"></a>#options</h3> <p><strong>Used by</strong>: <a href="#checkboxes">checkboxes</a>, <a href="#radios">radios</a>, <a href="#select">select</a> </p> <p><strong>Description</strong>: Selectable options for a form element that allows multiple choices. </p> <p><strong>Values</strong>: An array in the form of <code>array(t('Display value 1'), t('Display value 2'))</code> or <code>array('return_value1' => t('Display Value 1'), 'return_value2' => t('Display Value 2'))</code> if specific return values are required. </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/comment/comment.module/5">comment.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'posting_settings'</font><font color="#007700">][</font><font color="#dd0000">'comment_preview'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'radios'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Preview comment'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">variable_get</font><font color="#007700">(</font><font color="#dd0000">'comment_preview'</font><font color="#007700">, </font><font color="#0000bb">1</font><font color="#007700">), </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> array(</font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Optional'</font><font color="#007700">), </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Required'</font><font color="#007700">)),<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>If you are fed up with comments about # being the first character of property names, then sorry, but it's important.</p> </div> <h3><a name="parents" id="parents"></a>#parents</h3> <p class="help"><strong>Used by</strong>: All</p> <p><strong>Description</strong>: Identifies parent form elements. See <a href="http://drupal.org/node/48643">#tree and #parents</a> in the handbook.</p> <p class="help"><strong>Values</strong>: An array of element names.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/comment/comment.module/5">comment.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'admin'</font><font color="#007700">][</font><font color="#dd0000">'status'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'radios'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#parents' </font><font color="#007700">=> array(</font><font color="#dd0000">'status'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Status'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$status</font><font color="#007700">, </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> array(</font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Published'</font><font color="#007700">), </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Not published'</font><font color="#007700">)), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> -</font><font color="#0000bb">1</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>While the first character of the words parents and property is P, the first character of every property is #.</p> </div> <h3><a name="prefix" id="prefix"></a>#prefix</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a> </p> <p><strong>Description</strong>: Text or markup to include before the form element. Also see <a href="#suffix">#suffix</a>.</p> <p><strong>Values</strong>: Mixed </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/poll/poll.module/5">poll.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'choice'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'fieldset'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Choices'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#prefix' </font><font color="#007700">=> </font><font color="#dd0000">'<div class="poll-form">'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#suffix' </font><font color="#007700">=> </font><font color="#dd0000">'</div>'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#tree' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>The correct prefix of a property name is the #.</p> </div> <h3 class="help"><a name="printed" id="printed"></a>#printed</h3> <p>INTERNAL. Used to determine whether or not a form element has been printed yet.</p> <h3>#process</h3> <p class="help">INTERNAL. Used to modify a form element.</p> <h3 class="help"><a name="processed" id="processed"></a>#processed</h3> <p>INTERNAL. Used to ascertain whether or not a form element has been processed (ie: expanded to multiple elements).</p> <h3><a name="redirect" id="redirect"></a>#redirect</h3> <p><strong>Used by</strong>: <a href="#form">form</a></p> <p><strong>Description</strong>: The default goto value after form is submitted. This value should be returned by a form's submit callback function, but altering another form's <a href="#redirect">#redirect</a> value by using <a href="http://api.drupal.org/api/function/hook_form_alter/5" class="local">hook_form_alter</a>() can be useful to change where that form redirects after it is submitted. Also see <a href="#action">#action</a>.</p> <p><strong>Values</strong>: An internal path or an array of arguments to pass to <a href="http://api.drupal.org/api/function/url/5" class="local">url</a>(). The value may also be set to <code>FALSE</code> to prevent redirection after form submission.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/includes/locale.inc/5">locale.inc</a>):</p> <div class="codeblock"> <p><code><font color="#000000"><font color="#0000BB"><?php<br /> $form</font><font color="#007700">[</font><font color="#DD0000">'#redirect'</font><font color="#007700">] = </font><font color="#DD0000">'node'</font><font color="#007700">;<br /> </font><font color="#0000BB">?></font></font></code></p> <p><code><font color="#000000"><font color="#0000BB"><?php<br /> $form</font><font color="#007700">[</font><font color="#DD0000">'#redirect'</font><font color="#007700">] = array(</font><font color="#DD0000">'user/login'</font><font color="#007700">, </font><font color="#DD0000">'destination=node'</font><font color="#007700">);<br /> </font><font color="#0000BB">?></font></font></code></p> <p><code><font color="#000000"><font color="#0000BB"><?php<br /> $form</font><font color="#007700">[</font><font color="#DD0000">'#redirect'</font><font color="#007700">] = </font><font color="#0000BB">FALSE</font><font color="#007700">;<br /> </font><font color="#0000BB">?></font></font></code></p> <p>Only heathens leave out the # before property names.</p> </div> <h3><a name="required" id="required"></a>#required</h3> <p><strong>Used by</strong>: <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#file">file</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: Indicates whether or not the element is required. This automatically validates for empty fields, and flags inputs as required. File fields are <strong>NOT</strong> allowed to be required.</p> <p><strong>Values</strong>: TRUE or FALSE </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/forum/forum.module/5">forum.module</a>): </p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'title'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textfield'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Subject'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">title</font><font color="#007700">, </font><font color="#dd0000"><br /> '#size' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#maxlength' </font><font color="#007700">=> </font><font color="#0000bb">128</font><font color="#007700">, </font><font color="#dd0000"><br /> '#required' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>You know what's absolutely required? The # in the beginning of property names.</p> </div> <h3><a name="return_value" id="return_value"></a>#return_value</h3> <p><strong>Used by</strong>: <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a> </p> <p><strong>Description</strong>: Value element should return when selected </p> <p><strong>Values</strong>: Mixed </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/poll/poll.module/5">poll.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'morechoices'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'checkbox'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Need more choices'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#return_value' </font><font color="#007700">=> </font><font color="#0000bb">1</font><font color="#007700">, </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">0</font><font color="#007700">, </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">"If the amount of boxes above isn't enough, check this box and click the Preview button below to add some more."</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>Let's make this remark short: #</p> </div> <h3><a name="rows" id="rows"></a>#rows</h3> <p><strong>Used by</strong>: <a href="#textarea">textarea</a></p> <p><strong>Description</strong>: How many rows high the textarea should be (see also <a href="#cols">#cols</a>) </p> <p><strong>Values</strong>: A positive number </p> <p><strong>Usage example </strong>(<a href="http://api.drupal.org/api/file/modules/aggregator/aggregator.module/5">aggregator.module</a>):</p> <div class="codeblock"><code><font color="#000000"><font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textarea'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Description'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#cols' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#rows' </font><font color="#007700">=> </font><font color="#0000bb">5</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>Your code will row with you if you forget the # in the beginning of property names.</p> </div> <h3><a name="submit_property" id="submit_property"></a>#submit</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#form">form</a>, <a href="#submit">submit</a> </p> <p><strong>Description</strong>: Indicates whether or not button should submit the form. When set for the form itself, indicates the submit handler for the form.</p> <p><strong>Values</strong>: TRUE or FALSE. For form, an array in the form <code>array('submit_function_1' => array('arg1a', 'arg1b',..), 'submit_function_2' => array('arg2a', 'arg2b'..))</code>. </p> <h3><a name="size" id="size"></a>#size</h3> <p><strong>Used by</strong>: <a href="#select">select</a>, <a href="#textfield">textfield</a> </p> <p><strong>Description</strong>: Width of the textfield (in characters) or size of multiselect box (in lines).</p> <p><strong>Values</strong>: A positive number. </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/comment/comment.module/5">comment.module</a>):</p> <div class="codeblock"><code><font color="#000000"><font color="#0000BB"><?php<br /> $form</font><font color="#007700">[</font><font color="#DD0000">'admin'</font><font color="#007700">][</font><font color="#DD0000">'homepage'</font><font color="#007700">] = array(<br /> </font><font color="#DD0000">'#type' </font><font color="#007700">=> </font><font color="#DD0000">'textfield'</font><font color="#007700">,<br /> </font><font color="#DD0000">'#title' </font><font color="#007700">=> </font><font color="#0000BB">t</font><font color="#007700">(</font><font color="#DD0000">'Homepage'</font><font color="#007700">),<br /> </font><font color="#DD0000">'#maxlength' </font><font color="#007700">=> </font><font color="#0000BB">255</font><font color="#007700">,<br /> </font><font color="#DD0000">'#size' </font><font color="#007700">=> </font><font color="#0000BB">30</font><font color="#007700">,<br /> </font><font color="#DD0000">'#default_value' </font><font color="#007700">=> </font><font color="#0000BB">$edit</font><font color="#007700">[</font><font color="#DD0000">'homepage'</font><font color="#007700">],<br /> );<br /></font><font color="#0000BB">?></font></font></code> <p>If you forget the # sign...</p> </div> <h3><a name="suffix" id="suffix"></a>#suffix</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a> </p> <p><strong>Description</strong>: Text or markup to include after the form element. Also see <a href="#prefix">#prefix</a>.</p> <p><strong>Values</strong>: Mixed </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/poll/poll.module/5">poll.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'choice'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'fieldset'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Choices'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#prefix' </font><font color="#007700">=> </font><font color="#dd0000">'<div class="poll-form">'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#suffix' </font><font color="#007700">=> </font><font color="#dd0000">'</div>'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#tree' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code> <p>Suffix is almost suffer which will happen if you forget the # in the beginning of property names.</p> </div> <h3><a name="theme" id="theme"></a>#theme</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a> </p> <p><strong>Description</strong>: Theme function to call for element. </p> <p><strong>Values</strong>: The name of a theme function, without the initial theme_.</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/upload/upload.module/5">upload.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'#theme'</font><font color="#007700">] = </font><font color="#dd0000">'upload_form_new'</font><font color="#007700">;<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="title" id="title"></a>#title</h3> <p><strong>Used by</strong>: <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#fieldset">fieldset</a>, <a href="#date">date</a>, <a href="#file">file</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a> </p> <p><strong>Description</strong>: The title of the form element. Make sure to enclose inside the <a href="http://api.drupal.org/api/function/t/5">t</a>() function so this property can be translated.</p> <p><strong>Values</strong>: Mixed </p> <p><strong>Usage example </strong>(<a href="http://api.drupal.org/api/file/modules/aggregator/aggregator.module/5">aggregator.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'textarea'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Description'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$edit</font><font color="#007700">[</font><font color="#dd0000">'description'</font><font color="#007700">], </font><font color="#dd0000"><br /> '#cols' </font><font color="#007700">=> </font><font color="#0000bb">60</font><font color="#007700">, </font><font color="#dd0000"><br /> '#rows' </font><font color="#007700">=> </font><font color="#0000bb">5</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="tree" id="tree"></a>#tree</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a> </p> <p> <strong>D</strong><strong>escription</strong>: 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 <a href="http://drupal.org/node/48643">#tree and #parents</a> in the handbook.</p> <p><strong>Values</strong>: TRUE or FALSE </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/system/system.module/5">system.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'status'</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'checkboxes'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$status</font><font color="#007700">, </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> </font><font color="#0000bb">$options</font><font color="#007700">, </font><font color="#dd0000"><br /> '#tree' </font><font color="#007700">=> </font><font color="#0000bb">TRUE</font><font color="#007700">,<br /> );<br /> </font><font color="#0000bb">$required </font><font color="#007700">= array(</font><font color="#dd0000">'block'</font><font color="#007700">, </font><font color="#dd0000">'filter'</font><font color="#007700">, </font><font color="#dd0000">'system'</font><font color="#007700">, </font><font color="#dd0000">'user'</font><font color="#007700">, </font><font color="#dd0000">'watchdog'</font><font color="#007700">);<br /> foreach (</font><font color="#0000bb">$required </font><font color="#007700">as </font><font color="#0000bb">$require</font><font color="#007700">) {<br /> </font><font color="#0000bb"> $form</font><font color="#007700">[</font><font color="#dd0000">'status'</font><font color="#007700">][</font><font color="#0000bb">$require</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'hidden'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#value' </font><font color="#007700">=> </font><font color="#0000bb">1</font><font color="#007700">, </font><font color="#dd0000"><br /> '#suffix' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'required'</font><font color="#007700">),<br /> );<br /> }<br /> </font><font color="#0000bb">?></font> </font> </code> </div> <h3><a name="type" id="type"></a>#type</h3> <p><strong>Used by</strong>: All</p> <p><strong>Description</strong>: Used to determine the type of form element. </p> <p><strong>Values</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#form">form</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#val">value</a>, <a href="#weight">weight</a> </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/locale/locale.module/5">locale.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'submit'</font><font color="#007700">] = array(</font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'submit'</font><font color="#007700">, </font><font color="#dd0000">'#value' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Import'</font><font color="#007700">));<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="validate" id="validate"></a>#validate</h3> <p class="help"><strong>Used by</strong>: ??? </p> <p><strong>Description</strong>: A list of custom validation functions that need to be passed. Function declarations are written as <strong><em>thing_to_test</em></strong>, and <strong>thing_to_test</strong> is passed into #validate, which will indicate that that function needs to be passed. </p> <p><strong>Values</strong>: Mixed </p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/filter/filter.module/source/5">filter.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'format'</font><font color="#007700">][</font><font color="#0000bb">$format</font><font color="#007700">-></font><font color="#0000bb">format</font><font color="#007700">] = array(</font><font color="#dd0000"><br /> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'filter_format'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">$format</font><font color="#007700">-></font><font color="#0000bb">name</font><font color="#007700">, </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> </font><font color="#0000bb">$value</font><font color="#007700">, </font><font color="#dd0000"><br /> '#return_value' </font><font color="#007700">=> </font><font color="#0000bb">$format</font><font color="#007700">-></font><font color="#0000bb">format</font><font color="#007700">, </font><font color="#dd0000"><br /> '#parents' </font><font color="#007700">=> array(</font><font color="#dd0000">'format'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#description' </font><font color="#007700">=> </font><font color="#0000bb">theme</font><font color="#007700">(</font><font color="#dd0000">'filter_tips'</font><font color="#007700">, </font><font color="#0000bb">_filter_tips</font><font color="#007700">(</font><font color="#0000bb">$format</font><font color="#007700">-></font><font color="#0000bb">format</font><font color="#007700">, </font><font color="#0000bb">false</font><font color="#007700">)), </font><font color="#dd0000"><br /> '#validate' </font><font color="#007700">=> array(</font><font color="#dd0000">'filter_form_validate' </font><font color="#007700">=> array()),</font><br /> );</font><font color="#007700"><br /> </font><font color="#0000bb">?></font></code> <p>While #validate makes sure that user data is valid, nothing validates the form for missing # in the beginning of property name.</p> </div> <h3 class="help"><a name="validation" id="validation"></a>#validation_arguments</h3> <p>INTERNAL</p> <h3><a name="value" id="value"></a>#value</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#hidden">hidden</a>, <a href="#markup">markup</a>, <a href="#submit">submit</a></p> <p><strong>Description</strong>: Used to set values that cannot be edited by the user. <strong>Should NOT be confused with <a href="#default_value">#default_value</a></strong>, which is for controls where users can override the pre-existing value. </p> <p><strong>Values</strong>: Mixed (text or numbers)</p> <p><strong>Usage example</strong> (<a href="http://api.drupal.org/api/file/modules/locale/locale.module/5">locale.module</a>):</p> <div class="codeblock"><code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'submit'</font><font color="#007700">] = array(</font><font color="#dd0000">'#type' </font><font color="#007700">=> </font><font color="#dd0000">'submit'</font><font color="#007700">, </font><font color="#dd0000">'#value' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Import'</font><font color="#007700">));<br /> </font><font color="#0000bb">?></font></font></code></div> <h3><a name="weightval" id="weightval"></a>#weight</h3> <p><strong>Used by</strong>: <a href="#button">button</a>, <a href="#checkbox">checkbox</a>, <a href="#checkboxes">checkboxes</a>, <a href="#date">date</a>, <a href="#fieldset">fieldset</a>, <a href="#file">file</a>, <a href="#markup">markup</a>, <a href="#password">password</a>, <a href="#radio">radio</a>, <a href="#radios">radios</a>, <a href="#select">select</a>, <a href="#submit">submit</a>, <a href="#textarea">textarea</a>, <a href="#textfield">textfield</a>, <a href="#weight">weight</a></p> <p><strong>Description</strong>: Used to sort the list of form elements before being output; lower numbers appear before higher numbers.</p> <p><strong>Values</strong>: A positive or negative number (integer or decimal) </p> <p><strong>Usage example </strong>(<a href="http://api.drupal.org/api/file/modules/book/book.module/5">book.module</a>):<code><font color="#000000"><font color="#0000bb"><br /> </font></font></code></p> <div class="codeblock"> <code><font color="#000000"> <font color="#0000bb"><?php<br /> $form</font><font color="#007700">[</font><font color="#dd0000">'parent'</font><font color="#007700">] = array(<br /> </font><font color="#dd0000"> '#type' </font><font color="#007700">=> </font><font color="#dd0000">'select'</font><font color="#007700">, </font><font color="#dd0000"><br /> '#title' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'Parent'</font><font color="#007700">), </font><font color="#dd0000"><br /> '#default_value' </font><font color="#007700">=> (</font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">parent </font><font color="#007700">? </font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">parent </font><font color="#007700">: </font><font color="#0000bb">arg</font><font color="#007700">(</font><font color="#0000bb">4</font><font color="#007700">)), </font><font color="#dd0000"><br /> '#options' </font><font color="#007700">=> </font><font color="#0000bb">book_toc</font><font color="#007700">(</font><font color="#0000bb">$node</font><font color="#007700">-></font><font color="#0000bb">nid</font><font color="#007700">), </font><font color="#dd0000"><br /> '#weight' </font><font color="#007700">=> -</font><font color="#0000bb">15</font><font color="#007700">,<br /> </font><font color="#dd0000">'#description' </font><font color="#007700">=> </font><font color="#0000bb">t</font><font color="#007700">(</font><font color="#dd0000">'The parent that this page belongs in. Note that pages whose parent is &lt;top-level&gt; are regarded as independent, top-level books.'</font><font color="#007700">),<br /> );<br /> </font><font color="#0000bb">?></font></font></code> </div> </body> </html>