Form API Properties [The Form API]

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.

#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

setfor 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).

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 field set

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

$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 isdefined in the form and  appears in $form_state['values'].

#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 atform 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'),);

#states

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

#suffix

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

#theme

This optional property defines a string that will be used when Drupal looks for a theme function for this element. For

example, setting #theme = 'foo' will cause Drupal to check the theme registry for an entry that corresponds with foo.

See the “Finding a ThemeFunction for the Form”  section earlier in this chapter.

#theme_wrappers

Theme function to call for the element, after the element and  children are rendered, but before the

#post_render  functions are called.

#title

This string is the title of the element.

#tree

Used to allow collections of form elements. Normally applied to the "parent" element, as the #tree

property cascades to sub-elements.

#weight

This property can be an integer or a decimal number. When  form elements are rendered, they are sorted by their weight. Those  with smaller weights “float up” and  appear higher; those with larger  weights “sink down” and  appear lower on the rendered page.

Form  Elements

In this section, we’ll present examples of the built-in Drupal form elements.

Text Field

An example of a text field element follows:

$form['pet_name'] = array( '#title' => t('Name'), '#type' => 'textfield', '#description' => t('Enter the  name of  your  pet.'), '#default_value' => $user->pet_name,'#maxlength' => 32, '#required' => TRUE, '#size' => 15,'#weight' => 5,

'#autocomplete_path' => 'pet/common_pet_names',);

$form['pet_weight'] = array( '#title' => t('Weight'), '#type' => 'textfield',

'#description' => t('Enter the  weight  of  your  pet  in  kilograms.'), '#field_suffix' => t('kilograms'),

'#default_value' => $user->pet_weight,'#size' => 4, '#weight' => 10,);

This results in the form element shown in Figure  11-11.

Figure 11-11. The text field element

The #field_prefix and  #field_suffix properties are specific to text fields and  place  a string immediately before or after the text

field input. The #autocomplete property defines a path where Drupal’s automatically included JavaScript will send HTTP requests using jQuery. In the preceding example, it will query http://example.com/?q=pet/common_pet_names.

See the user_autocomplete() function in modules/user/user.pages.inc for a working example.

Properties commonly used with the text field element follow: #attributes, #autocomplete_path (the default is FALSE), #default_

value, #description,  #field_prefix, #field_suffix, #maxlength (the default is 128), #prefix, #required, #size (the default is60), 

#suffix, #title, #process (the default is array('ajax_process_form')), and  #weight.

Password

This element creates an HTML password field, where input entered by the user is not shown (usually bullet characters are echoed

to the screen instead). An example from user_login_block() follows:

$form['pass'] = array('#type' => 'password', '#title' => t('Password'),'#maxlength' => 60, '#size' => 15, '#required' =>

TRUE,);

Properties commonly used with the password element are #attributes, #description, #maxlength, #prefix, #required,  #size

(the default is 60),  #suffix, #title, #process (the default is array('ajax_ process_form')), and  #weight. The #default_

value property is not used with the password element for security reasons.

Password with Confirmation

This element creates two HTML password fields and  attaches a validator that checks if the two passwords match. For

example, this element is used by the user module when a user changes his or her password.

$form['account']['pass'] = array( '#type' => 'password_confirm', '#description' =>

t('To change  the  current   user  password,  enter   the  new password in  both  fields.'), '#size' => 25,);

Textarea

An example of the textarea element follows:

$form['pet_habits'] = array( '#title' => t('Habits'), '#type' => 'textarea',

'#description'  => t('Describe  the  habits  of  your pet.'), '#default_value'  => $user->pet_habits,

'#cols'  => 40, '#rows'  => 3, '#resizable'  =>  FALSE, '#weight'  =>  15,);

Properties commonly used with the textarea element are #attributes,  #cols (the default is 60),

#default_value, #description, #prefix, #required, #resizable, #suffix, #title, #rows (the default is 5),

#process (the default is array('ajax_process_form')), and  #weight.

The #cols setting may not be effective  if the dynamic textarea resizer is enabled by setting #resizable to TRUE.

Select

A select  element example from modules/statistics/statistics.admin.inc follows:

$period  = drupal_map_assoc(array(3600,  10800,  21600,  32400,  43200,  86400,  172800, 259200,  604800,  1209600,  2419200,  4838400,  9676800),  'format_interval');

/*  Period  now  looks  like  this: Array  ([3600]  => 1  hour [10800]  => 3  hours [21600]  => 6  hours [32400]  => 9  hours[43200]  => 12  hours [86400]  => 1  day [172800]  => 2  days [259200]  => 3  days [604800]  => 1  week [1209600]  => 2  weeks [2419200]  => 4  weeks [4838400]  => 8 weeks [9676800]  => 16  weeks  )

*/

$form['access']['statistics_flush_accesslog_timer']  = array( '#type'  => 'select',

'#title'  => t('Discard  access logs  older  than'),

'#default_value'  => variable_get('statistics_flush_accesslog_timer',  259200), '#options'  => $period,

'#description'  => t('Older  access log  entries  (including  referrer  statistics) will  be automatically  discarded.  (Requires  a  correctly  configured

<a href="@cron">cron  maintenance  task</a>.)',  array('@cron'  => url('admin/reports/status'))),);

Drupal supports grouping in the selection options by defining the #options property to be an associative array of submenuchoices, as shown in Figure  11-12.

$options = array( array(t('Healthy') => array(1  => t('wagging'),2  => t('upright'),3  => t('no tail')),), array(

t('Unhealthy') => array(4  => t('bleeding'),5  => t('oozing'),),),);

$form['pet_tail'] = array( '#title' => t('Tail demeanor'),

'#type' => 'select','#description' => t('Pick the  closest match that   describes the  tail of  your  pet.'),

'#options' => $options, '#multiple' => FALSE, '#weight' => 20,);

Figure 11-12. A select element using choice grouping

Selection of multiple choices is enabled by setting the #multiple property to TRUE. This also changes the value in $form_state['values'] from a string (e.g., 'pet_tail' = '2', assuming upright is selected in the preceding example) to an array of values (e.g.,pet_tail = array(   1  => '1', 2  => '2') assuming wagging and  upright are both chosen in the preceding

example). Properties commonly used with the select  element are #attributes, #default_value, #description, #multiple, #options, #prefix, #required, #suffix, #title, #process (the default is array('form_ process_select',

'ajax_process_form')), and  #weight.

Radio Buttons

A radio button example from modules/block/block.admin.inc follows:

$form['user_vis_settings']['custom'] = array( '#type' => 'radios',

'#title' => t('Custom  visibility settings'), '#options' => array(

t('Users  cannot  control whether  or  not  they  see  this block.'), t('Show  this block  by default, but  let  individual users   hide  it.'),t('Hide  this block  by default but  let  individual users   show it.')),

'#description' => t('Allow individual users   to  customize   the  visibility  of this block  in  their account  settings.'),'#default_value' => $edit['custom'],);

Properties commonly used with this element are #attributes, #default_value, #description,#options, #prefix, #required,#suffix, #title, and  #weight. Note that the #process property is set to array('form_process_radios') (see includes/form.inc) by default.

Check Boxes

An example of the check boxes element follows. The rendered version of this element is shown in Figure 11-13.

$options = array('poison' => t('Sprays deadly  poison'), 'metal' => t('Can   bite/claw through  metal'), 'deadly' => t('Killed  previous owner')  );$form['danger'] = array('#title' => t('Special conditions'), '#type' =>

'checkboxes','#description' => (t('Please note  if any of  these conditions apply  to  your pet.')),

'#options' => $options, '#weight' => 25,);

Figure 11-13. An example using the check boxes element

The array_filter() function is often used in validation and  submission functions to get the keys of the checked boxes. Forexample, if the first two check boxes are checked in Figure  11-13, 

$form_state['values']['danger'] would contain the following:

array('poison' => 'poison', 'metal' => 'metal', deadly' => 0,)

Running array_filter($form_state['values']['danger']) results in an array containing only the keys of the checked boxes: array('poison', 'metal').

Properties commonly used with the check boxes element are #attributes, #default_value,

#description, #options, #prefix, #required, #suffix, #title, #tree (the default is TRUE), and  #weight.

Note that the #process property is set to form_process_checkboxes() (see includes/form.inc) by default.

Value

The value element is used to pass values internally from $form to $form_state['values'] without ever being sent  to the browser, for example:

$form['pid'] = array( '#type' => 'value', '#value' => 123,);

When  the form is submitted, $form_state['values']['pid'] will be 123.

Do not confuse #type  => 'value' and  #value  => 123. The first declares what  kind of element is being described, and  the

second declares the value of the element. Only #type and  #value properties may be used with the value element.

Hidden

This element is used to pass a hidden value into a form using  an HTML input field of type hidden, as in the following example.

$form['my_hidden_field'] = array( '#type' => 'hidden','#value' => t('I am  a  hidden  field value'),);

If you want  to send a hidden value along  through the form,  it’s usually a better idea to use the value element for this, and  use

the hidden element only when the value element does not suffice. That’s because the user can view the hidden element in the

HTML source of a web form, but the value element is internal to Drupal and  not included in the HTML. Only the #prefix,

 #suffix, #process (the default is array('ajax_process_form')), and  #value properties are used with the hidden element.

Date

The date  element, as shown in Figure  11-14, is a combination element with three select  boxes:

$form['deadline'] = array( '#title' => t('Deadline'), '#type' => 'date','#description' => t('Set the  deadline.'), '#default_

value' => array('month'  => format_date(time(), 'custom',  'n'), 'day' => format_date(time(), 'custom',  'j'), 'year' => format_date(time(), 'custom',  'Y'),),);

Figure 11-14. A date element

 Properties commonly used by the date  element are #attributes, #default_value, #description, #prefix, #required, #suffix, #title, 

and  #weight. The #process property defaults to call array('form_process_date'), in which the year selector is hard-coded to the

years 1900 through 2050. The #element_validate property defaults to date_validate() (bothfunctions can be found in includes/

form.inc). You can define these properties when defining the date  element in your form to use your own code  instead.

Weight

The weight  element (not  to be confused with the #weight property) is a drop-down used to specify weights:

$form['weight'] = array( '#type' => 'weight', '#title' => t('Weight'), '#default_value' => 0, '#delta' => 10,

'#description' => t('In listings, the  heavier vocabularies will  sink  and the lighter  vocabularies will  be  positioned nearer  the  top.'),);

The preceding code  will be rendered as shown in Figure  11-15.

Figure 11-15. The weight element

The #delta property determines the range of weights to choose from and  defaults to 10. For example, if you set #delta to 50, the

range of weights would be from -50 to 50. Properties commonly used with the weight element are #attributes, #delta (the default is 10), #default_value, #description, #prefix, #required,  #suffix, #title, and  #weight. The #process property defaults to array('form_ process_weight', 'ajax_process_form'). 

File Upload

The file element creates a file upload interface. Here’s an example from modules/user/user.module:

$form['picture']['picture_upload'] = array( '#type' => 'file', '#title' => t('Upload picture'), '#size' => 48,

'#description' => t('Your virtual  face   or  picture.'));

The way this element is rendered is shown in Figure  11-16.

Figure 11-16. A file upload element

Note that if you use the file element, you’ll need to set the enctype property at the root of your form:

$form['#attributes']['enctype'] = 'multipart/form-data';

Properties commonly used with the file element are #attributes, #default_value, #description, #prefix, #required,  #size (the

default is 60), #suffix, #title, and  #weight.

Fieldset

A fieldset element is used to group elements together. It can be declared collapsible, which means JavaScript automatically provided byDrupal is used to open and  close the fieldset dynamically with a click while a user is viewing the form. Note the use of the

#access property in this example to allow or deny  access to all fields within the fieldset:

// Node author  information for  administrators.

$form['author'] = array( '#type' => 'fieldset','#access' => user_access('administer nodes'), '#title' =>

t('Authoring information'), '#collapsible' => TRUE,'#collapsed' => TRUE,'#weight' => 20,);

Properties commonly used with the fieldset element are #attributes, #collapsed (the default is FALSE), #collapsible (the default is

FALSE), #description, #prefix, #suffix, #title, #process (the default is array('form_process_fieldset','ajax_process_form')), and  #weight.

Submit

The submit element is used to submit the form. The word displayed inside the button defaults to “Submit” but can be changed using the #value property:

$form['submit'] = array( '#type' => 'submit', '#value' => t('Continue'),);

Properties commonly used with the submit element are #attributes, #button_type (the default is “submit”), #executes_submit_callback (the default is TRUE), #name (the default is “op”), #prefix, #suffix, #value, #process (the default is array('ajax_process_

form')), and  #weight. Additionally, the #validate and  #submit properties may be assigned directly to the submit element. For

example, if #submit is set to array('my_special_form_submit'), the function my_special_form_submit() will be used instead of

the form’s definedsubmit handler(s).

Button

The button element is the same as the submit element except that the #executes_submit_callback property defaults to FALSE. This property tells Drupal whether to process the form (when TRUE) or simply re-render the form (if FALSE). Like the Submitbutton,

specific validation and  submit functions can be assigned directly to a button. 

Image Button

The image button element is the same as the submit element with two exceptions. First, it has a #src property that has the URL of

an image as its value. Secondly, it sets the internal form property #has_garbage_value to TRUE, which prevents #default_value

from being used due to a bug in Microsoft Internet Explorer. Do not use #default_value with image buttons. Here is an image

button that uses the built-in Powered by Drupal image as the button:

$form['my_image_button'] = array( '#type' => 'image_button', '#src' => 'misc/powered-blue-80x15.png','#value' => 'foo',);

The value of the button can be safely retrieved by looking in $form_state['clicked_button']['#value'].

Markup

The markup element is the default element type if no #type property has been used. It is used to introduce text or HTML into the middle of a form.

$form['disclaimer'] = array( '#prefix' => '<div>', '#markup' => t('The  information below  is entirely optional.'),

'#suffix' => '</div>',);

Properties commonly used with the markup element are #attributes, #prefix (the default is the empty string ''), #suffix (the default is the empty string ''), #value, and  #weight.

Item

The item  element is formatted in the same way as other input element types  like text element or select element, but it lacks the

input field.

$form['removed'] = array( '#title' => t('Shoe size'), '#type' => 'item', '#description' => t('This  question has  been  removedbecause  the  law  prohibits  us from asking  your  shoe  size.'),);

The preceding element is rendered as shown in Figure  11-17.

Figure 11-17. An item element

 Properties commonly used with the item  element are #attributes, #description, #prefix (the default is an empty string, ''), 

#required, #suffix (the default is an empty string, ''),  #title, #value, and #weight.

#ajax Property

AJAX-enabled forms  in Drupal provide the ability to dynamically modify forms as a user interacts with the elements on the form.

A common example is to update the list of items in a select  list based on some value that the user selected or entered in aprevious

field – for example, select  an automobile manufacturer from a select  list changes the list of available models based on the value

selected by the user.  While you can perform that action without AJAX, its nice to not force the user  to sit through a pagereload

the form populates the values  in the second drop down list.  AJAX provides the means for performing that update without having to reload the whole  page,  only the part  that needs to be changed. The benefits of using the Form  API’s AJAX capbilitiesinclude:

•     AJAX forms provide dynamic form behavior without forcing  the user  to sit through one or more page reloads while the form updates an element.

•     You as the developer don't have to code  Javascript to create an AJAX-enabled form. The Form  API does 

all of the heavy lifting for you.

•     AJAX forms  are often simpler than multistep forms.

The process for creating an AJAX-enabled form is relatively simple:

Create or update an existing form element and  mark  it as AJAX-enabled by using the #ajax property.

Form  elements marked as AJAX-enabled trigger  a background AJAX call when the user change it or clicks on it.

The #ajax['wrapper'] property includes the HTML ID of a page section that will be modified when the Ajax call is executed. The

#ajax['callback'] indicates which callback should be executed after the AJAX call happens and  the form is rebuilt.

 Second, create a callback function using the name of the callback listed  in #ajax['callback']. This function’s primary typically

updates the content of the HTML ID identified in the #ajax[‘wrapper’].

The following example demonstrates the use of Ajax by creating a form with two select  lists, one for automobile manufacturer and the second for the models offered by that manufacturer. When  a user selects a manufacturer from the list, the second select list is

automatically updated with the list of models that are offered by the manufacturer that was selected by the user. The second select

list is updated through Ajax without having to reload the page.   Only that section of the page that contains the model select  list is

updated.

 /**

*   A  form with  a  dropdown  whose options are  dependent  on a

*   choice made in  a  previous dropdown.

*

*   On  changing  the  first dropdown, the  options in  the  second

*   are  updated.

*/

function automobile_dependent_dropdown($form,  &$form_state)  {

// get  the  list of  manufacturers  to  populate   the  manuacturer dropdown

$options_first = _automobile_get_manufacturer_dropdown_options();

// if we have  a  value  for  the  manufacturer  dropdown  from

// $form_state['values'] we use  this both  as  the  default value  for

// the  first dropdown  and also as  a  parameter  to  pass  to  the

// function that   retrieves the  options for  the  second  dropdown.

$selected = isset($form_state['values']['manufacturer_dropdown']) ?

$form_state['values']['manufacturer_dropdown'] : key($options_first);

$form['manufacturer_dropdown']   = array( '#type' => 'select',

'#title' => 'Manufacturer', '#options' => $options_first, '#default_value' => $selected,

// bind  an ajax  callback to  the  change  event  (which  is the  default for  the

// select form type) of  the  manufacturer  dropdown. It  will replace the

// model dropdown  when rebuilt '#ajax' => array(

'callback' => 'automobile_dependent_dropdown_callback', 'wrapper'   => 'dropdown_model_replace',

),

);

$form['model_dropdown']  = array( '#type' => 'select',

'#title' => 'Model',

// The entire enclosing div  created here  gets  replaced when manufacturer_dropdown

// is changed.

'#prefix' => '<div  id="dropdown_model_replace">', '#suffix' => '</div>',

// when the  form is rebuilt during  ajax  processing, the  $selected  variable

// will now have  the  new value  and so  the  models  will change '#options' => _automobile_get_model_dropdown_options($selected), '#default_value' => isset($form_state['values']['model_dropdown']) ?$form_state['values']['model_dropdown']  : '',

);

$form['submit']  = array( '#type'  => 'submit', '#value'  => t('Submit'),

);

return  $form;

}

if (isset($options[$key])) { return  $options[$key];

}

else {

return  array();

}

}

The general processing performed by the code  above:

1.       Presents the form to the user,  as any form would be.

2.       In the form, a div with an HTML ID of ' dropdown_model_replace ' wraps

$form['model_dropdown']  . This is done with $form['model_dropdown'] ['#prefix'] and  $form['model_dropdown']  ['#suffix'].

3.       When  the user changes $form['manufacturer_dropdown']   a background request is made to the server,  causing the form to be rebuilt.

4.       The form is rebuilt and  the values for model are reset based on the value selected in the $form[‘model_dropdown’]

5.       The function   automobile_dependent_dropdown_callback() is called.  It selects the piece  of the form which is to be replaced on the page (almost always the same as what's in #ajax['wrapper']).

6.       The portion returned is rendered, sent  back to the page,  and  the div with id ‘dropdown_model_replace’ is replaced on the page.

/**

*   Selects  just  the  model  dropdown  to  be returned  for  re-rendering

*

*   The  version  here  has been re-loaded  with  a  different  set of  options  and

*   is sent  back to  the  page to  be updated.

*

*   @return  renderable  array  (the  second dropdown)

*/

function  automobile_dependent_dropdown_callback($form,  $form_state)  { return  $form['model_dropdown'];

}

/**

*   Helper  function  to  populate  the  manufacturer  dropdown.  This  would  normally  be

*   pulling  data  from  the  database.

*

*   @return  array  of  options

*/

function  _automobile_get_manufacturer_dropdown_options()  {

// drupal_map_assoc()  just  makes  an array('Strings'  => 'Strings'...).

return  drupal_map_assoc(array(t('Honda'),  t('Toyota'),  t('Ford'),  t('Volkswagen')));

}

/**

*   Helper  function  to  populate  the  model  dropdown.  This  would  normally  be

*   pulling  data  from  the  database.

*

*   @param  key.  This  will  determine  which  set of  options  is returned.

*

*   @return  array  of  options

*/

function  _automobile_get_model_dropdown_options($key  = '') {

$options  = array(

t('Honda')  => drupal_map_assoc(array(t('Accord'),  t('Civic'),  t('CRX'),  t('Pilot'))), t('Toyota')  => drupal_map_assoc(array(t('Camry'),  t('Yaris'),  t('Tundra'),

t('Tacoma'))),

t('Ford')  => drupal_map_assoc(array(t('F-150'),  t('Explorer'),  t('Escape'),  t('Edge'))), t('Volkswagen')  => drupal_map_assoc(array(t('GTI'),  t('Passat'),  t('Jeta'),  t('Polo'))),

);

Remember that the $form  you're dealing with in your callback function has already been sent through all the form processing functions (but hasn't yet been sent to drupal_render()). So while adjusting, say, themarkup of an element is straightforward:

<?php

$elements['some_element']['#markup'] = 'New markup.'; return  $elements;

?>

Changing a value that has already been converted into the #attributes property means digging deeper into the $form  array, as well as also changing that element's corresponding property.

<?php

// You need  to  do both

$elements['some_element']['#disabled'] = TRUE;

$elements['some_element']['#attributes']['disabled'] = 'disabled'; return  $elements;

?>

If Javascript is not supported

Best practices call for providing a graceful for degrading behavior when the users browser does not support Javascript.  AJAX forms provide the ability to address this, but it may take considerable effort to make a form behave correctly in either a Javascript ornon-javascript environment. In most cases you must provide alternative means for navigating, such as a "next" button for the AJAX-enabled element. When  it is pressed, the page (and form) are rebuilt emulating the same functionality when the AJAX- enabledelement is changed, but with a page reload. The Examples module provides several examples of AJAX with graceful degradation in ajax_example_graceful_degradation.inc:

•     An add-more button

•     A dependent dropdown example

•     Dynamic sections

•     Wizard (classic  multistep form)

Additional AJAX features

The AJAX Framework provides many additional features and  options in beyond basic forms behavior.

•     AJAX Framework Commands may be used on the server  side to generate dynamic behaviors on the page.  The #ajax['callback'] function may return an array of commands instead of returning a renderable array or an HTML string. Thisprovides the ablity to create dynamic functions that extend beyond simple Form API operations.

•     The #ajax['callback'] does  not have to return a portion of the form. It can return any renderable array,  or it can return an HTML string.

•     The replace method is the default and  most common, but it is also possible to do other things with the content returned by the #ajax['callback'], including prepending, appending, etc.

•     If you want  to replace ajax_form_callback() with your own functions, use ajax_form_callback() would be the model for your replacement. In that case, you would change #ajax['path'] from the default 'system/ajax' and  set up a menu entryin hook_menu() to point to your replacement path.

Additional resources

•     The Examples module (http://drupal.org/project/examples) provides more examples, including an AJAX-enabled dependent dropdown, and  several other examples, including an example of graceful degradation when Javascript is notenabled.

•     See the AJAX Framework (http://api.drupal.org/api/group/ajax/7) documentation and  the Form  API Reference

Summary

After reading this chapter, you should understand the following concepts:

•     How the form API works.

•     Creating simple forms.

•     Changing the rendered form using theme functions.

•     Writing  a validation function for a form or for individual elements.

•     Writing  a submit function and  doing redirection after form processing.

•     Altering existing forms.

•     Creating dynamic forms.

•     Using the #ajax property to create dynamic forms  that react to users input without page reloads

•     The form definition properties you can use and  what  they mean.

•     The form elements (text fields, select  fields, radios, and  so on) thatre available in Drupal.

•     How AJ-based  text replacement works with forms.

For more information about forms, including tips and  tricks, see the Drupal Handbook at

http://drupal.org/node/37775.