390 lines
13 KiB
Plaintext
390 lines
13 KiB
Plaintext
<?php
|
|
/**
|
|
* @file
|
|
* An example field using the Field Types API.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup field_example Example: Field Types API
|
|
* @ingroup examples
|
|
* @{
|
|
* Examples using Field Types API.
|
|
*
|
|
* This is updated from Barry Jaspan's presentation at Drupalcon Paris,
|
|
* @link http://acquia.com/community/resources/acquia-tv/intro-field-api-module-developers Video Presentation @endlink
|
|
*
|
|
* Providing a field requires:
|
|
* - Defining a field:
|
|
* - hook_field_info()
|
|
* - hook_field_schema()
|
|
* - hook_field_validate()
|
|
* - hook_field_is_empty()
|
|
*
|
|
* - Defining a formatter for the field (the portion that outputs the field for
|
|
* display):
|
|
* - hook_field_formatter_info()
|
|
* - hook_field_formatter_view()
|
|
*
|
|
* - Defining a widget for the edit form:
|
|
* - hook_field_widget_info()
|
|
* - hook_field_widget_form()
|
|
*
|
|
* Our module defines the field in field_example_field_info(),
|
|
* field_example_field_validate() and field_example_field_is_empty().
|
|
* field_example_field_schema() is implemented in field_example.install.
|
|
*
|
|
* Our module sets up a formatter in field_example_field_formatter_info() and
|
|
* field_example_field_formatter_view(). These are the API hooks that present
|
|
* formatted and themed output to the user.
|
|
*
|
|
* And finally, our module defines the widget in
|
|
* field_example_field_widget_info() and field_example_field_widget_form().
|
|
* The widget is the form element used to receive input from the user
|
|
* when the field is being populated.
|
|
*
|
|
* @see field_types
|
|
* @see field
|
|
*/
|
|
|
|
/***************************************************************
|
|
* Field Type API hooks
|
|
***************************************************************/
|
|
|
|
/**
|
|
* Implements hook_field_info().
|
|
*
|
|
* Provides the description of the field.
|
|
*/
|
|
function field_example_field_info() {
|
|
return array(
|
|
// We name our field as the associative name of the array.
|
|
'field_example_rgb' => array(
|
|
'label' => t('Example Color RGB'),
|
|
'description' => t('Demonstrates a field composed of an RGB color.'),
|
|
'default_widget' => 'field_example_3text',
|
|
'default_formatter' => 'field_example_simple_text',
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_validate().
|
|
*
|
|
* This hook gives us a chance to validate content that's in our
|
|
* field. We're really only interested in the $items parameter, since
|
|
* it holds arrays representing content in the field we've defined.
|
|
* We want to verify that the items only contain RGB hex values like
|
|
* this: #RRGGBB. If the item validates, we do nothing. If it doesn't
|
|
* validate, we add our own error notification to the $errors parameter.
|
|
*
|
|
* @see field_example_field_widget_error()
|
|
*/
|
|
function field_example_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
|
|
foreach ($items as $delta => $item) {
|
|
if (!empty($item['rgb'])) {
|
|
if (!preg_match('@^#[0-9a-f]{6}$@', $item['rgb'])) {
|
|
$errors[$field['field_name']][$langcode][$delta][] = array(
|
|
'error' => 'field_example_invalid',
|
|
'message' => t('Color must be in the HTML format #abcdef.'),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* Implements hook_field_is_empty().
|
|
*
|
|
* hook_field_is_empty() is where Drupal asks us if this field is empty.
|
|
* Return TRUE if it does not contain data, FALSE if it does. This lets
|
|
* the form API flag an error when required fields are empty.
|
|
*/
|
|
function field_example_field_is_empty($item, $field) {
|
|
return empty($item['rgb']);
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_formatter_info().
|
|
*
|
|
* We need to tell Drupal that we have two different types of formatters
|
|
* for this field. One will change the text color, and the other will
|
|
* change the background color.
|
|
*
|
|
* @see field_example_field_formatter_view()
|
|
*/
|
|
function field_example_field_formatter_info() {
|
|
return array(
|
|
// This formatter just displays the hex value in the color indicated.
|
|
'field_example_simple_text' => array(
|
|
'label' => t('Simple text-based formatter'),
|
|
'field types' => array('field_example_rgb'),
|
|
),
|
|
// This formatter changes the background color of the content region.
|
|
'field_example_color_background' => array(
|
|
'label' => t('Change the background of the output text'),
|
|
'field types' => array('field_example_rgb'),
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_formatter_view().
|
|
*
|
|
* Two formatters are implemented.
|
|
* - field_example_simple_text just outputs markup indicating the color that
|
|
* was entered and uses an inline style to set the text color to that value.
|
|
* - field_example_color_background does the same but also changes the
|
|
* background color of div.region-content.
|
|
*
|
|
* @see field_example_field_formatter_info()
|
|
*/
|
|
function field_example_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
|
|
$element = array();
|
|
|
|
switch ($display['type']) {
|
|
// This formatter simply outputs the field as text and with a color.
|
|
case 'field_example_simple_text':
|
|
foreach ($items as $delta => $item) {
|
|
$element[$delta] = array(
|
|
// We create a render array to produce the desired markup,
|
|
// "<p style="color: #hexcolor">The color code ... #hexcolor</p>".
|
|
// See theme_html_tag().
|
|
'#type' => 'html_tag',
|
|
'#tag' => 'p',
|
|
'#attributes' => array(
|
|
'style' => 'color: ' . $item['rgb'],
|
|
),
|
|
'#value' => t('The color code in this field is @code', array('@code' => $item['rgb'])),
|
|
);
|
|
}
|
|
break;
|
|
|
|
// This formatter adds css to the page changing the '.region-content' area's
|
|
// background color. If there are many fields, the last one will win.
|
|
case 'field_example_color_background':
|
|
foreach ($items as $delta => $item) {
|
|
$element[$delta] = array(
|
|
'#type' => 'html_tag',
|
|
'#tag' => 'p',
|
|
'#value' => t('The content area color has been changed to @code', array('@code' => $item['rgb'])),
|
|
'#attached' => array(
|
|
'css' => array(
|
|
array(
|
|
'data' => 'div.region-content { background-color:' . $item['rgb'] . ';}',
|
|
'type' => 'inline',
|
|
),
|
|
),
|
|
),
|
|
);
|
|
}
|
|
break;
|
|
}
|
|
|
|
return $element;
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_widget_info().
|
|
*
|
|
* Three widgets are provided.
|
|
* - A simple text-only widget where the user enters the '#ffffff'.
|
|
* - A 3-textfield widget that gathers the red, green, and blue values
|
|
* separately.
|
|
* - A farbtastic colorpicker widget that chooses the value graphically.
|
|
*
|
|
* These widget types will eventually show up in hook_field_widget_form,
|
|
* where we will have to flesh them out.
|
|
*
|
|
* @see field_example_field_widget_form()
|
|
*/
|
|
function field_example_field_widget_info() {
|
|
return array(
|
|
'field_example_text' => array(
|
|
'label' => t('RGB value as #ffffff'),
|
|
'field types' => array('field_example_rgb'),
|
|
),
|
|
'field_example_3text' => array(
|
|
'label' => t('RGB text field'),
|
|
'field types' => array('field_example_rgb'),
|
|
),
|
|
'field_example_colorpicker' => array(
|
|
'label' => t('Color Picker'),
|
|
'field types' => array('field_example_rgb'),
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_widget_form().
|
|
*
|
|
* hook_widget_form() is where Drupal tells us to create form elements for
|
|
* our field's widget.
|
|
*
|
|
* We provide one of three different forms, depending on the widget type of
|
|
* the Form API item provided.
|
|
*
|
|
* The 'field_example_colorpicker' and 'field_example_text' are essentially
|
|
* the same, but field_example_colorpicker adds a javascript colorpicker
|
|
* helper.
|
|
*
|
|
* field_example_3text displays three text fields, one each for red, green,
|
|
* and blue. However, the field type defines a single text column,
|
|
* rgb, which needs an HTML color spec. Define an element validate
|
|
* handler that converts our r, g, and b fields into a simulated single
|
|
* 'rgb' form element.
|
|
*/
|
|
function field_example_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
|
|
$value = isset($items[$delta]['rgb']) ? $items[$delta]['rgb'] : '';
|
|
|
|
$widget = $element;
|
|
$widget['#delta'] = $delta;
|
|
|
|
switch ($instance['widget']['type']) {
|
|
|
|
case 'field_example_colorpicker':
|
|
$widget += array(
|
|
'#suffix' => '<div class="field-example-colorpicker"></div>',
|
|
'#attributes' => array('class' => array('edit-field-example-colorpicker')),
|
|
'#attached' => array(
|
|
// Add Farbtastic color picker.
|
|
'library' => array(
|
|
array('system', 'farbtastic'),
|
|
),
|
|
// Add javascript to trigger the colorpicker.
|
|
'js' => array(drupal_get_path('module', 'field_example') . '/field_example.js'),
|
|
),
|
|
);
|
|
// DELIBERATE fall-through: From here on the field_example_text and
|
|
// field_example_colorpicker are exactly the same.
|
|
case 'field_example_text':
|
|
$widget += array(
|
|
'#type' => 'textfield',
|
|
'#default_value' => $value,
|
|
// Allow a slightly larger size that the field length to allow for some
|
|
// configurations where all characters won't fit in input field.
|
|
'#size' => 7,
|
|
'#maxlength' => 7,
|
|
);
|
|
break;
|
|
|
|
case 'field_example_3text':
|
|
// Convert rgb value into r, g, and b for #default_value.
|
|
if (!empty($value)) {
|
|
preg_match_all('@..@', substr($value, 1), $match);
|
|
}
|
|
else {
|
|
$match = array(array());
|
|
}
|
|
|
|
// Make this a fieldset with the three text fields.
|
|
$widget += array(
|
|
'#type' => 'fieldset',
|
|
'#element_validate' => array('field_example_3text_validate'),
|
|
|
|
// #delta is set so that the validation function will be able
|
|
// to access external value information which otherwise would be
|
|
// unavailable.
|
|
'#delta' => $delta,
|
|
|
|
'#attached' => array(
|
|
'css' => array(drupal_get_path('module', 'field_example') . '/field_example.css'),
|
|
),
|
|
);
|
|
|
|
// Create a textfield for saturation values for Red, Green, and Blue.
|
|
foreach (array('r' => t('Red'), 'g' => t('Green'), 'b' => t('Blue')) as $key => $title) {
|
|
$widget[$key] = array(
|
|
'#type' => 'textfield',
|
|
'#title' => $title,
|
|
'#size' => 2,
|
|
'#default_value' => array_shift($match[0]),
|
|
'#attributes' => array('class' => array('rgb-entry')),
|
|
'#description' => t('The 2-digit hexadecimal representation of @color saturation, like "a1" or "ff"', array('@color' => $title)),
|
|
);
|
|
// Since Form API doesn't allow a fieldset to be required, we
|
|
// have to require each field element individually.
|
|
if ($instance['required'] == 1) {
|
|
$widget[$key]['#required'] = 1;
|
|
}
|
|
}
|
|
break;
|
|
|
|
}
|
|
|
|
$element['rgb'] = $widget;
|
|
return $element;
|
|
}
|
|
|
|
|
|
/**
|
|
* Validate the individual fields and then convert to RGB string.
|
|
*/
|
|
function field_example_3text_validate($element, &$form_state) {
|
|
// @todo: Isn't there a better way to find out which element?
|
|
$delta = $element['#delta'];
|
|
$field = $form_state['field'][$element['#field_name']][$element['#language']]['field'];
|
|
$field_name = $field['field_name'];
|
|
if (isset($form_state['values'][$field_name][$element['#language']][$delta]['rgb'])) {
|
|
$values = $form_state['values'][$field_name][$element['#language']][$delta]['rgb'];
|
|
foreach (array('r', 'g', 'b') as $colorfield) {
|
|
$colorfield_value = hexdec($values[$colorfield]);
|
|
// If they left any empty, we'll set the value empty and quit.
|
|
if (strlen($values[$colorfield]) == 0) {
|
|
form_set_value($element, '', $form_state);
|
|
return;
|
|
}
|
|
// If they gave us anything that's not hex, reject it.
|
|
if ((strlen($values[$colorfield]) != 2) || $colorfield_value < 0 || $colorfield_value > 255) {
|
|
form_error($element[$colorfield], t("Saturation value must be a 2-digit hexadecimal value between 00 and ff."));
|
|
}
|
|
}
|
|
|
|
$value = sprintf('#%02s%02s%02s', $values['r'], $values['g'], $values['b']);
|
|
form_set_value($element, $value, $form_state);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Implements hook_field_widget_error().
|
|
*
|
|
* hook_field_widget_error() lets us figure out what to do with errors
|
|
* we might have generated in hook_field_validate(). Generally, we'll just
|
|
* call form_error().
|
|
*
|
|
* @see field_example_field_validate()
|
|
* @see form_error()
|
|
*/
|
|
function field_example_field_widget_error($element, $error, $form, &$form_state) {
|
|
switch ($error['error']) {
|
|
case 'field_example_invalid':
|
|
form_error($element, $error['message']);
|
|
break;
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* Implements hook_menu().
|
|
*
|
|
* Provides a simple user interface that tells the developer where to go.
|
|
*/
|
|
function field_example_menu() {
|
|
$items['examples/field_example'] = array(
|
|
'title' => 'Field Example',
|
|
'page callback' => '_field_example_page',
|
|
'access callback' => TRUE,
|
|
);
|
|
return $items;
|
|
}
|
|
|
|
/**
|
|
* A simple page to explain to the developer what to do.
|
|
*/
|
|
function _field_example_page() {
|
|
return t("The Field Example provides a field composed of an HTML RGB value, like #ff00ff. To use it, add the field to a content type.");
|
|
}
|
|
/**
|
|
* @} End of "defgroup field_example".
|
|
*/
|