Building Field Groups in Drupal 7


A common requirement when building forms in Drupal is the ability to group fields together. Drupal 7 offers tools out of the box, as well as some contributed modules, each with their own set of pros and cons depending on the end goal of the project.


Fieldset comes out of the box with Drupal core, and provides a way to group fields into collapsible sets. Fieldset does require basic knowledge of the Form API to use, as it does not provide an administrative interface. All forms in Drupal are represented as a structured array, which you can learn more about here. To build a fieldset into a form, we’ll first create the fieldset element:

[prism:php] $form['contact'] = array( '#type' => 'fieldset', '#title' => t('Contact settings'), '#weight' => 5, '#collapsible' => TRUE, '#collapsed' => FALSE, ); [/prism:php]

Any elements you nest under the ‘contact’ key will be displayed in that fieldset.

[prism:php] $form[‘contact’][‘first_name’] = array( ‘#type’ => ‘textfield’, ‘#title’ => t(‘First Name’), ‘#default_value’ => ‘’, ‘#size’ => 60, ‘#maxlength’ => 128, ‘#required’ => TRUE ); [/prism:php]


Similar to Fieldsets, containers also come with Drupal core, and are part of the form API. They are also not available in the Drupal UI. Containers are groupings of fields, but are simpler than fieldsets. They don’t offer collapsibility out of the box. Rather, they simply wrap form elements in a div for easy grouping and theming. The code to build them works very much like fieldsets. You build the container first, and nest field elements under the container key.

[prism:php] $form['contact'] = array( '#type' => container, '#weight' => 5, ‘#attributes’ => array( ‘class’ => array( ‘contact-info’, ), ), ); [/prism:php]

Any elements you nest under the ‘contact’ key will be rendered in that container.

[prism:php] $form[‘contact’][‘first_name’] = array( ‘#type’ => ‘textfield’, ‘#title’ => t(‘First Name’), ‘#default_value’ => ‘’, ‘#size’ => 60, ‘#maxlength’ => 128, ‘#required’ => TRUE ); [/prism:php]

Field Group

Both of the above solutions work great if you aren’t afraid to jump into some php and the form API. However, solutions that provide a user interface are often needed by site builders and site administrators. This is where the Field Group module comes in. Field Group gives a site administrator or site builder a lot of the same functionality offered by fieldset, but allows them to edit and create field groups in the UI for content types, taxonomy terms, and users. Once installed, the admin gets a new form field on the bottom of the manage fields display that looks like this:

If a new group is added, the admin can then drag other fields on the entity under the newly created group.

If you are adding or editing the field group through the form API, be aware that the field group module has a slightly different structure than we are used to. If you open up the $form array with a field group, you will notice field group gives us 3 new keys: ‘#groups’, ‘#fieldgroups’, and ‘#group_children’. To insert a form element into a field group through the form API we first need to add the element to the ‘children’ array under the field group within the ‘#fieldgroups’ key, then add the element to the ‘#group_children’ array, and make its value the group.

For instance, using the above image as a reference, if we wanted to add a fax number field element to the ‘Basic Information’ field group, we would create our fax number field:

[prism:php] $form[‘fax_number’] = array( ‘#type’ => ‘textfield’, ‘#title’ => t(‘Contact Fax Number’), ‘#default_value’ => ‘’, ‘#size’ => 60, ‘#maxlength’ => 128, ‘#required’ => TRUE ); [/prism:php]

Then insert it into the children array ‘group_shipment_basic’ object, within our ‘#fieldgroups’ array:

[prism:php] $form['#fieldgroups'][‘group_shipment_basic’]->children[] = ‘fax_number’; [/prism:php]

And add ‘group_shipment_basic’ to the ‘#group_children array’, and make ‘group_shipment_basic’ its value:

[prism:php] $form['#group_children']['group_pallet_dims'] = 'group_shipment_details'; [/prism:php]

Field Collection

Another contributed module available to group fields is the Field Collection module. Field collection is more robust than field groups, but can be trickier to work with as well. Each field collection is an entity, and therefore comes with all the benefits given to entities in Drupal (one of the biggest benefits is they are exposed to views), and you can use them out of the box to give your users the ability to “Add Another” set of fields to the form.

And because we used field collection here, we can separate these contact collections from the form into their own view.

Remember that good user experience is important on all aspects of a web system, from administrator interfaces to contact forms. Armed with the tools above, you should be able to logically group fields together in a manner that conforms to the site design and user workflow.

For yet another way to build field groups in Drupal check out Ryan's post on creating flexible content in Drupal with Inline Entity Forms.

Banner image courtesy of [Juhan Sonin](