Form API Reference

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

checkbox

Description

Format a checkbox.

Properties

#access, #after_build, #ajax, #allow_focus, #array_parents, #attached, #attributes (default: array()), #default_value, #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_checkbox', 'ajax_process_form')), #required (default: FALSE), #required_message, #return_value (default: 1), #states, #suffix, #theme (default: checkbox), #theme_wrappers (default: array('form_element')), #title, #title_display (default: after), #tree, #type, #weight, #value_callback, #wrapper_attributes

Usage Example

<?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 cannot have a 0 key, as it would not be possible to discern checked and unchecked states.

Note that you can provide #description text for each of the options individually, as illustrated in the second example for the radios form element, which also supports this ability.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #default_value, #description, #disabled, #element_validate, #id, #indentation, #input (default: TRUE), #options, #parents, #post_render, #prefix, #pre_render (default: array('form_pre_render_conditional_form_element')), #process (default: array('form_process_checkboxes')), #required (default: FALSE), #required_message, #states, #suffix, #theme, #theme_wrappers (default: array('container__checkboxes')), #title, #title_display (default: before), #tree (default: TRUE), #type, #weight

Usage Example

(form_example_states.inc):

<?php
  $form['high_school']['tests_taken'] = array(
    '#type' => 'checkboxes',
    '#options' => backdrop_map_assoc(array(t('SAT'), t('ACT'))),
    '#title' => t('What standardized tests did you take?'),
    ...
  ),
?>

color

Description

Elements of type color provide a user interface element that lets a user specify a color, either by using a visual color picker interface or by entering the color into a text field in "#rrggbb" hexadecimal format. Only simple colors (with no alpha channel) are allowed. The values are compatible with CSS.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #autocomplete_path (default: FALSE), #default_value, #description, #disabled, #element_validate (default: array('form_validate_color')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #placeholder, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #states, #suffix, #theme (default: color), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

(form_test.module):

<?php
  $form['color'] = array(
    '#type' => 'color',
    '#title' => 'Color',
  );
?>

container

Description

Returns HTML to wrap child elements in a container. Surrounds child elements with a <div> and adds attributes such as classes or an HTML id.

Properties

#access, #after_build, #attributes, #children, #id, #indentation, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_container')), #required, #states, #suffix, #theme, #theme_wrappers (default: array('container')), #title_display, #tree, #type, #weight

Usage Example

(field.form.inc):

<?php
  if ($elements) {
    // Also aid in theming of field widgets by rendering a classified
    // container.
    $addition[$field_name] = array(
      '#type' => 'container',
      '#attributes' => array(
        'class' => array(
          'field-type-' . backdrop_html_class($field['type']),
          'field-name-' . backdrop_html_class($field_name),
          'field-widget-' . backdrop_html_class($instance['widget']['type']),
        ),
      ),
      '#weight' => $instance['widget']['weight'],
    );
  }
?>

contextual_links

Description

A building block used in the creation of contextual links around other form elements.

Properties

#access, #after_build, #attached (default: array('library' => array( array( 'contextual', 'contextual-links', ), ))), #attributes (default: array('class' => array( 'contextual-links', ))), #id, #input, #links (default: array()), #post_render, #pre_render (default: array('contextual_pre_render_links')), #prefix, #process, #required (default: FALSE), #suffix, #theme (default: links__contextual), #theme_wrappers, #title_display (default: before), #weight

Usage Example

$build['#contextual_links']['node'] = array('node', array($node->nid));

date

Description

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

Properties

#access, #after_build, #attributes (default: array()), #default_value, #description, #disabled, #element_validate (default: array('date_validate')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_date')), #required (default: FALSE), #required_message, #states, #suffix, #theme (default: date), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

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

details

Description

Used for grouped form items. Can also be used as a theme wrapper for any renderable element, to surround it with a tag and add attributes such as classes or an HTML id.

Introduced in Backdrop 1.20.

The details form element replaces the fieldset element that Backdrop inherited from Drupal; although the latter element is still widely used in Backdrop, going forward, developers should use details for collapsible groupings of other form elements (in both forms and general render arrays).

Properties

#id, #attributes, #children, #details (default: NULL), #open (default: FALSE), #summary (default: NULL), #theme_wrappers (default: array('details')), #weight

Usage Example

(layout.admin.inc)

<?php
  $page['help'] = array(
    '#type' => 'details',
    '#summary' => t('How layouts work'),
    '#details' => $help,
    '#attributes' => array(
      'class' => array('description'),
    ),
  );
?>

dropbutton

Description

Format a drop-down menu containing a list of links to pages.

Note that any #attributes will be applied to the ul tag that contains the links, but there are additional div wrapper classes around that.

Properties

#links, #access, #after_build, #attributes, #disabled, #parents, #post_render, #prefix, #pre_render (default: array('backdrop_pre_render_dropbutton')), #process, #states, #suffix, #theme (default: links__dropbutton), #theme_wrappers, #tree, #type, #weight

Usage Example

(views_ui.admin.inc)

<?php
  $element['extra_actions'] = array(
    '#type' => 'dropbutton',
    '#links' => array(
      'edit-details' => array(
        'title' => t('Change view name/description'),
        'href' => "admin/structure/views/nojs/config-details/$view->name",
        'attributes' => array('class' => array('views-ajax-link')),
      ),
      'analyze' => array(
        'title' => t('analyze view'),
        'href' => "admin/structure/views/nojs/analyze/$view->name/$display_id",
        'attributes' => array('class' => array('views-ajax-link')),
      ),
      'clone' => array(
        'title' => t('clone view'),
        'href' => "admin/structure/views/view/$view->name/clone",
      ),
      'export' => array(),  // Placeholder for export
      'reorder' => array(
        'title' => t('reorder displays'),
        'href' => "admin/structure/views/nojs/reorder-displays/$view->name/$display_id",
        'attributes' => array('class' => array('views-ajax-link')),
      ),
    ),
  );
?>

email

Description

Collect an email address from the user.

Properties

#access, #after_build, #attributes (default: array()), #autocomplete_path (default: FALSE), #description, #element_validate (default: array('form_validate_email')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 254), #name, #pre_render, #post_render, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 60), #theme (default: email), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #weight, #wrapper_attributes

Usage Example

(contact.pages.inc)

<?php
  $form['mail'] = array(
    '#type' => 'email',
    '#title' => t('Your e-mail address'),
    '#default_value' => $user->uid ? $user->mail : '',
    '#required' => TRUE,
  );
?>

fieldset

Description

Represent a set of form controls optionally grouped under a common name.

Fieldsets were introduced in Drupal, and while still widely used in Backdrop, have now been superceded in many cases by the HTML 5 <details> tag, which is now supported by most browsers. Going forward, for collapsible form elements, developers should use the details Form API element.

Note, though, that vertical tabs use fieldsets for grouping. If this element is part of a vertical tab group, or may be made part of a vertical tab group (by setting its #group property), it should remain a fieldset element.

Properties

#access, #after_build, #attributes, #collapsed (default: FALSE), #collapsible (default: FALSE), #description, #element_validate, #group, #parents, #post_render, #prefix, #pre_render (default: array('form_pre_render_fieldset')), #process (default: array('form_process_fieldset', 'ajax_process_form')), #required, #states, #suffix, #theme, #theme_wrappers (default: array('fieldset')), #title, #title_display, #token_types, #tree, #type, #value (default: NULL), #weight

Usage Example

<?php
  $form['comment'] = array(
    '#type' => 'fieldset',
    '#title' => t('Comment settings'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#group' => 'additional_settings',
    '#attributes' => array(
      'class' => array('comment-node-type-settings-form'),
    ),
    '#attached' => array(
      'js' => array(backdrop_get_path('module', 'comment') . '/js/comment.admin.js'),
    ),
    '#weight' => 25,
  );
?>

field_ui_table

Description

Creates a table for the "Manage fields" form of a bundle and its display.

Properties

#access, #after_build, #attributes (default: array()), #id, #input, #name, #parent_options, #post_render, #prefix, #pre_render (default: array('field_ui_table_pre_render')), #process, #regions (default: array('' => array())), #required (default: FALSE), #required_message, #suffix, #theme (default: field_ui_table), #theme_wrappers, #title_display (default: before), #weight

Usage Example

(field_ui.admin.inc)

<?php
  $table = array(
    '#type' => 'field_ui_table',
    '#tree' => TRUE,
    '#header' => array(
      t('Label'),
      t('Weight'),
      t('Parent'),
      t('Machine name'),
      t('Field type'),
      t('Widget'),
      t('Operations'),
    ),
    '#parent_options' => array(),
    '#regions' => array(
      'main' => array('message' => t('No fields are present yet.')),
      'add_new' => array('title' => '&nbsp;'),
    ),
    '#attributes' => array(
      'class' => array('field-ui-overview'),
      'id' => 'field-overview',
    ),
  );
?>

file

Description

Format a file upload field.

Note: Backdrop will add the code enctype="multipart/form-data", required by browsers to handle files, so it's not necessary to include it yourself.

Properties

#access, #after_build, #array_parents, #attached, #attributes (default: array()), #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process, #required (default: FALSE), #required_message, #size (default: 60), #states, #suffix, #theme (default: file), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

(file.module):

<?php
  $element['upload'] = array(
    '#name' => 'files[' . implode('_', $element['#parents']) . ']',
    '#type' => 'file',
    '#title' => t('Choose a file'),
    '#title_display' => 'invisible',
    '#size' => 22,
    '#theme_wrappers' => array(),
    '#weight' => -10,
  );
?>

form

Description

A form containing form elements.

Properties

#access, #action (default: request_uri()), #after_build, #attached, #attributes (default: array()), #config, #https, #id, #input, #method (default: post), #post_render, #prefix, #pre_render, #process, #required (default: FALSE), #states, #submit, #suffix, #theme, #theme_wrappers (default: array('form')), #title_display (default: before), #tree, #type, #validate, #weight, #redirect

head_tag

Description

A render element to specify tags that are displayed in the <head> of the HTML page.

Note that although this render element can be used to create a general-purpose tag, the usage of head_tag outside of the <head> is unsupported and will likely break in future versions of Backdrop.

Properties

#access, #after_build, #attributes (default: array()), #id, #input, #post_render, #pre_render (default: array('backdrop_pre_render_conditional_comments')), #process, #required (default: FALSE), #tag, #theme (default: head_tag), #title_display (default: before), #theme_wrappers, #token_types, #type, #value (default: NULL), #weight

Usage Example

<?php
function _backdrop_default_html_head() {
  // Add default elements. Make sure the Content-Type comes first because the
  // IE browser may be vulnerable to XSS via encoding attacks from any content
  // that comes before this META tag, such as a TITLE tag.
  $elements['system_meta_content_type'] = array(
    '#type' => 'head_tag',
    '#tag' => 'meta',
    '#attributes' => array(
      'charset' => 'utf-8',
    ),
    // Security: This always has to be output first.
    '#weight' => -1000,
  );
  // Show Backdrop and the major version number in the META GENERATOR tag.
  // Get the major version.
  list($version, ) = explode('.', BACKDROP_VERSION);
  $elements['system_meta_generator'] = array(
    '#type' => 'head_tag',
    '#tag' => 'meta',
    '#attributes' => array(
      'name' => 'Generator',
      'content' => 'Backdrop CMS ' . $version . ' (https://backdropcms.org)',
    ),
  );
  // Also send the generator in the HTTP header.
  $elements['system_meta_generator']['#attached']['backdrop_add_http_header'][] = array('X-Generator', $elements['system_meta_generator']['#attributes']['content']);
  return $elements;
}
?>

help

Description

Add some help text to the page (the element will have a help class and may be styled differently to other text).

Typically a bare #markup element has no margins above or below, and it was not uncommon in the past to wrap such text in <p> tags using the #prefix and #suffix properties. If the text is playing the role of help or explanatory text, you should use the help element instead. For example, use this:

<?php
$form['foo'] = array(
  '#type' => 'help',
  '#markup' => t('This field does something.'),
);
?>

rather than this:

<?php
$form['foo'] = array(
  '#markup' => t('This field does something.'),
  '#prefix' => '<p>',
  '#suffix' => '</p>',
);
?>

Though this element is commonly used in forms, it can also be used outside of forms as a renderable element.

Properties

#access, #markup (default: ''), #prefix, #pre_render (default: array('backdrop_pre_render_markup')), #suffix, #theme (default: help), #theme_wrappers, #type, #weight

Usage Example

(redirect.module):

<?php
  $form['help'] = array(
    '#type' => 'help',
    '#markup' => t('This page lists all paths that have resulted in 404 errors and do not yet have any redirects assigned to them.'),
  );
?>

hidden

Description

Store data in a hidden form field.

Properties

#access, #after_build, #default_value, #element_validate, #parents, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form')), #states, #suffix, #theme (default: hidden), #theme_wrappers, #token_types, #tree, #type, #value, #weight

Usage Example

(block.module):

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

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

Rendered output:

<input type="hidden" id="custId" name="custId" value="3487">

html_date

Description

Format a date element.

Properties

#access, #after_build, #ajax, #array_parents, #attached, #attributes (default: array()), #default_value, #description, #disabled, #element_validate (default: array('html_date_validate')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process, #required (default: FALSE), #required_message, #states, #suffix, #theme (default: html_date), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #value_callback, #weight, #wrapper_attributes

Usage Example

<?php
  $form['h5date'] = array(
    '#type' => 'html_date',
    '#title' => 'Date',
    '#description' => 'A date.',
  );
?>

Rendered output:

  <label for="edit-h5date">Date </label>
  <input id="edit-h5date" class="form-date" type="date" value="" name="h5date">
  <div class="description">A date.</div>

html_datetime

Description

Format both a date element and a time element together. Uses the browser to render the date and time pickers.

Properties

#access, #after_build, #ajax, #array_parents, #attached, #attributes (default: array()), #default_value, #description, #disabled, #element_validate (default: array('html_datetime_validate')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_html_datetime')), #required (default: FALSE), #required_message, #states, #suffix, #theme (default: html_datetime), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #value_callback, #weight, #wrapper_attributes

Usage Example

<?php
  $form['author']['date'] = array(
    '#type' => 'html_datetime',
    '#title' => t('Authored on'),
    '#default_value' => array(
      'date' => format_date($node->created, 'custom', DATE_FORMAT_DATE),
      'time' => format_date($node->created, 'custom', DATE_FORMAT_TIME),
    ),
    '#attributes' => array(
      'date' => array(
        'min' => '1970-01-01',
        'max' => '2037-12-31',
        'placeholder' => t('e.g. @date', array(
          '@date' => format_date(REQUEST_TIME, 'custom', DATE_FORMAT_DATE)
        )),
      ),
      'time' => array(
        'placeholder' => t('e.g. @date', array(
          '@date' => format_date(REQUEST_TIME, 'custom', DATE_FORMAT_TIME)
        )),
      ),
    ),
    '#description' => t('Leave blank to use the current time.'),
  );
?>

Rendered Output:

  <label for="edit-date">Authored on </label>
  <div id="edit-date" class="container-inline">
    <div class="form-item form-type-html-date form-item-date-date">
      <input min="1970-01-01" max="2037-12-31" placeholder="e.g. 2024-11-01" id="edit-date-date" class="form-date" type="date" value="2020-09-10" name="date[date]">
    </div>
    <div class="form-item form-type-html-time form-item-date-time">
      <input placeholder="e.g. 12:43:37" id="edit-date-time" class="form-time" type="time" value="19:00:00" name="date[time]" step="1">
    </div>
  </div>
  <div class="description">Leave blank to use the current time.</div>

html_time

Description

Format a time element. Uses the browser to render the time picker.

Properties

#access, #after_build, #ajax, #array_parents, #attached, #attributes (default: array()), #default_value, #description, #disabled, #element_validate (default: array('html_time_validate')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process, #required (default: FALSE), #required_message, #states, #suffix, #theme (default: html_time), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #value_callback, #weight, #wrapper_attributes

Usage Example

'html_time',
'#title' => 'Time',
'#description' => 'A time.',
);
?>

Rendered output:

  <label for="edit-h5time">Time </label>
  <input id="edit-h5time" class="form-time" type="time" value="" name="h5time" step="1">
  <div class="description">A time.</div>

image_button

Description

Format a form submit button with an image.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #button_type (default: submit), #disabled, #element_validate, #executes_submit_callback (default: TRUE), #has_garbage_value (default: TRUE), #id, #indentation, #input (default: TRUE), #limit_validation_errors (default: FALSE), #parents, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form', 'form_process_button')), #required (default: FALSE), #required_message, #return_value (default: TRUE), #src (default: NULL), #states, #submit, #suffix, #theme, #theme_wrappers (default: array('image_button')), #title_display (default: before), #token_types, #tree, #type, #validate, #value, #weight

item

Description

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

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

Fields of type item do not support the #attributes property; use #wrapper_attributes instead.

Properties

#access, #after_build, #description, #element_validate, #field_prefix, #field_suffix, #id, #markup (default: ''), #name, #parents, #post_render, #prefix, #pre_render (default: array('backdrop_pre_render_markup')), #process, #required (default: FALSE), #states, #suffix, #theme, #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

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

link

Description

A link with a title and target path.

There are two ways to add attributes (like classes) to the link. You can pass them directly as a '#attribute' property:

<?php
  $form['link_1'] = array(
    '#type' => 'link',
    '#title' => t('Link 1'),
    '#href' => 'mypath',
    '#attributes' => array('class' => 'attribute-class'),
  );
?>

Or you can pass them within the '#options' property (note, though, that the key within the '#options' property is 'attributes', not '#attributes').

<?php
  $form['link_2'] = array(
    '#type' => 'link',
    '#title' => t('Link 2'),
    '#href' => 'mypath',
    '#options' => array(
      'attributes' => array('class' => 'option-class'),
    ),
  );
?>

You should not use both in the same link element. If you do, the '#options' attributes will be used and the '#attributes' property ignored.

Properties

#access, #after_build, #ajax, #attributes, #href, #id, #options, #parents, #post_render, #prefix, #pre_render (default: array('backdrop_pre_render_link', 'backdrop_pre_render_markup')), #process, #states, #suffix, #theme, #theme_wrappers, #title, #tree, #type, #token_types, #value, #weight

Usage Example

(block.admin.inc)

<?php
  $form['actions']['cancel'] = array(
    '#type' => 'link',
    '#title' => t('Cancel'),
    '#href' => $options['path'],
    '#options' => $options,
    '#weight' => 1,
  );
?>

link_field

Description

Stores a title, href, and attributes in the database to assemble a link.

Properties

#access, #after_build, #attributes (default: array()), #description, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #pre_render, #post_render, #process (default: array('link_field_process')), #required (default: FALSE), #required_message, #theme (default: link_field), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #weight, #wrapper_attributes

machine_name

Description

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

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

The element validation checks that the submitted value:

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

Non-standard form element properties:

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

Properties

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

Usage Example

(taxonomy.admin.inc):

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

(menu.admin.inc):

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

managed_file

Description

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

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

The #managed_file element is expanded into a set of FAPI elements, including a '#submit' button (for removing the uploaded file), a '#file' element and a handful of '#hidden' and '#markup' elements to handle progress indication and displaying of already uploaded files.

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

<?php
  // Load the file via file.fid.
  $file = file_load($form_state['values']['my_file_field']);
  // Change status to permanent.
  $file->status = FILE_STATUS_PERMANENT;
  // Save.
  file_save($file);
  // Record that the module (in this example, user module) is using the file.
  file_usage_add($file, 'user', 'user', $account->uid);
?>

(Without the call to file_usage_add, file_managed_file_validate produces an error upon saving the form, saying that the uploaded file may not be referenced.)

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

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

Non-standard form element properties:

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

Properties

#access, #after_build, #array_parents, #attached (default: array('css' => array( 'core/modules/file/css/file.admin.css', ), 'js' => array( 'core/modules/file/js/file.js', ))), #attributes (default: array()), #browser_view (default: FALSE), #description, #disabled, #element_validate (default: array('file_managed_file_validate')), #extended (default: FALSE), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render (default: array('file_managed_file_pre_render')), #process (default: array('file_managed_file_process')), #progress_indicator (default: throbber), #progress_message (default: NULL), #required (default: FALSE), #required_message, #size (default: 22), #states, #suffix, #theme (default: file_managed_file), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #upload_location (default: NULL), #upload_validators (default: array()), #value_callback (default: file_managed_file_value), #weight, #wrapper_attributes

Usage Example

(image_example.pages.inc.):

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

markup

Description

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

Note: if you use markup, if the content will not be wrapped in tags (generally <p> and <div>), will fall outside of collapsed fieldsets. Please add wrapping tags if needed.

Properties

#access, #after_build, #element_validate, #markup (default: ''), #parents, #post_render, #prefix, #pre_render (default: array('backdrop_pre_render_markup')), #process, #suffix, #theme, #theme_wrappers, #tree, #type, #weight

Usage Example

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

number

Description

Format a number (integer or decimal).

Note that the #size property is ignored by most browsers for the native number input, but is (currently) supported on Firefox.

Properties

#access, #after_build, #attributes (default: array()), #description, #element_validate (default: array('form_validate_number')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #min, #max, #name, #placeholder, #pre_render, #post_render, #prefix, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size, #states, #step (default: 1), #suffix, #theme (default: number), #theme_wrappers (default: array('form_element')), #title, #token_types, #title_display (default: before), #value, #weight, #wrapper_attributes

Usage Example

<?php
  $form['comment']['comment_per_page'] = array(
    '#type' => 'number',
    '#title' => t('Comments per page'),
    '#default_value' => $node_type->settings['comment_per_page'],
    '#required' => TRUE,
    '#min' => 10,
    '#max' => 1000,
    '#step' => 10,
  );
?>

Rendered output:

  <label for="edit-comment-per-page">Comments per page <abbr class="form-required" title="This field is required.">*</abbr></label>
  <input type="number" id="edit-comment-per-page" name="comment_per_page" value="600" step="10" min="10" max="1000" class="form-number required">

operations

Description

Format a drop-down menu containing a list of links to pages that are typically administrative actions.

Note that any #attributes will be applied to the ul tag that contains the links, but there are additional div wrapper classes around that.

The operations element is nearly the same as the dropbutton element, but has its own #theme property so that themers can, if they wish, distinguish between administrative action dropbuttons ('#type' => 'operations') and general-purpose dropbuttons ('#type' => 'dropbutton').

Properties

Usage Example

(node.types.inc)

<?php
  $row[] = array(
    'data' => array(
      '#type' => 'operations',
      '#links' => $links,
    ),
  );
?>

options

Description

The 'options' form element type is useful when collecting a series of values in a list. The values within the list may optionally have unique keys, such as that in an array structure. In addition, a default choice (or several default choices) may be selected by the user.

Properties

#access, #after_build, #attached (default: array('library' => array( array( 'options', 'options', ), ))), #attributes (default: array()), #default_value_allowed (default: TRUE), #default_value_pattern (default: ''), #description, #element_validate (default: array('form_options_validate')), #field_prefix, #field_suffix, #key_type (default: mixed), #key_type_toggle (default: NULL), #key_type_toggled (default: FALSE), #id, #indentation, #input (default: TRUE), #limit (default: NULL), #multiple (default: FALSE), #name, #optgroups (default: TRUE), #options (default: array()), #options_readonly (default: FALSE), #pre_render, #post_render, #process (default: array('form_options_expand')), #required (default: FALSE), #required_message, #theme_wrappers (default: array('form_element')), #theme, #title, #title_display (default: before), #weight, #wrapper_attributes

Usage Example

(list.module)

<?php
  $form['allowed_values'] = array(
    '#type' => 'options',
    '#title' => t('Allowed values list'),
    '#description' => '',
    '#default_value' => '',
    '#default_value_allowed' => FALSE,
    '#options' => $options,
    '#element_validate' => array('list_allowed_values_setting_validate'),
    '#field_has_data' => $has_data,
    '#field' => $field,
    '#field_type' => $field['type'],
    '#key_type' => 'mixed', // Optimal for now.
    '#key_type_toggle' => t('Custom keys'),
    '#key_type_toggled' => $key_type_toggled,
    '#access' => empty($settings['allowed_values_function']),
    '#multiple' => !($field['cardinality'] == 1),
  );
?>

password

Description

Format a single-line password field that does not display its contents visibly.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 128), #name, #parents, #password_shown (default: FALSE), #password_strength (default: FALSE), #password_toggle (default: FALSE), #placeholder, #post_render, #prefix, #pre_render, #process (default: array('user_form_process_password')), #required (default: FALSE), #required_message, #size (default: 60), #states, #suffix, #theme (default: password), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

(user.module):

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

Rendered output:

  <label for="edit-pass">Password <abbr class="form-required" title="This field is required.">*</abbr></label>
  <input type="password" spellcheck="false" id="edit-pass" name="pass" size="60" maxlength="128" class="form-text required">

password_confirm

Description

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

Properties

#access, #after_build, #attributes (default: array()), #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_password_confirm', 'user_form_process_password_confirm')), #required (default: FALSE), #required_message, #size (default: 60), #states, #suffix, #theme, #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

(user.module):

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

radio

Description

Format a radio button.

Note: It is not necessary to add each radio individually. See Radios for how to add a complete set.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #default_value (default: NULL), #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #parents, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #return_value, #states, #suffix, #theme (default: radio), #theme_wrappers (default: array('form_element')), #title, #title_display (default: after), #tree, #type, #weight, #wrapper_attributes

Usage Example

<?php
  $form['profile'][$name] = array(
    '#type' => 'radio',
    '#value' => 'standard',
    '#return_value' => $profile,
    '#title' => st($name),
    '#description' => isset($profiles[$profile]['description']) ? st($profiles[$profile]['description']) : '',
    '#parents' => array('profile'),
  );
?>

radios

Description

Format a set of radio buttons.

Note that you can provide #description text for each of the options individually, as illustrated in the second example, as well as other properties of individual radio form elements, such as #indentation.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #default_value, #description, #disabled, #element_validate, #id, #indentation, #input (default: TRUE), #options, #parents, #post_render, #prefix, #pre_render (default: array('form_pre_render_conditional_form_element')), #process (default: array('form_process_radios')), #required (default: FALSE), #required_message, #states, #suffix, #theme, #theme_wrappers (default: array('container__radios')), #title, #title_display (default: before), #tree, #type, #weight

Usage Example

(link.module):

<?php
  $form['title'] = array(
    '#type' => 'radios',
    '#title' => t('Link Title'),
    '#default_value' => $instance['settings']['title'],
    '#options' => array(
      'optional' => t('Optional Title'),
      'required' => t('Required Title'),
    ),
    '#description' => t('If the link title is optional or required, a field will be displayed to the end user. If the link title is static, the link will always use the same title.'),
  );
?>

Rendered output:

  <label for="edit-instance-settings-title">Link Title </label>
  <div class="form-radios" id="edit-instance-settings-title">
    <div class="form-item form-type-radio form-item-instance-settings-title">
      <input type="radio" id="edit-instance-settings-title-optional" name="instance[settings][title]" value="optional" checked="checked" class="form-radio">  
      <label class="option" for="edit-instance-settings-title-optional">Optional Title </label>
    </div>
    <div class="form-item form-type-radio form-item-instance-settings-title">
      <input type="radio" id="edit-instance-settings-title-required" name="instance[settings][title]" value="required" class="form-radio">  
      <label class="option" for="edit-instance-settings-title-required">Required Title </label>
    </div>
  </div>
  <div class="description">If the link title is optional or required, a field will be displayed to the end user. If the link title is static, the link will always use the same title.</div>

(node.pages.inc)

<?php
  $form['options']['status'] = array(
    '#type' => 'radios',
    '#title' => $node->nid ? t('Published state') : t('Publish action'),
    '#options' => array(
      NODE_PUBLISHED => $node->nid ? t('Published') : t('Publish now'),
      NODE_NOT_PUBLISHED => $node->nid ? t('Draft') : t('Save as draft'),
    ),
    '#default_value' => $status,
  );
  $form['options']['status'][NODE_PUBLISHED]['#description'] = t('Site visitors will be able to access this content.');
  $form['options']['status'][NODE_NOT_PUBLISHED]['#description'] = t('Only the content creator or site administrators will be able to access this content.');
?>

Rendered output:

  <label for="edit-status">Published state </label>
  <div class="form-radios" id="edit-status">
    <div class="form-item form-type-radio form-item-status">
      <input type="radio" id="edit-status-1" name="status" value="1" checked="checked" class="form-radio">  
      <label class="option" for="edit-status-1">Published</label>
      <div class="description">Site visitors will be able to access this content.</div>
   </div>
   <div class="form-item form-type-radio form-item-status">
     <input type="radio" id="edit-status-0" name="status" value="0" class="form-radio">  
     <label class="option" for="edit-status-0">Draft </label>
     <div class="description">Only the content creator or site administrators will be able to access this content.</div>
  </div>

range

Description

Form element that allows the user to enter a range of numbers, i.e., a minimum and maximum value.

Properties

#access, #after_build, #attributes (default: array()), #children, #description, #element_validate (default: array('form_validate_number')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #max (default: 100), #maxlength (default: 128), #min, #name, #pre_render, #post_render, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 30), #step (default: 1), #theme (default: range), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #weight, #wrapper_attributes

scripts

Description

An element that when rendered, creates the HTML to add a list of Javascript scripts to a page.

This takes the #items property as a structured array of queued cascading scripts in the form returned by backdrop_add_js().

Properties

#access, #after_build, #aggregate_callback (default: backdrop_aggregate_js), #attributes (default: array()), #group_callback (default: backdrop_group_js), #id, #input, #items (default: array()), #post_render, #pre_render (default: array('backdrop_pre_render_scripts')), #process, #required (default: FALSE), #theme, #theme_wrappers, #title_display (default: before), #weight

Usage Example

<?php
function backdrop_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALSE) {
  if (!isset($javascript)) {
    $javascript = backdrop_add_js();
  }
  if (empty($javascript)) {
    return '';
  }
  ...

  // Render the HTML needed to load the JavaScript.
  $elements = array(
    '#type' => 'scripts',
    '#items' => $items,
  );

  return backdrop_render($elements);
}
?>

search

Description

Input element for search functionality.

Properties

#access, #after_build, #attributes (default: array()), #autocomplete_path (default: FALSE), #description, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 128), #name, #placeholder, #pre_render, #post_render, #prefix, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 60), #suffix, #states, #theme (default: search), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #weight, #wrapper_attributes

Usage Example

(admin_bar.inc)

<?php
  $search['search']['search'] = array(
    '#type' => 'search',
    '#title' => t('Admin search'),
    '#title_display' => 'invisible',
    '#attributes' => array(
      'placeholder' => t('Menu search'),
      'autocomplete' => 'off',
      'autocorrect' => 'off',
      'autocapitalize' => 'off',
    ),
    '#id' => 'admin-bar-search-items',
  );
?>

select

Description

Format a drop-down select for a single value, or scrolling selection box for multiple values. See #empty_option and #empty_value for an explanation of various settings for a select element, including behavior if #required is TRUE or FALSE.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #default_value, #description, #disabled, #element_validate, #empty_option, #empty_value, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #multiple (default: FALSE), #name, #options, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_select', 'ajax_process_form')), #required (default: FALSE), #required_message, #size, #states, #suffix, #theme (default: select), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

(contact.admin.inc):

<?php
  $form['selected'] = array(
    '#type' => 'select',
    '#title' => t('Selected'),
    '#options' => array(
      0 => t('No'),
      1 => t('Yes'),
    ),
    '#default_value' => $category['selected'],
    '#description' => t('Set this to <em>Yes</em> if you would like this category to be selected by default.'),
  );
?>

styles

Description

An element that when rendered, creates the HTML to add a list of stylesheets to a page.

This takes the #items property as a structured array of queued cascading stylesheets in the form returned by backdrop_add_css().

Properties

#access, #attributes (default: array()), #after_build, #aggregate_callback (default: backdrop_aggregate_css), #group_callback (default: backdrop_group_css), #id, #input, #items (default: array()), #post_render, #pre_render (default: array('backdrop_pre_render_styles')), #process, #required (default: FALSE), #theme, #theme_wrappers, #title_display (default: before), #weight

Usage Example

<?php
function backdrop_get_css($css = NULL, $skip_alter = FALSE) {
  if (!isset($css)) {
    $css = backdrop_add_css();
  }
  ...

  // Render the HTML needed to load the CSS.
  $styles = array(
    '#type' => 'styles',
    '#items' => $css,
  );
  ...

  return backdrop_render($styles);
}
?>

submit

Description

Format a form submit button.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #button_type (default: submit), #disabled, #element_validate, #executes_submit_callback (default: TRUE), #id, #indentation, #input (default: TRUE), #limit_validation_errors (default: FALSE), #name (default: op), #parents, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form', 'form_process_button')), #required (default: FALSE), #states, #submit, #suffix, #theme, #theme_wrappers (default: array('button')), #title_display (default: before), #token_types, #tree, #type, #validate, #value, #weight

Usage Example

(locale.module):

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

tableselect

Description

A table created with a far left column of radios or checkboxes.

Build the table headings and columns with the #headers property, and the rows with the #options property. See Adding checkboxes to a table for a full explanation.

Other settings:

To set accessibility tags for the radios or checkboxes, build one of the cells in the #options property using the 'title' => array( 'data' => array(#title => 'mytitle'))) construction, as in the $options variable in the usage example below. Backdrop will create invisible label tags for the left column based on this value.
To disable the default "check all" button for the checkboxes, set #js_select property to FALSE. This is FALSE by default for radios.
Setting #multiple to TRUE will give you checkboxes instead of radios.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #default_value, #element_validate, #empty (default: ''), #header, #id, #indentation, #input (default: TRUE), #js_select (default: TRUE), #multiple (default: TRUE), #options (default: array()), #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_tableselect')), #required (default: FALSE), #required_message, #states, #suffix, #theme (default: tableselect), #theme_wrappers, #title_display (default: before), #tree, #type, #weight

Usage Example

(node.admin.inc):

<?php
  // Build the sortable table header.
  $header = array(
    'title' => array('data' => t('Title'), 'field' => 'n.title'),
    'type' => array('data' => t('Type'), 'field' => 'n.type'),
    'author' => t('Author'),
    'status' => array('data' => t('Status'), 'field' => 'n.status'),
    'changed' => array('data' => t('Updated'), 'field' => 'n.changed', 'sort' => 'desc')
  );
...
  //Get the node data.
  $nids = $query
    ->fields('n',array('nid'))
    ->limit(50)
    ->orderByHeader($header)
    ->execute()
    ->fetchCol();
  $nodes = node_load_multiple($nids);
...
  //Build the rows.
  $options = array();
  foreach ($nodes as $node) {
...
    $options[$node->nid] = array(
      'title' => array(
        'data' => array(
          '#type' => 'link',
          '#title' => $node->title,
          '#href' => 'node/' . $node->nid,
          '#options' => $l_options,
          '#suffix' => ' ' . theme('mark', array('type' => node_mark($node->nid, $node->changed))),
        ),
      ),
      'type' => check_plain(node_type_get_name($node)),
      'author' => theme('username', array('account' => $node)),
      'status' => $node->status ? t('published') : t('not published'),
      'changed' => format_date($node->changed, 'short'),
    );
   //For simplicity, this example omits the code to set the operations column.
...
  //Build the tableselect.
  $form['nodes'] = array(
    '#type' => 'tableselect',
    '#header' => $header,
    '#options' => $options,
    '#empty' => t('No content available.'),
  );
?>

tel

Description

Form element to enter a telephone number.

Properties

#access, #after_build, #autocomplete_path (default: FALSE), #attributes (default: array()), #description, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 128), #name, #placeholder, #post_render, #pre_render, #prefix, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 30), #states, #suffix, #theme (default: tel), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #weight, #wrapper_attributes

Usage Example

(contact.pages.inc)

<?php
  $form['phone'] = array(
    '#type' => 'tel',
    '#title' => t('Your phone number'),
    '#required' => $phone == 'required',
  );
?>

textarea

Description

Format a multiple-line text field.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #cols (default: 60), #default_value, #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #name, #placeholder, #post_render, #prefix, #pre_render, #process (default: array('bueditor_textarea', 'ajax_process_form')), #required (default: FALSE), #required_message, #resizable (default: TRUE), #rows (default: 5), #states, #suffix, #theme (default: textarea), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #weight, #wrapper_attributes

Usage Example

<?php
  $form['keywords'] = array(
    '#title' => t('Keywords'),
    '#type' => 'textarea',
    '#description' => t ('The comment will be unpublished if it contains any of the phrases above. Use a case-sensitive, comma-separated list of phrases. Example: funny, bungee jumping, "Company, Inc."'),
    '#default_value' => isset( $context['keywords']) ? backdrop_implode_tags($context['keywords']) : '',
  );
?>

textfield

Description

Format a single-line text field.

Properties

#access, #after_build, #ajax, #array_parents, #attached, #attributes (default: array()), #autocomplete_path (default: FALSE), #default_value, #description, #disabled, #element_validate, #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 128), #name, #parents, #placeholder, #post_render, #prefix, #pre_render, #process (default: array('form_process_autocomplete', 'ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 60), #states, #suffix, #theme (default: textfield), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #value_callback, #weight, #wrapper_attributes

Usage Example

(forum.module):

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

text_format

Description

A text-format-enabled version of a textarea.

Non-standard Properties:

#format: the format to apply. If you want to use the default format, set this property to NULL in your form constructor function, and the filter system will handle the rest.
#base_type (optional): defaults to 'textarea'. This makes it possible to also attach the text format selector to other form element types, such as textfields.

Properties

#access, #after_build, #ajax, #attributes (default: array()), #base_type (default: textarea), #cols (default: 60), #default_value, #description, #disabled, #editor_uploads (default: FALSE), #element_validate, #format (default: NULL), #id, #indentation, #input, #parents, #post_render, #prefix, #pre_render, #process (default: array('filter_process_format')), #required (default: FALSE), #required_message, #resizable (default: TRUE), #rows (default: 5), #states, #suffix, #theme, #theme_wrappers (default: array('text_format_wrapper')), #title, #title_display (default: before), #tree, #type, #weight

Usage Example

(taxonomy.admin.inc):

<?php
  $form['description'] = array(
    '#type' => 'text_format',
    '#title' => t('Description'),
    '#default_value' => $term->description,
    '#format' => $term->format,
    '#weight' => 0,
  );
?>

token

Description

Store token data in a hidden form field (generally used to protect against cross-site forgeries).

Note: A token element is automatically added to each Backdrop form by backdrop_prepare_form(), so you don't generally have to add one yourself.

Properties

#access, #after_build, #attributes (default: array()), #default_value, #element_validate, #id, #input (default: TRUE), #parents, #post_render, #prefix, #pre_render, #process, #required (default: FALSE), #states, #suffix, #theme (default: hidden), #theme_wrappers, #title_display (default: before), #token_types, #tree, #type, #value, #weight

url

Description

Format a url field.

Properties

#access, #after_build, #ajax, #array_parents, #attached, #attributes (default: array()), #autocomplete_path (default: FALSE), #default_value, #description, #disabled, #element_validate (default: array('form_validate_url')), #field_prefix, #field_suffix, #id, #indentation, #input (default: TRUE), #maxlength (default: 255), #name, #parents, #placeholder, #post_render, #prefix, #pre_render, #process (default: array('ajax_process_form')), #required (default: FALSE), #required_message, #size (default: 60), #states, #suffix, #theme (default: url), #theme_wrappers (default: array('form_element')), #title, #title_display (default: before), #tree, #type, #value_callback, #weight, #wrapper_attributes

Usage Example

(forum.module):

<?php
  $form['url'] = array(
    '#type' => 'url',
    '#title' => t('Install from a URL'),
    '#default_value' => $node->title,
    '#description' => t('For example: %url', array('%url' => 'https://github.com/backdrop-contrib/module/archive/1.x-1.2.3.zip')),
    '#required' => TRUE,
  );
?>

value

Description

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

Properties

#token_types, #type, #value

Usage Example

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

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

vertical_tabs

Description

Formats all child fieldsets as vertical tabs. Non-child fieldsets can be added to the vertical tab by setting their #group to the vertical tab's element name.

Properties

#access, #after_build, #default_tab (default: ''), #element_validate, #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_vertical_tabs')), #states, #suffix, #theme, #theme_wrappers (default: array('vertical_tabs')), #tree, #type, #weight

Usage Example

  $form['additional_settings'] = array(
    '#type' => 'vertical_tabs',
    '#weight' => 99,
    '#attached' => array(
      'js' => array(backdrop_get_path('module', 'user') . '/js/user.admin.js'),
    ),
  );

weight

Description

Format a weight selection menu.

Properties

#access, #after_build, #attributes (default: array()), #default_value, #delta (default: 10), #description, #disabled, #element_validate, #id, #indentation, #input (default: TRUE), #parents, #post_render, #prefix, #pre_render, #process (default: array('form_process_weight', 'ajax_process_form')), #required (default: FALSE), #required_message, #states, #suffix, #theme, #theme_wrappers, #title, #title_display (default: before), #tree, #type, #weight

Usage Example

(menu.module):

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

Properties

#access

Used By

actions, ajax, button, checkbox, checkboxes, color, container, contextual_links, date, dropbutton, email, fieldset, field_ui_table, file, form, head_tag, help, hidden, html_date, html_datetime, html_time, image_button, item, link, link_field, machine_name, managed_file, markup, number, operations, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, vertical_tabs, weight

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

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

#after_build

Used By

actions, ajax, button, checkbox, checkboxes, color, container, contextual_links, date, dropbutton, email, fieldset, field_ui_table, file, form, head_tag, hidden, html_date, html_datetime, html_time, image_button, item, link, link_field, machine_name, managed_file, markup, number, operations, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, vertical_tabs, weight

Description

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

Usage Example

(system.admin.inc):

<?php
  $form['file_public_path'] = array(
    '#type' => 'textfield',
    '#title' => t('Public file system path'),
    '#default_value' => variable_get('file_public_path', conf_path() . '/files'),
    '#maxlength' => 255,
    '#description' => t('A local file system path where public files will be stored. This directory must exist and be writable by Backdrop. This directory must be relative to the Backdrop installation directory and be accessible over the web.'),
    '#after_build' => array('system_check_directory'),
  );
?>

#aggregate_callback

Used By

scripts, styles

Description

A function to call to aggregate the items within the groups arranged by the #group_callback function. See backdrop_pre_render_styles().

#ajax

Used By

Description

An array of elements whose values control the behavior of the element with respect to the Backdrop AJAX framework.

AJAX (Asynchronous Javascript and XML) is a term used for dynamic communication between the browser and the server, without page reloads. In a nutshell an AJAX request follows these steps:

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

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

#ajax['callback']

Used By

Description

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

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

Values

String containing a function name.

Usage Example

(poll.module):

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

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

#ajax['effect']

Used By

Description

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

Values

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

#ajax['event']

Used By

Description

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

Values

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

#ajax['keypress']

Used By

Description

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

#ajax['method']

Used By

Description

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

Values

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

#ajax['path']

Used By

Description

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

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

Values

String containing a Backdrop menu path.

#ajax['prevent']

Used By

Description

A JavaScript event to prevent when 'event' is triggered. Defaults to 'click' for #ajax on #type 'submit', 'button', and 'image_button'. Multiple events may be specified separated by spaces. For example, when binding #ajax behaviors to form buttons, pressing the ENTER key within a textfield triggers the 'click' event of the form's first submit button. Triggering Ajax in this situation leads to problems, like breaking autocomplete textfields. Because of that, Ajax behaviors are bound to the 'mousedown' event on form buttons by default. However, binding to 'mousedown' rather than 'click' means that it is possible to trigger a click by pressing the mouse, holding the mouse button down until the Ajax request is complete and the button is re-enabled, and then releasing the mouse button. For this case, 'prevent' can be set to 'click', so an additional event handler is bound to prevent such a click from triggering a non-Ajax form submission. This also prevents a textfield's ENTER press triggering a button's non-Ajax form submission behavior.

Values

String. Possible values: One or more jQuery events, with multiple events separated by space characters.

#ajax['progress']

Used By

Description

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

Values

Array.

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

Possible values:

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

Usage Example

(file.module):

<?php
  $ajax_settings['progress']['type'] ? $ajax_settings['progress']['type'] == 'bar' : 'throbber';
  $ajax_settings['progress']['message'] = NULL;
  $ajax_settings['effect'] = 'none';
  $element['remove_button'] = array(
    '#name' => implode('_', $element['#parents']) . '_remove_button',
    '#type' => 'submit',
    '#value' => t('Remove'),
    '#validate' => array(),
    '#submit' => array('file_managed_file_submit'),
    '#limit_validation_errors' => array($element['#parents']),
    '#ajax' => $ajax_settings,
    '#weight' => -5,
  );
?>

#ajax['trigger_as']

Used By

Description

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

Values

Array.

Possible values

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

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

#ajax['wrapper']

Used By

Description

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

Values

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

Usage Example

(book.module):

<?php
  // Add a drop-down to select the destination book.
  $form['book']['bid'] = array(
    '#type' => 'select',
    '#title' => t('Book'),
    '#default_value' => $node->book['bid'],
    '#options' => $options,
    '#access' => (bool) $options,
    '#description' => t('Your page will be a part of the selected book.'),
    '#weight' => -5,
    '#attributes' => array('class' => array('book-title-select')),
    '#ajax' => array(
      'callback' => 'book_form_update',
      'wrapper' => 'edit-book-plid-wrapper',
      'effect' => 'fade',
      'speed' => 'fast',
    ),
  );
?>

#allow_focus

Used By

checkbox

Description

This property, when set to TRUE, turns a #disabled element into a read-only element.

It is common in Backdrop to make a normally editable element non-editable by setting #disabled = TRUE, but in that case, the element value will not be included in the form submission in $_POST. To include its value, set $allow_focus to TRUE.

Values

TRUE or FALSE.

Usage Example

<?php
  // A disabled textedit field that won't be submitted.
  $form['edit_1'] = array(
    '#type' => 'textfield',
    '#title' => t('Field 1'),
    '#default_value' => 'Some value',
    '#disabled' => TRUE,
  );
  
  // A disabled textedit field that is read-only and will be submitted.
  $form['edit_2'] = array(
    '#type' => 'textfield',
    '#title' => t('Field 2'),
    '#default_value' => 'Some value',
    '#disabled' => TRUE,
    '#allow_focus' => TRUE,
  );
?>

#array_parents

Used By

checkbox, file, html_date, html_datetime, html_time, managed_file, textfield, url

Description

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

#attached

Used By

checkbox, contextual_links, file, form, html_date, html_datetime, html_time, managed_file, options, textfield, url

Description

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

Values

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

See backdrop_process_attached() for additional information.

Usage Example

(AJAX Example):

<?php
  $form['#attached']['css'] = array(
    backdrop_get_path('module', 'ajax_example') . '/ajax_example.css',
  );
    $form['#attached']['js'] = array(
    backdrop_get_path('module', 'ajax_example') . '/ajax_example.js',
  );
?>

The above javascript #attach could also be written as:

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

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

Adding settings

You add a javascript setting by using the 'data' key (as php keys can't be arrays):

<?php
  $settings = array('id' => 'mymodule-element-1');
  $form['#attached']['js'][] = array(
    'data' => array('mymodule' => $settings),
    'type' => 'setting',
  );
?>

Usage example (contact.pages.inc):

<?php
  if (!$user->uid) {
    $form['#attached']['library'][] = array('system', 'jquery.cookie');
    $form['#attributes']['class'][] = 'user-info-from-cookie';
  }
?>

#attributes

Used By

actions, ajax, button, checkbox, checkboxes, color, container, contextual_links, date, details, dropbutton, email, fieldset, field_ui_table, file, form, head_tag, html_date, html_datetime, html_time, image_button, link, link_field, machine_name, managed_file, number, operations, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, weight

Description

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

Values

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

Usage Example

(search.module):

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

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

#autocomplete_path

Used By

color, email, machine_name, search, tel, textfield, url

Description

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

Usage Example

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

#base_type

Used By

text_format

Description

The form element #type to use for the 'value' element when expanding an element into a base element with text format selector attached.

Values

This should be the machine name of one of the text format types.

#browser_view

Used By

managed_file

Description

The name of the View to use as a browser for managed files.

Values

FALSE or the name of the View.

#built

Used By

Description

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

Values

TRUE or FALSE.

Usage Example

INTERNAL. See the _form_builder function in form.inc.

#button_type

Used By

button, image_button, submit

Description

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

Values

String.

Usage Example

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

#children

Used By

actions, container, details, range

Description

Internal. The rendered child elements of an element. Automatically assigned by backdrop_render(), unless already set. In rare cases, you may use #children to override the output of rendered child elements, for example in a #theme_wrappers or #post_render callback. Normally, you should not have to use #children, use regular child elements instead. (See actions for an example.)

Values

String representing the rendered child elements of an element.

Usage Example

(theme_container()):
Example in a #theme_wrappers callback.

<?php
  function theme_container($variables) {
    $element = $variables['element'];

...

    return '<div' . backdrop_attributes($element['#attributes']) . '>' . $element['#children'] . '</div>';
  }
?>

#collapsed

Used By

fieldset

Description

Specifies whether a fieldset that is collapsible is initially collapsed.

Values

TRUE or FALSE.

Usage Example

<?php
  $form['comment'] = array(
    '#type' => 'fieldset',
    '#title' => t('Comment settings'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#group' => 'additional_settings',
    '#attributes' => array(
      'class' => array('comment-node-type-settings-form'),
    ),
    '#attached' => array(
      'js' => array(backdrop_get_path('module', 'comment') . '/js/comment.admin.js'),
    ),
    '#weight' => 25,
  );
?>

#collapsible

Used By

fieldset

Description

Specifies whether a fieldset can be collapsed.

Values

TRUE or FALSE.

Usage Example

<?php
  $form['comment'] = array(
    '#type' => 'fieldset',
    '#title' => t('Comment settings'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#group' => 'additional_settings',
    '#attributes' => array(
      'class' => array('comment-node-type-settings-form'),
    ),
    '#attached' => array(
      'js' => array(backdrop_get_path('module', 'comment') . '/js/comment.admin.js'),
    ),
    '#weight' => 25,
  );
?>

#cols

Used By

textarea, text_format

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,
  );
?>

#commands

Used By

ajax

Description

A form property containing AJAX commands of the form returned by ajax_command_*(). See the AJAX Framework for details on usage.

Usage Example

(config.admin.inc)

<?php
function config_export_single_form_update_type($form, &$form_state) {
  // Empty out the configuration value field.
  $form['export']['#value'] = '';
  $form['export']['#rows'] = 12;

  // Because we need to replace both the configation name select and the
  // textarea, this requires using AJAX commands instead of a simple return.
  $commands = array();
  $commands[] = ajax_command_replace('#edit-config-type-wrapper', backdrop_render($form['config_name']));
  $commands[] = ajax_command_replace('#edit-export-wrapper', backdrop_render($form['export']));
  $commands[] = ajax_command_prepend(NULL, theme('status_messages'));
  return array(
    '#type' => 'ajax',
    '#commands' => $commands,
  );
}
?>

#config

Used By

form

Description

Name of configuration file where form submission values are to be stored.

If #config is used at the top level of the form array (see Example 1 below), all submitted values in the form will be saved under the corresponding key in the configuration file. If form sub-elements or groups of sub-elements have their own #config keys, then values of those elements and their children will be saved to that configuration file (see Example 2 below).

Once this property is set, the form variable must be passed to system_settings_form(), which will add the appropriate handlers to store the form values.

Values

String containing a configuration file name, with the '.json' extension removed.

Usage Example

Example 1

(admin_bar.inc):

<?php
  $form['#config'] = 'admin_bar.settings';
  $form['margin_top'] = array(
    '#type' => 'checkbox',
    '#title' => t('Adjust top margin'),
    '#default_value' => $config->get('margin_top'),
    '#description' => t('Shifts the entire site content down to make room for the administration bar. If disabled, absolute- or fixed-positioned page elements may be covered by the administration bar.'),
  );
  // ...
  return system_settings_form($form);
?>

Example 2

All sub-elements of the fieldset $form['user_login'] will be stored to system.core.json, while the rest of the elements will be stored in user.flood.json

(user.admin.inc)

<?php
  $form['#config'] = 'user.flood';

  // User login settings.
  $form['user_login'] = array(
    '#type' => 'fieldset',
    '#title' => t('User login'),
    '#weight' => -2,
    '#config' => 'system.core',
  );
  $form['user_login']['user_login_method'] = array(
    '#type' => 'radios',
    '#title' => t('Users may log in using'),
    '#options' => array(
      USER_LOGIN_USERNAME_OR_EMAIL => t('Username or email address'),
      USER_LOGIN_USERNAME_ONLY => t('Username'),
      USER_LOGIN_EMAIL_ONLY => t('Email address'),
    ),
    '#default_value' => $core_config->get('user_login_method'),
  );
  // ...
  return system_settings_form($form);
?>

#default_tab

Used By

vertical_tabs

Description

The default open tab.

Values

String containing the HTML ID of the fieldset element for the default tab. The default value is an empty string, which results in the first tab having the focus. The elements's HTML ID typically takes the form of "edit-ARRAY_KEY".

Usage Example

<?php
  $form['vertical_tabs'] = array(
    '#type' => 'vertical_tabs',
    '#default_tab' => 'edit-tab2',
  );
  $form['tab1'] = array(
    '#type' => 'fieldset',
    '#title' => t('Tab 1'),
    '#group' => 'vertical_tabs',
  );
  $form['tab1']['field1'] = array(
    '#title' => t('Field 1'),
    '#type' => 'textfield',
  );
  $form['tab2'] = array(
    '#type' => 'fieldset',
    '#title' => t('Tab 2'),
    '#group' => 'vertical_tabs',
  );
  $form['tab2']['field2'] = array(
    '#title' => t('Field 2'),
    '#type' => 'textfield',
  );
?>

#default_value

Used By

checkbox, checkboxes, color, date, hidden, html_date, html_datetime, html_time, machine_name, radio, radios, select, tableselect, textarea, textfield, text_format, token, url, 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,
  );
?>

#default_value_allowed

Used By

options

Description

Indicates whether the end user should be able to modify the default value when editing an options list.

Values

TRUE or FALSE.

#default_value_pattern

Used By

options

Description

If allowing dynamic default value keys, such as a token, specify a regular expression pattern that will also be allowed as a default value. Include pattern delimiters.

#delta

Used By

weight

Description

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

Values

A positive number.

Usage Example

(menu.module):

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

#description

Used By

checkbox, checkboxes, color, date, email, fieldset, file, html_date, html_datetime, html_time, item, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, radios, range, search, select, tel, textarea, textfield, text_format, url, 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.'),
  );
?>

#details

Used By

details

Description

Full details information for a details element.

#disabled

Used By

Description

Disables (greys out) a form input element. Setting #disabled to TRUE results in user input being ignored, regardless of how the element is themed or whether JavaScript is used to change the control's attributes.

Values

TRUE or FALSE.

Usage Example

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

#editor_uploads

Used By

text_format

Description

Specifies whether uploads are allowed.

Values

TRUE or FALSE.

Usage Example

(block.module)

<?php
  $form['body'] = array(
    '#type' => 'text_format',
    '#title' => t('Block content'),
    '#default_value' => $edit['body']['value'],
    '#format' => $edit['body']['format'],
    '#editor_uploads' => TRUE,
    '#rows' => 8,
    '#required' => TRUE,
  );
?>

#element_validate

Used By

button, checkbox, checkboxes, color, date, email, fieldset, file, hidden, html_date, html_datetime, html_time, image_button, item, machine_name, managed_file, markup, number, options, password, password_confirm, radio, radios, range, select, submit, tableselect, textarea, textfield, text_format, token, url, vertical_tabs, weight

Description

A list of custom validation functions. The validation functions must use form_error() or form_set_error() to flag the element as having 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 $element, $form_state, and $form as parameters, and has the form:

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

For the function name, you can use any valid PHP Callback, for example:

'#element_validate' => array('myelement_validate'), a function name;
'#element_validate' => array('CLASS::METHOD'), a static class method;
'#element_validate' => array(array('CLASS', 'METHOD')), another way of specifying a static class method;
'#element_validate' => array(array($my_object, 'METHOD')), a method of a class object;
'#element_validate' => array(array($this, 'METHOD')), a method of a class object, when this property is used within another method of the same class.

Usage Example

(file.field.inc):

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

You'll notice that the validation function below includes only the first two arguments. $form is the same as $form_state['complete form'], so the third parameter is in fact contained in the second parameter.

<?php
  $form['max_filesize'] = array(
    '#type' => 'textfield',
    '#title' => t('Maximum upload size'),
    '#default_value' => $settings['max_filesize'],
    '#description' => t('Enter a value like "512" (bytes), "80 KB" (kilobytes) or "50 MB" (megabytes) in order to restrict the allowed file size. If left empty the file sizes will be limited only by PHP\'s maximum post and file upload sizes (current limit <strong>%limit</strong>).', array('%limit' => format_size(file_upload_max_size()))),
    '#size' => 10,
    '#element_validate' => array('_file_generic_settings_max_filesize'),
    '#weight' => 5,
  );
...
  function _file_generic_settings_max_filesize($element, &$form_state) {
    if (!empty($element['#value']) && !is_numeric(parse_size($element['#value']))) {
      form_error($element, t('The "!name" option must contain a valid value. You may either leave the text field empty or enter a string like "512" (bytes), "80 KB" (kilobytes) or "50 MB" (megabytes).', array('!name' => t($element['title']))));
    }
  }
?>

#empty

Used By

tableselect

Description

Text to display if the #options property is empty.

Values

Text, enclosed in the t() translation function.

#empty_option

Used By

select

Description

The label to show for the initial option denoting no selection in a select element. By default, the label is automatically set to "- Select -" for a required field and "- None -" for an optional field.

Values

Text, enclosed in the t() translation function.

Note: Use of this property plays a part in several possible states for a select field:

If #required is TRUE and there is no #default_value, an empty option is added to the select control to force the user to make an active choice.
If #empty_value or #empty_option is set and #required is FALSE (default), an empty option is added to the select control, allowing the user to choose nothing.
If none of #required, #empty_value, #empty_option, and #default_value are set, then no empty option is added to the select control. This leaves the control in a slightly illogical state, since all user agents automatically preselect the first available option.There's no way for the user to select nothing, and the user is also not forced to make an active decision.

#empty_value

Used By

select

Description

The value for the initial option denoting no selection in a select element, which is used to determine whether the user submitted a value or not.

Values

Defaults to empty string. Can be anything except NULL.

Note: Use of this property plays a part in several possible states for a select field:

If #required is TRUE and there is no #default_value, an empty option is added to the select control to force the user to make an active choice.
If #empty_value or #empty_option is set and #required is FALSE (default), an empty option is added to the select control, allowing the user to choose nothing.
If none of #required, #empty_value, #empty_option, and #default_value are set, then no empty option is added to the select control. This leaves the control in a slightly illogical state, since all user agents automatically preselect the first available option. There's no way for the user to select nothing, and the user is also not forced to make an active decision.

#error

Used By

ajax

Description

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

#executes_submit_callback

Used By

button, image_button, submit

Description

Indicates whether or not the submit handler should be run when the form is submitted using this button element.

Values

TRUE or FALSE.

#extended

Used By

managed_file

Description

Indicates whether the managed file element is extended with additional properties. See file_field_widget_form().

Usage Example

(file_module_text.module)

<?php
  $form['nested']['file'] = array(
    '#type' => 'managed_file',
    '#title' => t('Managed file'),
    '#upload_location' => 'public://test',
    '#progress_message' => t('Please wait...'),
    '#extended' => (bool) $extended,
    '#size' => 13,
  );
?>

#field_prefix

Used By

checkbox, color, date, email, file, html_date, html_datetime, html_time, item, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, range, search, select, tel, textarea, textfield, url

Description

Text or code that is placed directly in front of a field. This can be used to prefix a field with a constant string. It should be translated, normally. If it is not already wrapped in a safe markup object, will be filtered for XSS safety.

Note that (unlike #prefix and #suffix), #field_prefix (and #field_suffix) work properly with #states.

Any HTML markup in #field_prefix (or #field_suffix) should be complete, as both will be independently wrapped in span tags. That is, you should not put an opening tag in #field_prefix and its close in #field_suffix. Use #prefix and #suffix to wrap the field in another tag.

Values

Mixed.

Usage Example

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

Description

Text or code that is placed directly after a field. This can be used to add a unit to a field (often a #number field).

Note that (unlike #prefix and $suffix), #field_prefix (and #field_suffix) work properly with #states.

Values

Mixed.

Usage Example

<?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')
  );
?>

#format

Used By

text_format

Description

A format type for the text_format element.

Values

This should be the machine name of one of the text format types.

#group

Used By

fieldset

Description

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

Values

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

Usage Example

(user.admin.inc):

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

#group_callback

Used By

scripts, styles

Description

A function to call to group #items to enable the use of fewer tags by aggregating files and/or using multiple @import statements within a single tag. See backdrop_pre_render_styles().

#has_garbage_value

Used By

image_button

Description

An indicator used in image buttons to indicate not to pass the value of that element.

Used By

ajax, tableselect

Description

Column headers.

Values

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

#href

Used By

link

Description

Target path for a link.

Values

String giving the path of a link.

Usage Example

(block.admin.inc)

<?php
  $form['actions']['delete'] = array(
    '#type' => 'link',
    '#title' => t('Delete'),
    '#href' => 'admin/structure/block/manage/' . $delta . '/delete',
    '#attributes' => array('class' => array('button', 'button-secondary', 'form-delete')),
  );
?>

#https

Used By

form

Description

A property of a form that specifies whether it should be posted as https.

Values

TRUE or FALSE

Usage Example

(authorize.inc)

<?php
function authorize_filetransfer_form($form, &$form_state) {
  global $is_https;
  $form = array();

  // If possible, we want to post this form securely via HTTPS.
  $form['#https'] = TRUE;
  ...
}
?>

#id

Used By

actions, ajax, button, checkbox, checkboxes, color, container, contextual_links, date, details, email, field_ui_table, file, form, head_tag, html_date, html_datetime, html_time, image_button, item, link, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, weight

Description

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

Values

HTML ID string.

#indentation

Used By

Description

An integer quantity that specifies the level of indentation to be applied to this form element. Used for conveying hierarchical relationships between form elements and/or dependencies.

Note that for checkboxes, radios, and select form elements, distinct values of indentation can be applied to the individual checkboxes, radio buttons, and select values, as illustrated in the usage example.

Introduced in Backdrop 1.25.0.

Values

Integer between 0 and 5. (Higher levels of indentation are not currently supported in core CSS.)

Usage Example

(form_test.module)

<?php
  $form['checkboxes'] = array(
    '#type' => 'checkboxes',
    '#title' => 'Indented checkboxes',
    '#options' => array(
      0 => 'No indentation',
      'foo' => 'One indentation',
      3 => 'No indentation 2',
      'bar' => 'Two indentations',
    ),
  );
  $form['checkboxes']['foo']['#indentation'] = 1;
  $form['checkboxes']['bar']['#indentation'] = 2;
?>

#input

Used By

Description

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

#items

Used By

scripts, styles

Description

A list of CSS or JS files provided to the #styles or #scripts form element.

Usage Example

<?php
function backdrop_get_css($css = NULL, $skip_alter = FALSE) {
  if (!isset($css)) {
    $css = backdrop_add_css();
  }
  ...

  // Render the HTML needed to load the CSS.
  $styles = array(
    '#type' => 'styles',
    '#items' => $css,
  );
  ...

  return backdrop_render($styles);
}
?>

#js_select

Used By

tableselect

Description

Whether to include a select all checkbox.

Values

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

#key_type

Used By

options

Description

The method by which keys are determined for each value in an option list.

Values

'mixed', 'numeric', 'associative', 'custom', or 'none'. See options_element_info() for description.

#key_type_toggle

Used By

options

Description

If specified for an 'option' element, a checkbox will be added that allows the user to toggle between the current key type and the "custom" key type, letting them customize the keys as desired. This option has no effect with the "none" key type.

Values

A test string.

#key_type_toggled

Used By

options

Description

Determine if the toggle checkbox is set or not by default.

Values

TRUE or FALSE.

#limit

Used By

options

Description

The maximum number of options that can be added to an options list. Defaults to 100.

Values

Any nonnegative integer.

#limit_validation_errors

Used By

button, image_button, submit

Description

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

Values

Array indicating sections of the $form_state['values'] which should be validated.

#links

Used By

contextual_links, dropbutton, operations

Description

A structured array giving a list of links used in a dropbutton or operations element.

Values

An array of arrays, each link array containing the following keys:

title (required) — the title of the link. Should be wrapped in t().
href (required) — the destination of the link.
attributes (optional) — any attributes, such as 'class', to be applied to the <a> tag.
query (optional) — additional query parameters. See the documentation for url() for further information.

Usage Example

(views_ui.admin.inc)

<?php
  $element['extra_actions']['#links']['export'] = array(
    'title' => t('export view'),
    'href' => 'admin/config/development/configuration/single/export',
    'query' => array(
      'group' => 'Views',
      'name' => 'views.view.' . $view->name,
    ),
  );
?>

#markup

Used By

help, item, markup

Description

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

Values

Text (valid HTML).

Usage Example

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

#max

Used By

number, range

Description

Establishes a maximum value for a number element.

Values

Any valid numeric quantity.

Usage Example

<?php
  $form['comment']['comment_per_page'] = array(
    '#type' => 'number',
    '#title' => t('Comments per page'),
    '#default_value' => $node_type->settings['comment_per_page'],
    '#required' => TRUE,
    '#min' => 10,
    '#max' => 1000,
    '#step' => 10,
  );
?>

#maxlength

Used By

email, machine_name, password, range, search, tel, textfield, url

Description

The maximum amount of characters to accept as input.

Values

A positive number.

Usage Example

(forum.module):

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

#method

Used By

form

Description

The HTTP method with which the form will be submitted.

Values

GET or POST. Default is POST.

Usage Example

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

#min

Used By

number, range

Description

Establishes a minimum value for a number element.

Values

Any legal numeric value.

Usage Example

<?php
  $form['comment']['comment_per_page'] = array(
    '#type' => 'number',
    '#title' => t('Comments per page'),
    '#default_value' => $node_type->settings['comment_per_page'],
    '#required' => TRUE,
    '#min' => 10,
    '#max' => 1000,
    '#step' => 10,
  );
?>

#multiple

Used By

options, select, tableselect

Description

Indicates whether the user may select more than one item.

Values

TRUE or FALSE.

Usage Example

(taxonomy.module):

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

#name

Used By

button, checkbox, color, date, email, field_ui_table, file, html_date, html_datetime, html_time, item, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, range, search, select, submit, tel, textarea, textfield, url

Description

The name attribute of the corresponding HTML element. This can be used in element types such as submit, button and file to override the default setting.

Values

String.

#open

Used By

details

Description

Initial collapsed/expanded display.

#optgroups

Used By

options

Description

If nesting of options is supported, up to one level. This is used when building a select HTML element that uses optgroups. Defaults to FALSE.

Values

TRUE or FALSE.

#options

Used By

checkboxes, link, options, radios, select, tableselect

Description

There are two use cases for this property:

Selectable options for a form element that allows multiple choices (checkboxes, radios, select, tableselect).
Alternative way of specifying attributes for a link element.

Important note: You should not mix integer and string keys in a list of options; the keys should be either all integers or all strings. When PHP compares integers to strings (something that's likely to happen anytime someone is checking whether a particular key was chosen), it casts the strings to integers, which can give unexpected results. See, for example, backdrop/backdrop-issues#6024.

Values

In multiple-choice form elements: An array in the form of
```
<?php
array(t('Display value 1'), t('Display value 2'))
?>
```
or
```
<?php
array(
  'return_value1' => t('Display Value 1'),
  'return_value2' => t('Display Value 2'),
)
?>
```
if specific return values are required. If returned values are identical to displayed values, you can use backdrop_map_assoc() as in the example below. The #options property needs special handling for checkboxes, and works completely differently for tableselect.
In link elements: An array of values that could be supplied as the third argument to l().

Usage Example

(form_example_states.inc):

<?php
  $form['undergraduate']['school_country'] = array(
    '#type' => 'select',
    '#options' => backdrop_map_assoc(array(t('UK'), t('Other'))),
    '#title' => t('In what country is your college or university located?'),
  );
?>

(field_ui.admin.inc):

<?php
  'widget_type' => array(
    '#type' => 'link',
    '#title' => t($widget_types[$instance['widget']['type']]['label']),
    '#href' => $admin_field_path . '/widget-type',
    '#options' => array('attributes' => array('title' => t('Change widget type.'))),
  ),
?>

(file.pages.inc):

<?php
  $form['actions']['cancel'] = array(
    '#type' => 'link',
    '#title' => t('Cancel'),
    '#href' => $url['path'],
    '#options' => array('query' => $url['query']),
    '#weight' => 15,
  );
?>

#options_readonly

Used By

options

Description

Indicates whether an option list is read-only.

Values

TRUE or FALSE.

#parents

Used By

Description

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

Values

An array of element names.

Usage Example

(file_module_test.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,
  );
?>

#parent_options

Used By

field_ui_table

Description

Options to be passed to the parent HTML element.

Usage Example

(field_ui.admin.inc)

<?php
  $table = array(
    '#type' => 'field_ui_table',
    '#tree' => TRUE,
    '#header' => array(
      t('Field'),
      t('Weight'),
      t('Parent'),
      t('Label'),
      array('data' => t('Format'), 'colspan' => 3),
    ),
    '#regions' => array(
      'visible' => array('message' => t('No field is displayed.')),
      'hidden' => array('title' => t('Hidden'), 'message' => t('No field is hidden.')),
    ),
    '#parent_options' => array(),
    '#attributes' => array(
      'class' => array('field-ui-overview'),
      'id' => 'field-display-overview',
    ),
    // Add Ajax wrapper.
    '#prefix' => '<div id="field-display-overview-wrapper">',
    '#suffix' => '</div>',
  );
?>

#password_shown

Used By

password

Description

Indicates whether the password is (initially) shown or greeked on a password form element.

Values

TRUE or FALSE.

Usage Example

(form.inc)

<?php
  $element['pass1'] =  array(
    '#type' => 'password',
    '#title' => t('New password'),
    '#value' => empty($element['#value']) ? NULL : $element['#value']['pass1'],
    '#required' => $element['#required'],
    '#attributes' => array('class' => array('password-field')),
    '#password_strength' => TRUE,
    '#password_shown' => FALSE,
    '#password_toggle' => FALSE,
  );
?>

#password_strength

Used By

password

Description

Specifies whether to provide an evaluation of password strength on a password form element.

Values

TRUE or FALSE.

Usage Example

(install.core.inc)

<?php
  $form['admin_account']['account']['pass'] = array(
    '#title' => st('Password'),
    '#type' => 'password',
    '#required' => TRUE,
    '#weight' => 0,
    '#password_toggle' => TRUE,
    '#password_strength' => TRUE,
  );
?>

#password_toggle

Used By

password

Description

Specifies whether to allow the user to toggle between showing and hiding a password in a password field element.

Values

TRUE or FALSE.

Usage Example

(install.core.inc)

<?php
  $form['admin_account']['account']['pass'] = array(
    '#title' => st('Password'),
    '#type' => 'password',
    '#required' => TRUE,
    '#weight' => 0,
    '#password_toggle' => TRUE,
    '#password_strength' => TRUE,
  );
?>

#placeholder

Used By

color, number, password, search, tel, textarea, textfield, url

Description

Defines a short prompt or example text to be displayed in an input field using HTML5's placeholder attribute.

Values

Text, enclosed in the t() translation function.

Usage Example

<?php
  $form['password'] = array(
    '#type' => 'password',
    '#title' => t('Password'),
    '#placeholder' => t('Enter password'),
  );
?>

#post_render

Used By

Description

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

Values

An array of function names to call.

Usage Example

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

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

#prefix

Used By

Description

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

You can use #prefix and #suffix to wrap the element in another HTML tag, as in the example below.

Note: do not use #field_prefix and #field_suffix in the same manner, as these properties require complete HTML tags (HTML elements that have both opening and closing tags).

Values

Mixed.

Usage Example

(poll.module):

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

#pre_render

Used By

Description

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

Values

An array of function names to call.

Usage Example

(filter.module):

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

<?php
  // Prepend #pre_render callback to replace field value with user notice
  // prior to rendering.
  if (!isset($element['value']['#pre_render'])) {
    $element['value']['#pre_render'] = array();
  }
  array_unshift($element['value']['#pre_render'], 'filter_form_access_denied');
...
  function filter_form_access_denied($element) {
    $element['#value'] = t('This field has been disabled because you do not have sufficient permissions to edit it.');
    return $element;
  }
?>

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

#printed

Used By

Description

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

#process

Used By

Description

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

Values

Array of function names (strings).

Usage Example

(system.module) in system_element_info():

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

<?php
  $types['radios'] = array(
    '#input' => TRUE,
    '#process' => array('form_process_radios'),
    '#theme_wrappers' => array('radios'),
    '#pre_render' => array('form_pre_render_conditional_form_element'),
  );
?>

In this example, the function form_process_radios is called; the entire radios element is passed in as the argument. This function expands a radios element into individual radio buttons.

#processed

Used By

Description

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

#progress_indicator

Used By

managed_file

Description

What type of progress indicator to display during file uploads.

Values

'throbber' or 'bar' or 'none'.

Usage Example

(file.pages.inc)

<?php
  $form['upload'] = array(
    '#type' => 'managed_file',
    '#title' => t('Upload a new file'),
    '#upload_location' => file_upload_destination_uri($options),
    '#upload_validators' => file_get_upload_validators($options),
    '#progress_indicator' => 'bar',
    '#pre_render' => array('file_managed_file_pre_render', 'file_upload_validators_pre_render'),
    '#default_value' => isset($form_state['storage']['upload']) ? $form_state['storage']['upload'] : NULL,
  );
?>

#progress_message

Used By

managed_file

Description

Message to display while a file is uploading.

Values

A string or NULL.

Usage Example

<?php
  $form['nested']['file'] = array(
    '#type' => 'managed_file',
    '#title' => t('Managed file'),
    '#upload_location' => 'public://test',
    '#progress_message' => t('Please wait...'),
    '#extended' => (bool) $extended,
    '#size' => 13,
  );
?>

#redirect

Used By

form

Description

Indicates where the person who is using the form should be redirected when the form submits.

Values

string

Usage Example

(system.admin.inc)

<?php
$form['#redirect'] = 'admin/config/media/file-system/settings';<br>
?>

#regions

Used By

field_ui_table

Description

Property of a 'field_ui_table' element.

Usage Example

(field_ui.admin.inc)

<?php
  $table = array(
    '#type' => 'field_ui_table',
    '#tree' => TRUE,
    '#header' => array(
      t('Field'),
      t('Weight'),
      t('Parent'),
      t('Label'),
      array('data' => t('Format'), 'colspan' => 3),
    ),
    '#regions' => array(
      'visible' => array('message' => t('No field is displayed.')),
      'hidden' => array('title' => t('Hidden'), 'message' => t('No field is hidden.')),
    ),
    '#parent_options' => array(),
    '#attributes' => array(
      'class' => array('field-ui-overview'),
      'id' => 'field-display-overview',
    ),
    // Add Ajax wrapper.
    '#prefix' => '<div id="field-display-overview-wrapper">',
    '#suffix' => '</div>',
  );
?>

#required

Used By

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,
  );
?>

#required_message

Used By

Description

Form elements that have the #required property will display a generic error if the value is left empty. You can set #required_message to a custom message to display instead.

Introduced in Backdrop 1.23.0.

Values

A translated string.

Usage Example

(form_test.module):

<?php
  $form['checkboxes'] = array(
    '#type' => 'checkboxes',
    '#title' => t('Checkboxes'),
    '#options' => $options,
    '#required' => TRUE,
    '#required_message' => t('Please choose at least one option.'),
  );
?>

#resizable

Used By

textarea, text_format

Description

Whether users should be allowed to resize the text area.

Values

TRUE or FALSE.

#return_value

Used By

checkbox, image_button, radio

Description

Value element should return when selected.

Values

Mixed.

Usage Example

(poll.module):

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

#rows

Used By

textarea, text_format

Description

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

Values

A positive number.

Usage Example

(aggregator.module):

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

#size

Used By

email, file, machine_name, managed_file, number, password, password_confirm, range, search, select, tel, textfield, url

Description

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

Values

A positive number.

Usage Example

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

#src

Used By

image_button

Description

The URL of the image of the button.

Values

A URL.

#states

Used By

actions, button, checkbox, checkboxes, color, container, date, dropbutton, fieldset, file, form, hidden, html_date, html_datetime, html_time, image_button, item, link, machine_name, managed_file, number, operations, password, password_confirm, radio, radios, search, select, submit, tableselect, tel, textarea, textfield, text_format, token, url, vertical_tabs, weight

Description

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

Values

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

Usage Example

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

#step

Used By

number, range

Description

Establishes that the value must be offset from the minimum value (or zero if there is no minimum) by an integral multiple of this value.

Values

Any positive numeric value or 'any' if there is no step requirement.

Usage Example

<?php
  $form['comment']['comment_per_page'] = array(
    '#type' => 'number',
    '#title' => t('Comments per page'),
    '#default_value' => $node_type->settings['comment_per_page'],
    '#required' => TRUE,
    '#min' => 10,
    '#max' => 1000,
    '#step' => 10,
  );
?>

#submit

Used By

button, form, image_button, submit

Description

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

Values

An array of function names to be called upon submission of this form (after successful validation).

A submission function for a form takes $form and $form_state as parameters. For example:

<?php
function test_form_submit($form, &$form_state) {
  // Do something with the values submitted in $form_state['values'].
}
?>

For the function name, you can use any valid PHP Callback, for example:

'#submit' => array('myelement_validate'), a function name;
'#submit' => array('CLASS::METHOD'), a static class method;
'#submit' => array(array('CLASS', 'METHOD')), another way of specifying a static class method;
'#submit' => array(array($my_object, 'METHOD')), a method of a class object;
'#submit' => array(array($this, 'METHOD')), a method of a class object, when this property is used within another method of the same class.

Usage Example

(node_form()):

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

#suffix

Used By

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,
  );
?>

#summary

Used By

details

Description

Summary information for a details element.

#tag

Used By

head_tag

Description

A form property used to specify a tag to be added to page HTML.

Usage Example

<?php
function _backdrop_default_html_head() {
  // Add default elements. Make sure the Content-Type comes first because the
  // IE browser may be vulnerable to XSS via encoding attacks from any content
  // that comes before this META tag, such as a TITLE tag.
  $elements['system_meta_content_type'] = array(
    '#type' => 'head_tag',
    '#tag' => 'meta',
    '#attributes' => array(
      'charset' => 'utf-8',
    ),
    // Security: This always has to be output first.
    '#weight' => -1000,
  );
  // Show Backdrop and the major version number in the META GENERATOR tag.
  // Get the major version.
  list($version, ) = explode('.', BACKDROP_VERSION);
  $elements['system_meta_generator'] = array(
    '#type' => 'head_tag',
    '#tag' => 'meta',
    '#attributes' => array(
      'name' => 'Generator',
      'content' => 'Backdrop CMS ' . $version . ' (https://backdropcms.org)',
    ),
  );
  // Also send the generator in the HTTP header.
  $elements['system_meta_generator']['#attached']['backdrop_add_http_header'][] = array('X-Generator', $elements['system_meta_generator']['#attributes']['content']);
  return $elements;
}
?>

#theme

Used By

Description

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

Values

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

Usage Example

<?php
  $data['actions']['output'][] = array(
    '#theme' => 'menu_local_action',
    '#link' => $item,
  );
?>

#theme_wrappers

Used By

actions, ajax, button, checkbox, checkboxes, color, container, contextual_links, date, details, dropbutton, email, fieldset, field_ui_table, file, form, head_tag, help, hidden, html_date, html_datetime, html_time, image_button, item, link, link_field, machine_name, managed_file, markup, number, operations, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, vertical_tabs, weight

Description

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

Values

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

Usage Example

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

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

#title

Used By

checkbox, checkboxes, color, date, email, fieldset, file, html_date, html_datetime, html_time, item, link, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, radios, range, search, select, tel, textarea, textfield, text_format, url, weight

Description

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

Values

Mixed.

Usage Example

(aggregator.module):

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

#title_display

Used By

ajax, button, checkbox, checkboxes, color, container, contextual_links, date, email, fieldset, field_ui_table, file, form, head_tag, html_date, html_datetime, html_time, image_button, item, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, weight

Description

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

Values

String.

Possible values:

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

Usage Example

(block.module):

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

#token_types

Used By

button, fieldset, head_tag, hidden, image_button, link, number, submit, token, value

Description

A list of token types included in a form element that may contain tokens within its '#value' property.

The form element should include '#element_validate' => array('token_element_validate') in its properties as in the example.

Usage Example

(user.admin.inc)

<?php
  $form['email_admin_created']['user_mail_register_admin_created_subject'] = array(
    '#type' => 'textfield',
    '#title' => t('Subject'),
    '#default_value' => $mail_config->get('register_admin_created_subject'),
    '#maxlength' => 180,
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('user'),
  );
?>

#tree

Used By

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

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

actions, button, checkbox, checkboxes, color, container, date, dropbutton, fieldset, file, form, head_tag, help, hidden, html_date, html_datetime, html_time, image_button, item, link, machine_name, managed_file, markup, operations, password, password_confirm, radio, radios, select, submit, tableselect, textarea, textfield, text_format, token, url, value, vertical_tabs, weight

Description

Used to determine the type of form element.

Values

Usage Example

(locale.module):

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

#upload_location

Used By

managed_file

Description

Location to upload a managed file to.

Values

NULL for the default, or a URI specifying the location.

Usage Example

(block.hero.inc)

<?php
  $form['image'] = array(
    '#type' => 'managed_file',
    '#title' => t('Background image'),
    '#description' => $upload_description,
    '#default_value' => $this->settings['image'],
    '#upload_location' => 'public://hero/',
    '#upload_validators' => $upload_validators,
    '#weight' => -10,
  );
?>

#upload_validators

Used By

managed_file

Description

A nested array of functions to validate uploaded files. See file_get_upload_validators() for the validator categories.

Usage Example

(file.pages.inc)

<?php
  $form['upload'] = array(
    '#type' => 'managed_file',
    '#title' => t('Upload a new file'),
    '#upload_location' => file_upload_destination_uri($options),
    '#upload_validators' => file_get_upload_validators($options),
    '#progress_indicator' => 'bar',
    '#pre_render' => array('file_managed_file_pre_render', 'file_upload_validators_pre_render'),
    '#default_value' => isset($form_state['storage']['upload']) ? $form_state['storage']['upload'] : NULL,
  );
?>

#validate

Used By

button, form, image_button, submit

Description

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

Values

An array of function names to be called to validate this form.

A validation function for a form takes $form and $form_state as parameters and should use form_set_error() if the form values do not pass validation. For example:

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

For the function name, you can use any valid PHP Callback, for example:

'#validate' => array('myelement_validate'), a function name;
'#validate' => array('CLASS::METHOD'), a static class method;
'#validate' => array(array('CLASS', 'METHOD')), another way of specifying a static class method;
'#validate' => array(array($my_object, 'METHOD')), a method of a class object;
'#validate' => array(array($this, 'METHOD')), a method of a class object, when this property is used within another method of the same class.

Usage Example