Drupal:CCK字段模塊樣本

此例為一個CCK字段模塊，它舉例說明可用的字段及窗件掛鉤(Hook)。此例取自CCK整合包中的field.php文件，其中包括了幾個不同的字段，以各種方法使用Hook。

一個模塊可以創(chuàng)建一個或多個字段，也可以是一個或多個窗件。選項窗件（optionwidget） 模塊可以創(chuàng)建一些窗件但不能創(chuàng)建字段。數(shù)字（number）模塊可以創(chuàng)建兩類字段和一個單個的文本字段窗件。日期（date）模塊創(chuàng)建兩類字段，每種字段都有三類不同的窗件對應(yīng)。

內(nèi)容模塊處理node_load() and node_save()運(yùn)算，所以在大部分情況下字段模塊不對這些運(yùn)算做處理。它們則會定義必要的數(shù)據(jù)存儲方式--在表單中進(jìn)行收集并在節(jié)點(diǎn)中顯示出來。

注意，字段和窗件幾乎不做任何數(shù)據(jù)庫查詢。絕大多數(shù)情況下所有必要的查詢都會被內(nèi)容模塊處理。

<?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
* @{
*/
?>

絕大多數(shù)模塊只聲明單個字段，但可以創(chuàng)建任意多的不同類型。注意，此模塊聲明兩種類型的字段，整數(shù)字段和小數(shù)字段。

<?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'),

函數(shù)hook_field_settings() 為字段進(jìn)行定義。'form'和'save'運(yùn)算是協(xié)同工作的。使用'form'向字段管理表單添加一個設(shè)定，而'save'則確保此設(shè)定保存賊了內(nèi)容模塊的管理過程中。

注意盡管絕大多數(shù)的字段具有一個數(shù)據(jù)庫欄，其中包括一個稱為“value”的值，你還是可以為一個字段聲明任意數(shù)量的欄位。比如，日期字段可以定義日期數(shù)值（date value），時區(qū)（timezone）及時差（offset）。

<?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',
        ),
      );
  }
}
?>

Hook_field() 定義字段存儲方式及內(nèi)容顯示方式。'view'運(yùn)算定義數(shù)據(jù)的顯示方式。一般來說視圖使用函數(shù)content_format()，應(yīng)返回默認(rèn)的格式。

當(dāng)節(jié)點(diǎn)驗(yàn)證后，'validate' 運(yùn)算為字段提供驗(yàn)證字段數(shù)據(jù)的機(jī)會。$field 參量包含字段的設(shè)定，在驗(yàn)證過程中使用的話將會有所幫助。

內(nèi)容模塊將這些運(yùn)算中的每一個都調(diào)用兩次，第一次它們各司其職，第二次則是內(nèi)容模塊本身，即在字段上執(zhí)行自身的運(yùn)算。

<?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;
  }
}
?>

CCK使用格式化程序以允許字段定義一種或多種信息顯示方式。'default（默認(rèn)）'的格式化程序用于標(biāo)準(zhǔn)節(jié)點(diǎn)的顯示，但你可以在主題中使用其他的格式化程序，一不同的方式顯示它。

主題中格式化程序輸出的顯示方式是：

print content_format('field_example', $field_example[0], 'trimmed');

當(dāng)字段使用于Views時，所有可用的格式化程序會顯示為選項。

<?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;
  }
}
?>

與字段一樣，窗件可以為自身聲明信息。它們需要判別可以處理的字段類型?？梢杂卸嘤谝粋€的窗件，而且每個窗件都可以處理一種以上的字段。

<?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'),
    ),
  );
}
?>

hook_widget_settings() 與hook_field_settings()幾乎相同，唯一不同就是前者允許你定義窗件的行為方式。

某些字段和窗件設(shè)定經(jīng)由內(nèi)容模塊處理，因此它們在此沒有被定義。內(nèi)容模塊處理表單元素，為每個字段收集字段標(biāo)簽，幫助文本和weight。

<?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');
  }
}
?>

Hook_widget() 控制窗件的行為，主要是用于創(chuàng)建和驗(yàn)證編輯表單（edit form）。'process form values' 運(yùn)算應(yīng)用作在表單數(shù)值被存儲之前對它們進(jìn)行操作。此運(yùn)算在預(yù)覽前被呼叫，因此以正確預(yù)覽數(shù)值為目的的操作都要先經(jīng)過此運(yùn)算的處理。

注意，表單元素的頂層必須包括#tree => TRUE ，這樣表單就會保留所有的次級元素（sub-element）。參見FAPI資料進(jìn)一步了解 #tree。

<?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".
*/
?>

請注意，所有的Hook函數(shù)都是必須的。CCK希望他們都被表現(xiàn)出來，缺一不可。