When should the "container" form element be used?

Question

The System module defines the container form element, but that form element is not documented in the Form API Reference.

When should that form element be used?

Answer 1

It looks like it can be used when you want to wrap a part of the form in a div, for example to be able to add some classes to it.

Some examples from core are the following:

• field_default_form()

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

• node_filter_form()

  $form['filters']['status'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('clearfix')),
    '#prefix' => ($i ? '<div class="additional-filters">' . t('and where') . '</div>' : ''),
  );
  $form['filters']['status']['filters'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('filters')),
  );
  

• search_form()

  $form['basic'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('container-inline')),
  );
  

Forms in Drupal 6 often used #prefix and #suffix on the first/last element to do this; this is a lot better because it is easier to add additional items or move them around.

I could use this in a few places in my own contributed modules, actually. ;)

Answer 2

In D6, there were often times when you would need to add a <div> around a FAPI element (for example with #ahah / #ajax), so container is a more consistent solution in regards to the Forms API to this common pattern than adding a wrapper div using #prefix/#suffix.