Drupal 7 Module Development

Chapter 7
Exposing fields to the Form API with
widgets
Although fields can be stored anywhere (or at least anywhere for which we write
a storage engine) and accessed in a variety of ways, by far the most common user
workflow is to create and edit an entity containing fields using a form embedded in
a web page. In Drupal, all forms shown to the user are controlled by the Form API,
introduced in Chapter 5. The way the field system exposes itself to the Form API is
through widgets.
Widgets are simply Form API fragments that can get built into a larger form by
Drupal. They can be very simple or very complex, depending on how we want
to present information to the user. In fact, some of the greatest powers of widgets
comes from the fact that the form elements the widget exposes do not have to map
to the storage of the field type itself at all. Imagine, for example, a field that stored
geographic points. While we could simply offer the user a series of text fields to enter
X and Y values, it would be much nicer if we could offer them an interactive map
to click on. The coordinate data would then get mapped back into X and Y values
before it's stored, without the field itself being any the wiser. With widgets, we can
do exactly that.
Declaring a widget
As with field types, widgets start with an info hook:
function dimfield_field_widget_info() {
return array(
'dimfield_simple' => array(
'label' => t('Separate text fields'),
'description' => t(
'Allow the user to enter each dimension separately.'),
'field types' => array('dimensions'),
'behaviors' => array(
'multiple values' => FIELD_BEHAVIOR_DEFAULT,
'default value' => FIELD_BEHAVIOR_DEFAULT,
),
),
'dimfield_combined' => array(
'label' => t('Combined text field'),
'description' => t(
'Allow the user to enter all dimensions together.'),
'field types' => array('dimensions'),
'settings' => array('size' => 10),
[ 191 ]