Drupal 7 Views 3.0 Tutorial

Drupal 7 Views 3.0 Tutorial

The Drupal forms API is a powerful leap forward. It also allows for almost unlimited possibilities for custom theming, validation, and execution of forms. Even better, ANY form (even those in core) can be altered in almost any way imaginable--elements can be removed, added, and rearranged. This page is certainly not a comprehensive guide to this functionality, but should provide a good working foundation with which to do the most basic form creation, theming, validation, and execution. For programming details on form elements and their properties, please see the Forms API Reference.

Creating Forms

Form elements are now declared in array fashion, with the hierarchical structure of the form elements themselves as array elements (which can be nested), and each form elements properties/attributes listed as array elements in key/value pairs--the key being the name of the property/attribute, and the value being the value of the property/attribute. For example, here's how to go about constructing a textfield form element:

$form['foo'] = array(
  '#type' => 'textfield', 
  '#title' => t('bar'),
  '#default_value' => $object['foo'],
  '#size' => 60,
  '#maxlength' => 64, 
  '#description' => t('baz'),
);
?>

and a submit button:

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

a few things to note:

1. The element's name property is declared in the $form array, at the very end of the array tree. For example, if an element in the form tree was structured like this:
   
   
   $form['account_settings']['username']
?>
   
   ...then that element's name property is 'username'--this is the key it will be available under in$form_state['values'], in your validation and submission functions, as the form code flattens the array in this fashion before it passes the key/value pairs. NOTE: if you wish to have the full tree structure passed to $form_state['values'], this is possible, and will be discussed later.
2. The type of form element is declared as an attribute with the '#type' property.
3. Properties/attributes keys are declared with surrounding quotes, beginning with a # sign. Values are strings.
4. The order of the properties/attributes doesn't matter, and any attributes that you don't need don't need to be declared. Many properties/attributes also have a default fallback value if not explicitly declared.
5. Don't use the '#value' attribute for any form elements that can be changed by the user. Use the '#default_value' attribute instead. Don't put values from $form_state['values'](or $_POST) here! FormsAPI will deal with that for you; only put the original value of the field here.

One great advantages of this system is that the explicitly named keys make deciphering the form element much easier.
Let's take a look at a working piece of code using the API:

function test_form($form_state) {
  // Access log settings:
  $options = array('1' => t('Enabled'), '0' => t('Disabled'));
  $form['access'] = array(
    '#type' => 'fieldset', 
    '#title' => t('Access log settings'), 
    '#tree' => TRUE,
  );
  $form['access']['log'] = array(
    '#type' => 'radios', 
    '#title' => t('Log'), 
    '#default_value' =>  variable_get('log', 0), 
    '#options' => $options, 
    '#description' => t('The log.'),
  );
  $period = drupal_map_assoc(array(3600, 10800, 21600, 32400, 43200,86400, 172800, 259200, 604800, 1209600, 2419200, 4838400, 9676800),'format_interval');
  $form['access']['timer'] = array(
    '#type' => 'select', 
    '#title' => t('Discard logs older than'), 
    '#default_value' => variable_get('timer', 259200), 
    '#options' => $period, 
    '#description' => t('The timer.'),
  );
  // Description
  $form['details'] = array(
    '#type' => 'fieldset', 
    '#title' => t('Details'), 
    '#collapsible' => TRUE, 
    '#collapsed' => TRUE,
  );
  $form['details']['description'] = array(
    '#type' => 'textarea', 
    '#title' => t('Describe it'), 
    '#default_value' =>  variable_get('description', ''), 
    '#cols' => 60, 
    '#rows' => 5, 
    '#description' => t('Log description.'),
  );
  $form['details']['admin'] = array(
    '#type' => 'checkbox', 
    '#title' => t('Only admin can view'), 
    '#default_value' => variable_get('admin', 0),
  );
  $form['name'] = array(
    '#type' => 'textfield', 
    '#title' => t('Name'), 
    '#size' => 30, 
    '#maxlength' => 64, 
    '#description' => t('Enter the name for this group of settings'),
  );
  $form['hidden'] = array('#type' => 'value', '#value' => 'is_it_here');
  $form['submit'] = array('#type' => 'submit', '#value' => t('Save'));
  return $form;
}

function test_page() {
  return drupal_get_form('test_form');
}
?>

--