Elements

If you are familiar with the Drupal forms API you know the concept of form elements as the basic building blocks of any form. Drupal provides several types of elements, some rather straightforward (#type textfield), some more advanced (#type password_confirm).

It is also possible to define custom form elements that enable you to implement complex widgets with ease.

At the moment, the focus of Elements is the tableselect widget. It provides a clean, easy way to create tables with one checkbox per row, multi-row selection and a select all checkbox, without making your code a complicated mess.

Example scaffolding

You can use the following code to create an example.module which you can use to experiment with the examples in this guide.

  1. // example.module
  2. function example_menu($maycache) {
  3.   if ($maycache) {
  4.     $items[] = array(
  5.       'path' => 'scratch/elements',
  6.       'access' => user_access('administer site configuration'),
  7.       'type' => MENU_NORMAL_ITEM,
  8.       'title' => t('Elements'),
  9.       'callback' => 'drupal_get_form',
  10.       'callback arguments' => array('example_elements_form'),
  11.     );
  12.     return $items;
  13.   }
  14. }

  1. ; example.info
  2. name = "Example"
  3. description = "Quick scratch module."

Comboselect element

The comboselect element has not yet been included in Elements. You can follow its development at #268424.

The comboselect written by John Morahan gives you a select type element with an 'Other' option. When the user chooses this option; a textfield appears.

Create a simple comboselect element

  1. function example_elements_form() {
  2.   $form = array();
  3.  
  4.   $options = array(
  5.     'one' => t('First Option'),
  6.     'two' => t('Second Option'),
  7.   );
  8.  
  9.   $form['choice'] = array(
  10.     '#type' => 'comboselect',    
  11.     '#title' => t('Example'),
  12.     '#default_options' => $options,
  13.   );
  14.  
  15.   $form['submit'] = array(
  16.     '#type' => 'submit',
  17.     '#value' => t('Submit'),
  18.   );
  19.  
  20.   return $form;
  21. }


Change the 'Other' option

  1. function example_elements_form() {
  2.   $form = array();
  3.  
  4.   $options = array(
  5.     'one' => t('First Option'),
  6.     'two' => t('Second Option'),
  7.   );
  8.  
  9.   $form['test'] = array(
  10.     '#type' => 'comboselect',    
  11.     '#title' => t('Example'),
  12.     '#required' => TRUE,
  13.     '#default_options' => $options,
  14.     '#other' => t('None of the above, but'),
  15.   );
  16.  
  17.   $form['submit'] = array(
  18.     '#type' => 'submit',
  19.     '#value' => t('Submit'),
  20.   );
  21.  
  22.   return $form;
  23. }

Tableselect element

The form element tableselect provides a clean, easy way to create tables with one checkbox per row, multi-row selection and a select all checkbox, without making your code a complicated mess:

A simple table

The basic properties of the tableselect element are #header which accepts an array of key => value pairs to generate the header from and #options, which receives an array of rows.

The basic structure looks like the following:

$header = array(
  'field1' => 'Title of field 1',
  'field2' => 'Title of field 2',
);

$options['some_unique_id'] = array(
  'field1' => 'Value of field 1',
  'field2' => 'Value of field 2',
);

The tableselect element relies on the keys to match columns with the appropriate header. The element will behave like the #checkboxes type. You'll get an array of values in your submit function, with the checked ones set to nonzero so you can array_filter them to get the checked rows.

function example_elements_form() {
  $form = array();

  $header = array(
    'title' => t('Title'),
    'author' => t('Author'),
  );

  $query = "SELECT n.nid, n.title, u.name FROM {node} n INNER JOIN {users} u ON n.uid = u.uid";
  $result = pager_query(db_rewrite_sql($query));

  while($partial_node = db_fetch_object($result)) {
    $options[$partial_node->nid] = array(
      'title' => check_plain($partial_node->title),
      'author' => check_plain($partial_node->name),
    );
  }

  if (!empty($options)) {
    $form['nodes'] = array(
      '#type' => 'tableselect',
      '#header' => $header,
      '#options' => $options,
    );

    $form['pager'] = array('#value' => theme('pager'));

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

  }
  return $form;
}

Which results in:

Example table

Support for sortable tables

The tableselect element supports use with tablesort_sql. Simply modify the header to the format described in theme_table.

function example_elements_form() {
  $form = array();

  $header = array(
    'title' => array('field' => 'n.title', 'data' => t('Title')),
    'author' => array('field' => 'u.name', 'data' => t('Author')),
  );

  $query = "SELECT n.nid, n.title, u.name FROM {node} n INNER JOIN {users} u ON n.uid = u.uid". tablesort_sql($header);

  $result = pager_query(db_rewrite_sql($query));

  while($partial_node = db_fetch_object($result)) {
    $options[$partial_node->nid] = array(
      'title' => check_plain($partial_node->title),
      'author' => theme('username', $partial_node),
    );
  }

  if (!empty($options)) {
    $form['nodes'] = array(
      '#type' => 'tableselect',
      '#header' => $header,
      '#options' => $options,
    );

    $form['pager'] = array('#value' => theme('pager'));

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

  }

  return $form;
}

Properties

#header
The table header, an array of field_key => title pairs or the format described for theme_table.
#options
The data displayed in the table. Nested array of id => array pairs where the array is an array of field_key => value pairs.
#multiple
Determines whether multiple values can be selected. Displays checkboxes when TRUE, radios when FALSE.
Default: TRUE
#advanced_select
Whether to provide advanced selection behaviour (SELECT ALL checkbox, SHIFT-select).
Default: TRUE - when #multiple is TRUE.
When #multiple is FALSE, always FALSE.
#default_value
Provide an array of id => x pairs for the ids that should be selected by default when #multiple is TRUE.
Provide the id as a scalar for the id that should be selected by default when #multiple is FALSE.