Drupal:CCK字段模块样本

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

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

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

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

/**

@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

@{

/

?>

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




/**



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

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

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




/**



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

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

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




/**



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（默认）'的格式化程序用于标准节点的显示，但你可以在主题中使用其他的格式化程序，一不同的方式显示它。

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



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

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




/**



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;

  }

}

?>

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

/**

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()几乎相同，唯一不同就是前者允许你定义窗件的行为方式。

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

/**

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

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

/**

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函数都是必须的。CCK希望他们都被表现出来，缺一不可。''

category:drupal:cck