CHAPTER 11 ■ THE FORM API

Figure 11-10. The Board Room elements are displayed after selecting Board Room from the list of room types.

Using the approach just outlined, you have the ability to create a wide variety of forms that are easy to use and address one of the frequently requested features for online surveys.

Form API Properties

When building a form definition in your form building function, array keys are used to specify information about the form. The most common keys are listed in the following sections. Some keys are added automatically by the form builder.

Properties for the Root of the Form

The properties in the following sections are specific to the form root. In other words, you can set $form['#programmed'] = TRUE, but setting $form['myfieldset']['mytextfield'][#programmed'] = TRUE will not make sense to the form builder.

#action

The path to which the form will be submitted.

273

CHAPTER 11 ■ THE FORM API

#built

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

#method

The HTTP method with which the form will be submitted.

Properties Added to All Elements

When the form builder goes through the form definition, it ensures that each element has some default values set. The default values are set in _element_info() in includes/form.inc but can be overridden by an element’s definition in hook_elements().

#description

This string property is added to all elements and defaults to NULL. It’s rendered by the element’s theme function. For example, a text field’s description is rendered underneath the text field, as shown in Figure 11-2.

#attributes

Additional HTML attributes, such as “class” can be set using this mechanism. The following example sets the CSS class of the form to “search-form”.

<?php

$form[‘#attributes’] = array(‘class’ => ‘search-form’); ?>

#required

This Boolean property is added to all elements and defaults to FALSE. Setting this to TRUE will cause Drupal’s built-in form validation to throw an error if the form is submitted but the field has not been completed. Also, if set to TRUE, a CSS class is set for this element (see theme_form_element() in includes/form.inc).

#tree

This Boolean property is added to all elements and defaults to FALSE. If set to TRUE, the $form_state['values'] array resulting from a form submission will not be flattened. This affects how you access submitted values (see the “Fieldsets” section of this chapter).

274

CHAPTER 11 ■ THE FORM API

Properties Allowed in All Elements

The properties explained in the sections that follow are allowed in all elements.

#type

This string declares the type of an element. For example, #type = 'textfield'. The root of the form must contain the declaration #type = 'form'.

#access

This Boolean property determines whether the element is shown to the user. If the element has children, the children will not be shown if the parent’s #access property is FALSE. For example, if the element is a fieldset, none of the fields included in the fieldset will be shown if #access is FALSE.

The #access property can be set to TRUE or FALSE directly, or the value can be set to a function that returns TRUE or FALSE when executed. Execution will happen when the form definition is retrieved. Here’s an example from Drupal’s default node form:

$form['revision_information']['revision'] = array( '#access' => user_access('administer nodes'), '#type' => 'checkbox',

'#title' => t('Create new revision'), '#default_value' => $node->revision,

);

#after_build

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

#array_parents

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.

#attached

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.

#default_value

The type for this property is mixed. For input elements, this is the value to use in the field if the form has not yet been submitted. Do not confuse this with the #value element, which defines an internal form value that is never given to the user but is defined in the form and appears in $form_state['values'].

275

CHAPTER 11 ■ THE FORM API

#disabled

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

#element_validate

A list of custom validation functions that need to be passed.

#parents

This array property is added to all elements and defaults to an empty array. It is used internally by the form builder to identify parent elements of the form tree. For more information, see http://drupal.org/node/48643.

#post_render

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

#prefix

The string defined in this property will be added to the output when the element is rendered, just before the rendered element.

#pre_render

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

#process

This property is an associative array. Each array entry consists of a function name as a key and any arguments that need to be passed as the values. These functions are called when an element is being built and allow additional manipulation of the element at form building time. For example, in modules/system/system.module where the checkboxes type is defined, the function form_process_checkboxes() in includes/form.inc is set to be called during form building:

$type['checkboxes'] = array( '#input' => TRUE,

'#process' => array('form_process_checkboxes'),

);

276