Professional Documents
Culture Documents
org
Home
Search Drupal 6
forms_api_reference.html
Function, file, or topic: * Drupal 4.7 Drupal 5 Drupal 6 Drupal 7
Search
View documentation View source
● Drupal 6
Version 1.81.2.6 (checked in on 2009/03/07 at 16:39:07 by darthsteven)
● Constants
● Files 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
● Functions forms, please see the Forms API QuickStart guide.
● Globals
● Topics 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
#ahah 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 -
#collapsed - - - X - - - - - - - -
#collapsible - - - X - - - - - - - -
#cols - - - - - - - - - X - -
#default_value 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
#element_validate X 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 X X X X X X X X X X X X
#prefix X X X X X X X X X X X X
#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 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
#weight X X X X X X X X X X X X
Special Elements
#type button image_button submit form hidden markup item value
#after_build X X X X X X X -
#ahah X X X - - - - -
#action - - - X - - - -
#attributes X X X X X X - -
#button_type X X X - - - - -
#default_value - - - - X - - -
#description - - - - - - X -
#element_validate X X X - X X X X
#executes_submit_callback X X X - - - - -
#method - - - X - - - -
#parents X X X - X - - X
#prefix X X X X X X X -
#redirect - - - X - - - -
#required - - - - X - - -
#src - X - - - - - -
#submit X X X X - - - -
#suffix X X X X X X X -
#theme X X X X X X X -
#title - - - - - - X -
#tree X X X X X - - X
#validate X X X X - - - -
#value X X X - - X X X
#weight X X X - - X X -
Default Values
Every element automatically has these default values (see _element_info):
● #description = NULL
● #attributes = array()
● #required = FALSE
● #tree = FALSE
● #parents = array()
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'
❍ #executes_submit_callback = FALSE
❍ #ahah['event'] = 'click'
● checkbox
❍ #return_value = 1
❍ #ahah['event'] = 'change'
● checkboxes
❍ #tree = 1
● fieldset
❍ #collapsible = FALSE
❍ #collapsed = FALSE
● file
❍ #size = 60
● form
❍ #method = 'post'
❍ #action = request_uri()
● image_button
❍ #button_type = 'submit'
❍ #executes_submit_callback = TRUE
❍ #ahah['event'] = 'click'
● item
❍ #prefix = ''
❍ #suffix = ''
● markup
❍ #prefix = ''
❍ #suffix = ''
● radio
❍ #ahah['event'] = 'change'
● password
❍ #size = 30
❍ #maxlength = 64
❍ #ahah['event'] = 'blur'
● submit
❍ #name = 'op'
❍ #button_type = 'submit'
❍ #executes_submit_callback = TRUE
❍ #ahah['event'] = 'click'
● textarea
❍ #cols = 60
❍ #rows = 5
❍ #ahah['event'] = 'blur'
● textfield
❍ #size = 60
❍ #maxlength = 128
❍ #autocomplete_path = FALSE
❍ #ahah['event'] = 'blur'
● 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: #ahah, #attributes, #button_type (default: submit), #executes_submit_callback (default: FALSE), #name (default: op),
#prefix, #suffix, #type. #value, #weight
<?php
$form['preview'] = array(
'#type' => 'button',
'#value' => t('Preview'),
'#weight' => 19,
);
?>
checkbox
Properties: #ahah, #attributes, #default_value, #description, #prefix, #required, #return_value (default: 1), #suffix, #title, #type.
#weight
<?php
$form['copy'] = array(
'#type' => 'checkbox',
'#title' => t ('Send me a copy.'),
);
?>
checkboxes
Description: Format a set of checkboxes. #options is an associative array, where the key is the #return_value of the checkbox and the value
is displayed. The #options array can not have a 0 key, as it would not be possible to discern checked and unchecked states.
Properties: #attributes, #default_value, #description, #options, #prefix, #required, #suffix, #title, #tree (default: TRUE), #type.
#weight
<?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
<?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
Properties: #attributes, #collapsed (default: FALSE), #collapsible (default: FALSE), #description, #prefix, #suffix, #title, #type.
#weight
file
Note: you will need to include $form['#attributes'] = array('enctype' => "multipart/form-data"); in your form. See this handbook page for an
example http://drupal.org/node/111782.
Note: the #required property is not supported (setting it to true will always cause a validation error). Instead, you may want to use your own
validation function to do checks on the $_FILES array with #required set to false. You will also have to add your own required asterisk if you
would like one.
Properties: #attributes, #description, #prefix, #size (default: 60), #suffix, #title, #type. #weight
<?php
$form['new']['upload'] = array(
'#type' => 'file',
'#title' => t('Attach new file'),
'#size' => 40,
);
?>
form
Properties: #action (default: request_uri()), #attributes, #method (default: 'post'), #prefix, #submit, #suffix, #theme, #validate
Usage example:
N/A
hidden
<?php
$form['bid'] = array('#type' => 'hidden', '#value' => $bid);
?>
image_button
Properties: #ahah, #attributes, #button_type (default: 'submit'), #executes_submit_callback (default: TRUE), #name (default: 'op'),
#prefix, #src, #suffix, #submit, #type. #value, #weight
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
<?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
<?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: #ahah, #attributes, #description, #maxlength (default: 30), #prefix, #required, #size (default: 64), #suffix, #title,
#type. #weight
<?php
$form['pass'] = array(
'#type' => 'password',
'#title' => t('Password'),
'#maxlength' => 64,
'#size' => 15,
);
?>
radio
Properties: #ahah, #attributes, #default_value, #description, #prefix, #required, #suffix, #title, #type. #weight
Usage example:
N/A
radios
Properties: #attributes, #default_value, #description, #options, #prefix, #required, #suffix, #title, #type. #weight
<?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
Properties: #ahah, #attributes, #default_value, #description, #multiple, #options, #prefix, #required, #suffix, #title, #type.
#weight
<?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
Properties: #ahah, #attributes, #button_type (default: 'submit'), #executes_submit_callback (default: TRUE), #name (default: 'op'),
#prefix, #suffix, #type. #value, #weight
<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>
textarea
Properties: #ahah, #attributes, #cols (default: 60), #default_value, #description, #prefix, #required, #suffix, #title, #type. #rows
(default: 5), #weight
<?php
$form['body'] = array(
'#type' => 'textarea',
'#title' => t('Body'),
'#default_value' => $node->body,
'#required' => TRUE
);
?>
textfield
Properties: #ahah, #attributes, #autocomplete_path (default: FALSE), #default_value, #description, #field_prefix, #field_suffix,
#maxlength (default: 128), #prefix, #required, #size (default: 60), #suffix, #title, #type. #weight
<?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.
<?php
$form['vid'] = array('#type' => 'value', '#value' => $node->vid);
?>
weight
Properties: #attributes, #delta (default: 10), #default_value, #description, #prefix, #required, #suffix, #title, #type. #weight
<?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.
#action
<?php
$form['#action'] = url('comment/reply/'. $edit['nid']);
?>
#after_build
An array of function names which will be called after the form is built. Example: node preview.
<?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');
...
#ahah
Used by: button, checkbox, image button, password, radio, select, submit, textarea, textfield
An array of elements whose values control the behavior of the element with respect to the Drupal AHAH javascript methods.
The #ahah name refers to AHAH javascript replacement (Asychronous HTML and HTTP), a relative of AJAX. AHAH is a form of javascript
page replacement that is both easy and straight forward. In a nutshell an AHAH request follows these steps:
1. Drupal builds a form element with a set of #ahah properties. The misc/ahah.js file is included on the page automatically.
2. ahah.js finds all the form elements on the page that have an #ahah['path'] set and adds an event handler for the #ahah['event'] set
on that form element.
3. When the #ahah['event'] occurs on the element (such as 'click'), the AHAH request is made to the Drupal path of the element's #ahah
['path'].
4. Drupal generates HTML in a second request in the background. While the user waits for the callback to execute a throbber or progress bar
is shown as determined by #ahah['progress']. The result is returned to the original page containing the form element.
5. ahah.js gets the result and inserts the returned HTML into the #ahah['wrapper']. Depending on the #ahah['method'], the result may
affect the wrapper in different ways.
#ahah['effect']
Description: Specifies the effect used when adding the content from an AHAH request.
Values: String. Possible values: 'none' (default), 'fade', 'slide'. If the interface elements library is installed, any effect with the name
effectToggle may also be used.
$form['choice_wrapper']['poll_more'] = array(
'#type' => 'submit',
'#value' => t('More choices'),
'#description' => t("If the amount of boxes above isn't enough, click here to add more choices."),
'#weight' => 1,
'#submit' => array('poll_more_choices_submit'), // If no javascript action.
'#ahah' => array(
'path' => 'poll/js',
'wrapper' => 'poll-choices',
'method' => 'replace',
'effect' => 'fade',
),
#ahah['event']
Description: When this event occurs to this element, Drupal will perform an HTTP request in the background via Javascript.
Values: String. Possible values: 'click', 'blur', 'change'. Note that #ahah['event'] does not need to be explicitly specified. Although it can be
manually set, usually the default value will be sufficient.
#ahah['method']
Description: Modify the behavior of the returned HTML from an AHAH request when inserting into the #ahah_wrapper. If not set, the
returned HTML will replace the contents of the wrapper element, but it's also possible to use any of the available jQuery operations for DOM
manipulation.
Values: String. Possible values: 'replace' (default), 'after', 'append', 'before', 'prepend'.
#ahah['path']
Description: If set, this property triggers AHAH behaviors on a form element. This is the Drupal menu path to a callback function which will
generate HTML and return the string of HTML to Drupal. The result will be placed in the div specified in #ahah['wrapper'].
<?php
/**
* Implementation of hook_menu
hook_menu().
*/
function upload_menu() {
$items['upload/js'] = array(
'page callback' => 'upload_js',
'access arguments' => array('upload files'),
'type' => MENU_CALLBACK,
);
...
return $items;
}
...
function _upload_form($node) {
...
$form['new']['attach'] = array(
'#type' => 'submit',
'#value' => t('Attach'),
'#name' => 'attach',
'#ahah' => array(
'path' => 'upload/js',
'wrapper' => 'attach-wrapper',
'progress' => array('type' => 'bar', 'message' => t('Please wait...')),
),
'#submit' => array('node_form_submit_build_node'),
);
...
return $form;
?>
#ahah['path'] is set to 'upload/js', which has a menu item defined in the same module. Then the menu hook will call the 'upload_js' function which
generates HTML and returns it to original page.
#ahah['progress']
Description: Choose either a throbber or progress bar that is displayed while awaiting a response from the callback, and add an optional message.
Values: Array.
Possible values:
#ahah['wrapper']
Description: This property defines the HTML id attribute of an element on the page will server as the destination for HTML returned by an AHAH
request. Usually, a div element is used as the wrapper, as it provides the most flexibility for placement of elements before, after, or inside of it's
HTML tags. This property is required for using AHAH requests in on a form element.
Values: String containg a valid id attribute of an HTML element on the same page.
$form['new']['attach'] = array(
'#type' => 'submit',
'#value' => t('Attach'),
'#name' => 'attach',
'#ahah' => array(
'path' => 'upload/js',
'wrapper' => 'attach-wrapper',
'progress' => array('type' => 'bar', 'message' => t('Please wait...')),
),
'#submit' => array('node_form_submit_build_node'),
);
#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).
<?php
$form['#attributes'] = array('class' => 'search-form');
?>
#autocomplete_path
Description: The path the AJAX autocomplete script uses as the source for autocompletion.
<?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
Description: Used to ascertain whether or not a form element has been built yet.
#button_type
<?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
Description: Indicates whether or not the fieldset is collapsed by default. See #collapsible property.
<?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
Description: Indicates whether or not the fieldset can be collapsed with JavaScript. See #collapsed property.
<?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
Description: How many columns wide the textarea should be (see also #rows)
<?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
<?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
Description: Number of weights to have selectable. For example, with $delta => 10, the weight selection box would display numbers from -10 to 10.
<?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
<?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
<?php
if (isset($disabled[$name])) {
$form['theme_settings'][$name]['#disabled'] = TRUE;
}
?>
#element_validate
Description: A list of custom validation functions that need to be passed. The functions must use form_error() or form_set_error() to set an
error if the validation fails.
Values: an array of function names to be called to validate this element (and/or its children).
A validation function for an element takes the element and the form state as parameters, and has the form:
function myelement_validate($element, &$form_state) {
if (empty($element['#value']) {
form_error($element, t('This field is required.'));
}
}
<?php
if (count($formats) > 1) {
$form = array(
'#type' => 'fieldset',
'#title' => t('Input format'),
'#collapsible' => TRUE,
'#collapsed' => TRUE,
'#weight' => $weight,
'#element_validate' => array('filter_form_validate'),
);
...
?>
While #element_validate makes sure that user data is valid, nothing validates the form for missing # in the beginning of property name.
#error
INTERNAL. Indicates whether or not a form element has been flagged as having an error.
#executes_submit_callback
#id
#input
INTERNAL. Indicates whether or not input is possible for this form element.
#field_prefix
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
<?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
Description: Text or code that is placed directly after a textfield. This can be used to add a unit to a textfield.
Values: Mixed
<?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
You can spare lots of debug time by not forgetting the # in the beginning of property names.
#method
Description: The HTTP method with which the form will be submitted.
<?php
$form['#method'] = 'post';
?>
#multiple
Description: Indicates whether the user may select more than one item.
<?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
#options
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.
<?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
Description: Identifies parent form elements. See #tree and #parents in the handbook.
<?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
<?php
$form['choice'] = array(
'#type' => 'fieldset',
'#title' => t('Choices'),
'#prefix' => '<div class="poll-form">',
'#suffix' => '</div>',
'#tree' => TRUE,
);
?>
#printed
INTERNAL. Used to determine whether or not a form element has been printed yet.
#process
Description: An array of functions, each with an array of arguments, that are called when an element is processed. Using this callback, modules
can "register" further actions. For example the "radios" form type is expanded to multiple radio buttons using a processing function.
In this example, the function expand_radios with no arguments is called. This function adds new elements of type radio to the array with values
corresponding to the processed element's #options .
#processed
INTERNAL. Used to ascertain whether or not a form element has been processed (ie: expanded to multiple elements).
#redirect
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.
<?php
$form['#redirect'] = 'node';
?>
<?php
$form['#redirect'] = array('user/login', 'destination=node');
?>
<?php
$form['#redirect'] = FALSE;
?>
#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.
<?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
Values: Mixed
<?php
$form['morechoices'] = array(
'#type' => 'checkbox',
'#title' => t('Need more choices'),
'#return_value' => 1,
'#default_value' => 0,
'#description' => t("If the amount of boxes above isn't enough, check this box and click the Preview button below to add some more."),
);
?>
#rows
Description: How many rows high the textarea should be (see also #cols)
<?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.
#size
Description: Width of the textfield (in characters) or size of multiselect box (in lines).
<?php
$form['admin']['homepage'] = array(
'#type' => 'textfield',
'#title' => t('Homepage'),
'#maxlength' => 255,
'#size' => 30,
'#default_value' => $edit['homepage'],
);
?>
#src
Values: An URL.
#submit
Description: Contains a list of submit callbacks to be excuted on the form or only when a specific button is clicked.
<?php
function menu_form_alter(&$form, $form_state, $form_id) {
...
$form['menu']['parent'] = array(
'#type' => 'select',
'#title' => t('Parent item'),
'#default_value' => $default,
'#options' => $options,
'#attributes' => array('class' => 'menu-title-select'),
);
$form['#submit'][] = 'menu_node_form_submit';
}
?>
<?php
$form['menu_name'] = array('#type' => 'value', '#value' => $menu['menu_name']);
$form['#insert'] = FALSE;
$form['delete'] = array(
'#type' => 'submit',
'#value' => t('Delete'),
'#access' => !in_array($menu['menu_name'], menu_list_system_menus()),
'#submit' => array('menu_custom_delete_submit'),
'#weight' => 10,
);
?>
#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
<?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
<?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
<?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.
<?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
Values: button, checkbox, checkboxes, date, fieldset, file, form, hidden, markup, password, radio, radios, select, submit, textarea,
textfield, value, weight
<?php
$form['submit'] = array('#type' => 'submit', '#value' => t('Import'));
?>
#validate
Description: A list of custom validation functions that need to be passed.This is usually used to add additional vlidation functions to a form, or to
use an alternate function rather than the default form validation function which is the form ID with _validate appended to it.
Values: An array of function names. Each such function will take $form and $form_state as parameters and should use form_set_error() if the
form values do not pass validation. For example:
<?php
// Node types:
$types = array_map('check_plain', node_get_types('names'));
$form['advanced']['type'] = array(
'#type' => 'checkboxes',
'#title' => t('Only of the type(s)'),
'#prefix' => '<div class="criterion">',
'#suffix' => '</div>',
'#options' => $types,
);
$form['advanced']['submit'] = array(
'#type' => 'submit',
'#value' => t('Advanced search'),
'#prefix' => '<div class="action">',
'#suffix' => '</div>',
);
$form['#validate'][] = 'node_search_validate';
?>
#validation_arguments
INTERNAL
#value
Description: Used to set values that cannot be edited by the user. Should NOT be confused with #default_value, which is for form inputs where
users can override the default value.
<?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.
<?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.'),
);
?>
All source code and documentation on this site is released under the terms of the GNU General Public License, version 2 and later. Drupal is a registered
trademark of Dries Buytaert.