Drupal:CCK字段模块样本
来自站长百科
此例为一个CCK字段模块，它举例说明可用的字段及窗件挂钩(Hook)。此例取自CCK整合包中的field.php文件，其中包括了几个不同的字段，以各种方法使用Hook。
一个模块可以创建一个或多个字段，也可以是一个或多个窗件。选项窗件（optionwidget） 模块可以创建一些窗件但不能创建字段。数字（number）模块可以创建两类字段和一个单个的文本字段窗件。日期（date）模块创建两类字段，每种字段都有三类不同的窗件对应。
内容模块处理node_load() and node_save()运算，所以在大部分情况下字段模块不对这些运算做处理。它们则会定义必要的数据存储方式--在表单中进行收集并在节点中显示出来。
注意，字段和窗件几乎不做任何数据库查询。绝大多数情况下所有必要的查询都会被内容模块处理。
<?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
* @{
*/
?>
绝大多数模块只声明单个字段，但可以创建任意多的不同类型。注意，此模块声明两种类型的字段，整数字段和小数字段。
<?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'),
函数hook_field_settings() 为字段进行定义。'form'和'save'运算是协同工作的。使用'form'向字段管理表单添加一个设定，而'save'则确保此设定保存贼了内容模块的管理过程中。
注意尽管绝大多数的字段具有一个数据库栏，其中包括一个称为“value”的值，你还是可以为一个字段声明任意数量的栏位。比如，日期字段可以定义日期数值（date value），时区（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() 定义字段存储方式及内容显示方式。'view'运算定义数据的显示方式。一般来说视图使用函数content_format()，应返回默认的格式。
当节点验证后，'validate' 运算为字段提供验证字段数据的机会。$field 参量包含字段的设定，在验证过程中使用的话将会有所帮助。
内容模块将这些运算中的每一个都调用两次，第一次它们各司其职，第二次则是内容模块本身，即在字段上执行自身的运算。
<?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（默认）'的格式化程序用于标准节点的显示，但你可以在主题中使用其他的格式化程序，一不同的方式显示它。
主题中格式化程序输出的显示方式是：
print content_format('field_example', $field_example[0], 'trimmed');
当字段使用于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()几乎相同，唯一不同就是前者允许你定义窗件的行为方式。
某些字段和窗件设定经由内容模块处理，因此它们在此没有被定义。内容模块处理表单元素，为每个字段收集字段标签，帮助文本和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() 控制窗件的行为，主要是用于创建和验证编辑表单（edit form）。'process form values' 运算应用作在表单数值被存储之前对它们进行操作。此运算在预览前被呼叫，因此以正确预览数值为目的的操作都要先经过此运算的处理。
注意，表单元素的顶层必须包括#tree => TRUE ，这样表单就会保留所有的次级元素（sub-element）。参见FAPI资料进一步了解 #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函数都是必须的。CCK希望他们都被表现出来，缺一不可。