编辑“Drupal:CCK字段模块样本”

此例为一个CCK字段模块，它举例说明可用的字段及窗件挂钩(Hook)。此例取自CCK整合包中的field.php文件，其中包括了几个不同的字段，以各种方法使用Hook。

一个模块可以创建一个或多个字段，也可以是一个或多个窗件。选项窗件（optionwidget） 模块可以创建一些窗件但不能创建字段。数字（number）模块可以创建两类字段和一个单个的文本字段窗件。日期（date）模块创建两类字段，每种字段都有三类不同的窗件对应。

内容模块处理node_load() and node_save()运算，所以在大部分情况下字段模块不对这些运算做处理。它们则会定义必要的数据存储方式--在表单中进行收集并在节点中显示出来。

注意，字段和窗件几乎不做任何数据库查询。绝大多数情况下所有必要的查询都会被内容模块处理。 

<pre>
<?php
/**
* @file
* These hooks are defined by field modules, modules that define a new kind
* of field for insertion in a content type.
*
* Field hooks are typically called by content.module using _content_field_invoke().
*
* Widget module hooks are also defined here; the two go hand-in-hand, often in
* the same module (though they are independent).
*
* Widget hooks are typically called by content.module using _content_widget_invoke().
*/

/**
* @addtogroup hooks
* @{
*/
?>

</pre>

绝大多数模块只声明单个字段，但可以创建任意多的不同类型。注意，此模块声明两种类型的字段，整数字段和小数字段。

<pre>
<?php
/**
* Declare information about a field type.
*
* @return
*   An array keyed by field type name. Each element of the array is an associative
*   array with these keys and values:
*   - "label": The human-readable label for the field type.
*/
function hook_field_info() {
  return array(
    'number_integer' => array('label' => 'Integer'),
    'number_decimal' => array('label' => 'Decimal'),
</pre>

函数hook_field_settings() 为字段进行定义。'form'和'save'运算是协同工作的。使用'form'向字段管理表单添加一个设定，而'save'则确保此设定保存贼了内容模块的管理过程中。

注意尽管绝大多数的字段具有一个数据库栏，其中包括一个称为“value”的值，你还是可以为一个字段声明任意数量的栏位。比如，日期字段可以定义日期数值（date value），时区（timezone）及时差（offset）。

<pre>
<?php
/**
* Handle the parameters for a field.
*
* @param $op
*   The operation to be performed. Possible values:
*   - "form": Display the field settings form.
*   - "validate": Check the field settings form for errors.
*   - "save": Declare which fields to save back to the database.
*   - "database columns": Declare the columns that content.module should create
*     and manage on behalf of the field. If the field module wishes to handle
*     its own database storage, this should be omitted.
*   - "filters": If content.module is managing the database storage,
*     this operator determines what filters are available to views.
*     They always apply to the first column listed in the "database columns"
*     array.
* @param $field
*   The field on which the operation is to be performed.
* @return
*   This varies depending on the operation.
*   - The "form" operation should return an array of form elements to add to
*     the settings page.
*   - The "validate" operation has no return value. Use form_set_error().
*   - The "save" operation should return an array of names of form elements to
*     be saved in the database.
*   - The "database columns" operation should return an array keyed by column
*     name, with arrays of column information as values. This column information
*     must include "type", the MySQL data type of the column, and may also
*     include a "sortable" parameter to indicate to views.module that the
*     column contains ordered information. Details of other information that can
*     be passed to the database layer can be found at content_db_add_column().
*   - The "filters" operation should return an array whose values are 'filters'
*     definitions as expected by views.module (see Views Documentation).
*     When proving several filters, it is recommended to use the 'name'
*     attribute in order to let the user distinguish between them. If no 'name'
*     is specified for a filter, the key of the filter will be used instead.
*/
function hook_field_settings($op, $field) {
  switch ($op) {
    case 'form':
      $form = array();
      $form['max_length'] = array(
        '#type' => 'textfield',
        '#title' => t('Maximum length'),
        '#default_value' => $field['max_length'] ? $field['max_length'] : '',
        '#required' => FALSE,
        '#description' => t('The maximum length of the field in characters. Leave blank for an unlimited size.'),
      );
      $form['allowed_values'] = array(
        '#type' => 'textarea',
        '#title' => t('Allowed values list'),
        '#default_value' => isset($field['allowed_values']) ? $field['allowed_values'] : '',
        '#required' => FALSE,
        '#rows' => 10,
        '#description' => t('The possible values this field can contain.'),
      );

      return $form;

    case 'save':
      return array('max_length', 'allowed_values');

    case 'database columns':
      $columns = array(
        'value' => array('type' => 'varchar', 'not null' => TRUE, 'default' => "''", 'sortable' => TRUE),
        'format' => array('type' => 'int', 'length' => 10, 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
      );
      if ($field['max_length'] == 0 || $field['max_length'] > 255) {
        $columns['value']['type'] = 'longtext';
      }
      else {
        $columns['value']['length'] = $field['max_length'];
      }
      return $columns;

    case 'filters':
      return array(
        'substring' => array(
          'operator' => 'views_handler_operator_like',
          'handler' => 'views_handler_filter_like',
        ),
        'alpha_order' => array(
          'name' => 'alphabetical order',
          'operator' => 'views_handler_operator_gtlt',
        ),
      );
  }
}
?>
</pre>

Hook_field() 定义字段存储方式及内容显示方式。'view'运算定义数据的显示方式。一般来说视图使用函数content_format()，应返回默认的格式。

当节点验证后，'validate' 运算为字段提供验证字段数据的机会。$field 参量包含字段的设定，在验证过程中使用的话将会有所帮助。

内容模块将这些运算中的每一个都调用两次，第一次它们各司其职，第二次则是内容模块本身，即在字段上执行自身的运算。

<pre>
<?php
/**
* Define the behavior of a field type.
*
* @param $op
*   What kind of action is being performed. Possible values:
*   - "load": The node is about to be loaded from the database. This hook
*     should be used to load the field.
*   - "view": The node is about to be presented to the user. The module
*     should prepare and return an HTML string containing a default
*     representation of the field.
*   - "validate": The user has just finished editing the node and is
*     trying to preview or submit it. This hook can be used to check or
*     even modify the node. Errors should be set with form_set_error().
*   - "submit": The user has just finished editing the node and the node has
*     passed validation. This hook can be used to modify the node.
*   - "insert": The node is being created (inserted in the database).
*   - "update": The node is being updated.
*   - "delete": The node is being deleted.
* @param &$node
*   The node the action is being performed on. This argument is passed by
*   reference for performance only; do not modify it.
* @param $field
*   The field the action is being performed on.
* @param &$items
* An array containing the values of the field in this node. Changes to this variable will
* be saved back to the node object.
* Note that, in order to ensure consistency, this variable contains an array regardless of
* whether field is set to accept multiple values or not.
* @return
*   This varies depending on the operation.
*   - The "load" operation should return an object containing extra values
*     to be merged into the node object.
*   - The "view" operation should return a string containing an HTML
*     representation of the field data.
*   - The "insert", "update", "delete", "validate", and "submit" operations
*     have no return value.
*
* In most cases, only "view" and "validate" are relevant operations; the rest
* have default implementations in content_field() that usually suffice.
*/
function hook_field($op, &$node, $field, &$items, $teaser, $page) {
   switch ($op) {
    case 'view':
      foreach ($items as $delta => $item) {
        $items[$delta]['view'] = content_format($field, $item, 'default', $node);
      }
      return theme('field', $node, $field, $items, $teaser, $page);

    case 'validate':
      $allowed_values = text_allowed_values($field);

      if (is_array($items)) {
        foreach ($items as $delta => $item) {
          $error_field = $field['field_name'].']['.$delta.'][value';
          if ($item['value'] != '') {
            if (count($allowed_values) && !array_key_exists($item['value'], $allowed_values)) {
              form_set_error($error_field, t('Illegal value for %name.', array('%name' => t($field['widget']['label']))));
            }
          }
        }
      }
      break;
  }
}
?>

</pre>

CCK使用格式化程序以允许字段定义一种或多种信息显示方式。'default（默认）'的格式化程序用于标准节点的显示，但你可以在主题中使用其他的格式化程序，一不同的方式显示它。

主题中格式化程序输出的显示方式是：

<pre>
print content_format('field_example', $field_example[0], 'trimmed');
</pre>

当字段使用于Views时，所有可用的格式化程序会显示为选项。


<pre>
<?php
/**
* Declare information about a formatter.
*
* @return
*   An array keyed by formatter name. Each element of the array is an associative
*   array with these keys and values:
*   - "label": The human-readable label for the formatter.
*   - "field types": An array of field type names that can be displayed using
*     this formatter.
*/
function hook_field_formatter_info() {
  return array(
    'default' => array(
      'label' => 'Default',
      'field types' => array('text'),
    ),
    'plain' => array(
      'label' => 'Plain text',
      'field types' => array('text'),
    ),
    'trimmed' => array(
      'label' => 'Trimmed',
      'field types' => array('text'),
    ),
  );
}

/**
* Prepare an individual item for viewing in a browser.
*
* @param $field
*   The field the action is being performed on.
* @param $item
*   An array, keyed by column, of the data stored for this item in this field.
* @param $formatter
*   The name of the formatter being used to display the field.
* @param $node
*   The node object, for context. Will be NULL in some cases.
*   Warning : when displaying field retrieved by Views, $node will not
*   be a "full-fledged" node object, but an object containg the data returned
*   by the Views query (at least nid, vid, changed)
* @return
*   An HTML string containing the formatted item.
*
* In a multiple-value field scenario, this function will be called once per
* value currently stored in the field. This function is also used as the handler
* for viewing a field in a views.module tabular listing.
*
* It is important that this function at the minimum perform security
* transformations such as running check_plain() or check_markup().
*/
function hook_field_formatter($field, $item, $formatter, $node) {
  if (!isset($item['value'])) {
    return '';
  }
  if ($field['text_processing']) {
    $text = check_markup($item['value'], $item['format'], is_null($node) || isset($node->in_preview));
  }
  else {
    $text = check_plain($item['value']);
  }
  
  switch ($formatter) {
    case 'plain':
      return strip_tags($text);
    
    case 'trimmed':
      return node_teaser($text, $field['text_processing'] ? $item['format'] : NULL);
    
    default:
      return $text;
  }
}
?>

</pre>

与字段一样，窗件可以为自身声明信息。它们需要判别可以处理的字段类型。可以有多于一个的窗件，而且每个窗件都可以处理一种以上的字段。

<pre>
<?php
/**
* Declare information about a widget.
*
* @return
*   An array keyed by widget name. Each element of the array is an associative
*   array with these keys and values:
*   - "label": The human-readable label for the widget.
*   - "field types": An array of field type names that can be edited using
*     this widget.
*/
function hook_widget_info() {
  return array(
    'text' => array(
      'label' => 'Text Field',
      'field types' => array('text'),
    ),
  );
}
?>

</pre>

hook_widget_settings() 与hook_field_settings()几乎相同，唯一不同就是前者允许你定义窗件的行为方式。

某些字段和窗件设定经由内容模块处理，因此它们在此没有被定义。内容模块处理表单元素，为每个字段收集字段标签，帮助文本和weight。

<pre>
<?php
/**
* Handle the parameters for a widget.
*
* @param $op
*   The operation to be performed. Possible values:
*   - "form": Display the widget settings form.
*   - "validate": Check the widget settings form for errors.
*   - "save": Declare which pieces of information to save back to the database.
* @param $widget
*   The widget on which the operation is to be performed.
* @return
*   This varies depending on the operation.
*   - The "form" operation should return an array of form elements to add to
*     the settings page.
*   - The "validate" operation has no return value. Use form_set_error().
*   - The "save" operation should return an array of names of form elements to
*     be saved in the database.
*/
function hook_widget_settings($op, $widget) {
  switch ($op) {
    case 'form':
      $form = array();
      $form['rows'] = array(
        '#type' => 'textfield',
        '#title' => t('Rows'),
        '#default_value' => $widget['rows'] ? $widget['rows'] : 1,
        '#required' => TRUE,
      );
      return $form;

    case 'validate':
      if (!is_numeric($widget['rows']) || intval($widget['rows']) != $widget['rows'] || $widget['rows'] <= 0) {
        form_set_error('rows', t('"Rows" must be a positive integer.'));
      }
      break;

    case 'save':
      return array('rows');
  }
}
?>
</pre>

Hook_widget() 控制窗件的行为，主要是用于创建和验证编辑表单（edit form）。'process form values' 运算应用作在表单数值被存储之前对它们进行操作。此运算在预览前被呼叫，因此以正确预览数值为目的的操作都要先经过此运算的处理。

注意，表单元素的顶层必须包括#tree => TRUE ，这样表单就会保留所有的次级元素（sub-element）。参见FAPI资料进一步了解 #tree。

<pre>
<?php
/**
* Define the behavior of a widget.
*
* @param $op
*   What kind of action is being performed. Possible values:
*   - "prepare form values": The editing form will be displayed. The widget
*     should perform any conversion necessary from the field's native storage
*     format into the storage used for the form. Convention dictates that the
*     widget's version of the data should be stored beginning with "default".
*   - "form": The node is being edited, and a form should be prepared for
*     display to the user.
*   - "validate": The user has just finished editing the node and is
*     trying to preview or submit it. This hook can be used to check or
*     even modify the node. Errors should be set with form_set_error().
*   - "process form values": The inverse of the prepare operation. The widget
*     should convert the data back to the field's native format.
*   - "submit": The user has just finished editing the node and the node has
*     passed validation. This hook can be used to modify the node.
* @param &$node
*   The node the action is being performed on. This argument is passed by
*   reference for performance only; do not modify it.
* @param $field
*   The field the action is being performed on.
* @param &$items
* An array containing the values of the field in this node. Changes to this variable will
* be saved back to the node object.
* Note that, in order to ensure consistency, this variable contains an array regardless of
* whether field is set to accept multiple values or not.
* @return
*   This varies depending on the operation.
*   - The "form" operation should return an array of form elements to display.
*   - Other operations have no return value.
*/
function hook_widget($op, &$node, $field, &$items) {
  switch ($op) {
    case 'prepare form values':
      if ($field['multiple']) {
        $items_transposed = content_transpose_array_rows_cols($items);
        $items['default nids'] = $items_transposed['nid'];
      }
      else {
        $items['default nids'] = array($items['nid']);
      }
      break;

    case 'form':
      $form = array();

      $form[$field['field_name']] = array('#tree' => TRUE);
      $form[$field['field_name']]['nids'] = array(
        '#type' => 'select',
        '#title' => t($field['widget']['label']),
        '#default_value' => $items['default nids'],
        '#multiple' => $field['multiple'],
        '#options' => _nodereference_potential_references($field),
        '#required' => $field['required'],
        '#description' => $field['widget']['description'],
      );
      return $form;

    case 'process form values':
      if ($field['multiple']) {
        $items = content_transpose_array_rows_cols(array('nid' => $items['nids']));
      }
      else {
        $items['nid'] = is_array($items['nids']) ? reset($items['nids']) : $items['nids'];
      }
      break;
  }
}



/**
* @} End of "addtogroup hooks".
*/
?>
</pre>

请注意，所有的Hook函数都是必须的。CCK希望他们都被表现出来，缺一不可。


[[category:drupal:cck]]