Compound fields in Drupal 7
Compound fields in Drupal 7
Tobby Hagler | Director, Engineering
March 1, 2011
With Field API being part of core as of Drupal 7.0, creating custom fields just became a lot easier than they were in Drupal 6.x. Suppose you need to create a compound field, which consists of several different form elements (a select and several text fields). You can now have a basic compound field in three basic steps:
- Define the field (info and schema)
- Define the field form (widget)
- Define the output (formatter)
Note: Much of what will be discussed here can be found in the Field Example module, but with some much-needed explanations.
Step 1: Tell Drupal about the field
As with most APIs in Drupal, there are hooks that are required in order to tell Drupal about what it is you're creating. The hooks you'll need to initially define your field are:
- hook_field_info() -- The initial hook that defines which widget and formatter elements to use for the field
- hook_field_schema() -- The schema for storing your field information. This is similar to hook_schema() for modules, and also belongs in your module's .info file.
- hook_field_validate() -- A validation function that will validate all input from the field forms.
- hook_field_is_empty() -- Determine if your field has data, so that you may or may not be able to modify the widget later.
hook_field_info()
function dnd_fields_field_info() {
return array(
'dnd_fields_ability' => array(
'label' => t('D&D ability'),
'description' => t("This field stores PC ability scores"),
'settings' => array('allowed_values' => array(), 'allowed_values_function' => ''),
'default_widget' => 'dnd_fields_ability',
'default_formatter' => 'dnd_fields_ability', // This doesn't *have* to be the same name as default_widget's value, this is only coincidence
),
'dnd_fields_skill' => array(
'label' => t('D&D skill'),
'description' => t("This field stores PC skill values"),
'settings' => array('allowed_values' => array(), 'allowed_values_function' => ''),
'default_widget' => 'dnd_fields_skill',
'default_formatter' => 'dnd_fields_skill',
),
);
}This hook defines the initial widget. It defines the widget and formatter internally, but it also contains what will be displayed in the Manage Fields page of your content type admin UI. The default_widget and default_formatter aren't functions, they are operations that will be passed to hooks later. The settings element will let you set additional (optional) functions to handle default values, which may come in handy if you want the values of a select field to come from your database.
hook_field_schema()
Note: This goes in your .install file.
function dnd_fields_field_schema($field) {
switch($field['type']) {
case 'dnd_fields_ability':
$columns = array(
'ability' => array(
'type' => 'varchar',
'length' => '32',
'not null' => FALSE,
),
'score' => array(
'type' => 'int',
'size' => 'small',
'not null' => TRUE,
'default' => 0,
),
'mod' => array(
'type' => 'int',
'size' => 'small',
'not null' => TRUE,
'default' => 0,
),
'tempscore' => array(
'type' => 'int',
'size' => 'small',
'not null' => TRUE,
'default' => 0,
),
'tempmod' => array(
'type' => 'int',
'size' => 'small',
'not null' => TRUE,
'default' => 0,
),
);
break;
case 'dnd_fields_skill':
$columns = array(
'skill' => array(
'type' => 'varchar',
'length' => '128',
'not null' => FALSE,
),
'ranks' => array(
'type' => 'int',
'size' => 'small',
'not null' => TRUE,
'default' => 0,
),
);
$indexes = array(
'skill' => array('skill'),
);
break;
}
return array(
'columns' => $columns,
'indexes' => $indexes,
);
} This is identical to hook_schema() in the sense that syntax and data types are the same. For each field element in your widget, you will need a corresponding column (unless of course you are combining data from multiple input fields).
hook_field_validate()
function dnd_fields_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
foreach ($items as $delta => $item) {
// ...
}
}hook_field_is_empty()
function dnd_fields_field_is_empty($item, $field) {
$temp = array_keys($field['columns']);
$key = array_shift($temp);
return empty($item[$key]);
}In the simplest form, this hook tells Drupal that your field is or is not empty. This is checked when a site administrator attempts to modify an existing widget. In cases when there is existing field data, it is unadvisable to modify field settings, such as the list of allowed values (since the content in your existing fields will not be re-validated).
Step 2: Create the field widget
The next step is to create the field widget. This is essentially the form (using Form API) for user input as well as any interface elements that you wish to create. The hooks needed to create the field widget are:
hook_field_widget_info()
This hook tells Drupal enough information about your widget in order to start using the field and to accept user input.
function dnd_fields_field_widget_info() {
return array(
'dnd_fields_ability' => array(
'label' => t('D&D ability score'),
'field types' => array('dnd_fields_ability'),
),
'dnd_fields_skill' => array(
'label' => t('D&D skill values'),
'field types' => array('dnd_fields_skill'),
),
);
}At minimum, this returns a label that is displayed when selecting this widget from the Manage fields page while editing a content type. It also ties together that label to the field types, which are defined next.
hook_field_widget_form()
function dnd_fields_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
switch ($instance['widget']['type']) {
case 'dnd_fields_ability':
$settings = $form_state['field'][$instance['field_name']][$langcode]['field']['settings'];
$fields = array(
'ability' => t('Ability'),
'score' => t('Score'),
'mod' => t('Modifier'),
'tempscore' => t('Temp score'),
'tempmod' => t('Temp modifier'),
);
$abilities = (!empty($field['settings']['abilities'])) ? explode("n", $field['settings']['abilities']) : array();
foreach ($fields as $key => $label) {
$value = isset($items[$delta][$key]) ? $items[$delta][$key] : '';
if (empty($value) && $key == 'ability') {
$value = $abilities[$delta];
}
$element[$key] = array(
'#attributes' => array('class' => array('edit-dnd-fields-ability'), 'title' => t(''), 'rel' => strtolower($abilities[$delta])),
'#type' => 'textfield',
'#size' => 3,
'#maxlength' => 3,
'#title' => $label,
'#default_value' => $value,
'#attached' => array(
'css' => array(drupal_get_path('module', 'dnd_fields') . '/dnd_fields.css'),
'js' => array(drupal_get_path('module', 'dnd_fields') . '/dnd_fields.js'),
),
'#prefix' => '<div class="dnd-fields-ability-field dnd-fields-ability-' . $key . '-field dnd-fields-ability-' . $key . '-' . strtolower($abilities[$delta]) . '-field">',
'#suffix' => '</div>',
);
if ($key == 'ability') {
$element[$key]['#size'] = 10;
$element[$key]['#maxlength'] = 32;
if (arg(0) != 'admin') {
$element[$key]['#attributes'] = array('readonly' => 'readonly');
}
}
}
break;
case 'dnd_fields_skill':
$settings = $form_state['field'][$instance['field_name']][$langcode]['field']['settings'];
// Get the list of skills broken into an array, and split those elements into a
// multi-dimensional arrays
$skills_temp = (!empty($settings['skill'])) ? preg_split('/(rn?|n)/', $settings['skill']) : array();
$skills = array(0 => t('-Choose a skill-'));
foreach ($skills_temp as $skill) {
if(strpos($skill, '|') === FALSE) {
$skills[] = array($skill);
}
else {
$temp = explode('|', $skill);
$skills[$temp[0]] = $temp[1];
}
}
$element['skill'] = array(
'#attributes' => array('class' => array('edit-dnd-fields-skill'), 'title' => t('')),
'#type' => 'select',
'#options' => $skills,
'#title' => t('Skill name'),
'#description' => t('Choose a skill you wish to allocate ranks to.'),
'#attached' => array(
'css' => array(drupal_get_path('module', 'dnd_fields') . '/dnd_fields.css'),
'js' => array(drupal_get_path('module', 'dnd_fields') . '/dnd_fields.js'),
),
'#prefix' => '<div class="dnd-fields-skill-field dnd-fields-skill-skill-field">',
'#suffix' => '</div>',
);
$element['ranks'] = array(
'#attributes' => array('class' => array('edit-dnd-fields-ranks'), 'title' => t('')),
'#type' => 'textfield',
'#size' => 3,
'#maxlength' => 3,
'#title' => t('Skill ranks'),
'#prefix' => '<div class="dnd-fields-skill-field dnd-fields-skill-ranks-field">',
'#suffix' => '</div>',
);
// Loop through all the element children and set a default value if we have one. Then set HTML wrappers.
foreach (element_children($element) as $element_key) {
$value = isset($items[$delta][$element_key]) ? $items[$delta][$element_key] : '';
$element[$element_key]['#default_value'] = $value;
}
break;
}
return $element;
}With this hook, you now have something tangible that you can see and work with. This hook doubles as both the widget that the user sees when entering content into a node as well as the form the site administrator uses when creating a field with this widget on the content type. This hook is called for each field looking for widget information. In this case, we'll need to check the $instance['widget']['type'] value, which will correspond to the 'field types' element defined in our hook_field_widget_info() function above. Just as with regular forms using Form API, there is a $form_state variable that contains information that we want about the current state of the form widget. This is important for instances where a site administrator creates the field with default data. It also helps when doing multi-step forms with extremely complex widgets (yes, multi-step forms are possible, but those are a blog post of their own). Everything else is just Forms API. Feel free to embellish the form fields with jQuery plugins for a nice interface. The #attached array element provides an easy way to add JavaScript and CSS files to your form. You can also add #prefix and #suffix elements to provide HTML wrappers, which we will use later in the formatter hooks below.
Step 3: Format the field
Perhaps the most satisfying aspect of creating a custom field is the formatter. This is the output displayed to the end user. Just like with the widget hooks, there are two simple formatter hooks that we will use:
hook_field_formatter_info()
function dnd_fields_field_formatter_info() {
return array(
'dnd_fields_ability' => array(
'label' => t('Ability scores'),
'field types' => array('dnd_fields_ability'),
),
'dnd_fields_skill' => array(
'label' => t('Skill fields'),
'field types' => array('dnd_fields_skill'),
),
);
}Again, this is simply a list of the label for your field and which field types that are involved in the next hook.
hook_field_formatter_view()
This is the hook that will format and display the field.
function dnd_fields_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
$element = array();
switch ($display['type']) {
case 'dnd_fields_ability':
$headers = array(
t('Skill'),
t('Score'),
t('Modifier'),
t('Temp score'),
t('Temp modifier'),
);
$element[0]['#theme'] = 'table';
$element[0]['#data'] = array('header' => $headers, 'rows' => $items);
break;
case 'dnd_fields_skill':
// Set the skill name to the human readable name instead of the internal machine name.
$skills = dnd_fields_skill_list_array(explode("n", $field['settings']['skill']));
foreach ($items as $delta => $item) {
$items[$delta]['skill'] = $skills[$item['skill']];
}
$headers = array(
t('Skill'),
t('Ranks'),
);
$element[0]['#theme'] = 'table';
$element[0]['#data'] = array('header' => $headers, 'rows' => $items);
break;
}
return $element;
}There are countless ways to format the field data. For simplicity's sake, I'll water this down to the bare minimum needed to display the field data in an HTML table. Just like the hook_field_widget_form hook above, this looks at the display type to determine how to format the field. This hook returns a renderable array. In the example above, a simple table is used, which prints multiple entries as part of the same table. In other cases, you may want to loop through each field item in order to theme it individually.
foreach ($items as $delta => $item) {
$element[$delta] = array(
'#theme' => 'some_theme_function',
'#data' => $item['value'],
);
}In the original example above, $element[0] is the first instance of $element[$delta].
Final thoughts
While a field requires eight hooks to get started, most of it is straightforward. This example focuses mainly compound fields, but many other options are possible. For another good example, check out the Field Example module that comes with core. That module uses a jQuery color picker to help with field input. There are other hooks worth considering:
- hook_field_presave() - When dealing with compound fields, it's important to set any values for form elements that weren't set by the user. This will help prevent SQL errors when inserting null values into database tables that have 'not null' set.
- hook_form_field_ui_field_edit_form_alter() - This is hook_form_FORM_ID_alter(). This is a really useful hook for manipulating existing field forms, and adding default values that have to be calculated.
In the widget form hook above, I alluded to adding some HTML wrappers to help with formatting the form. By default, all the form fields will be displayed one on top of each other. Using this CSS, you can make forms that look a little more cohesive:
[css].field-type-dnd-fields-skill { display: inline-block; width: 100%; } .dnd-fields-skill-field { float: left; margin: 0 10px 0 0; } .dnd-fields-skill-ranks-field .form-text { width: 52px; } .dnd-fields-skill-field label { font-weight: normal; font-size: 12px; padding: 0 0 2px; } .dnd-fields-skill-ranks-field .form-item .description { width: 200px; display: none; }[/css]
