Home › API reference › Files

Version

1.49.2.20 (checked in on 2008/09/15 at 09:10:35 by leafishpaul)

Description

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 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):

 

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):

<?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

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: #attributes, #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 .' &lt;'. $user->mail .'&gt;',
);
?>

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.

Properties: #type, #value

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

Used by: button, submit

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 exam