分类函数
译者：老葛 Eskalate科技公司
下面的部分将解释在你的模块可能用到的分类常用函数。
取回关于词汇表的信息
下面部分所列的内置函数用来取回词汇表的相关信息，信息的形式可以是词汇表数据对象或者是关于这些对象的数组。
taxonomy_get_vocabulary($vid)
这个函数取回一个单个的词汇表（参数$vid是该词汇表的ID），返回的是一个词汇表对象。它还在内部缓存了词汇表对象，这样多次调用同一个词汇表对象并不费事。
taxonomy_get_vocabularies($type)
taxonomy_get_vocabularies($type)函数取回所有的词汇表对象。参数$type将取回的词汇表限定在给定的节点类型上；比如，blog。这个函数返回一个词汇表对象数组。
添加、修改、和删除词汇表
下面的函数用于创建、修改、和删除词汇表。它们返回一个状态代码，代码为Drupal常量SAVED_UPDATED、SAVED_NEW、或SAVED_DELETED中的一个。
taxonomy_save_vocabulary(&$vocabulary)
这个函数用来创建一个新的词汇表或者更新一个已存在的词汇表。参数$vocabulary是一个关联数组（注意它不是一个词汇表对象！），包含以下键：
•
name: 词汇表的名字。
•
description: 词汇表的描述。
•
help: 一个帮助文本，展现在节点创建表单中这个词汇表的字段的下面。
•
nodes: 一个数组，包含了这个词汇表应用到的所有节点类型。
•
hierarchy: 设为0意味着没有层级，设为1意味着单个层级，设为2意味着多层级。
•
relations: 设为0意味着禁用关联词语，设为1意味着允许关联词语。
•
tags: 设为0意味着禁用自由标签，设为1意味着启用自由标签。
•
multiple: 设为0意味着不可以对词语进行多选，设为1意味着允许多选。
•
required:
设为0意味着节点案提交时不选词语也能提交（这将引入一个默认的None词语），设为1意味着节点提交前必须选一个词语。
•
weight: 词汇表的重量；它影响分类字段集中节点提交表单的位置，
•
module: 负责这个词汇表的模块的名字。如果没有传递这个键，那么它的值默认为taxonomy（分类）。
•
vid: 词汇表ID。如果没有传递这个键，那么将创建一个新的词汇表。
taxonomy_save_vocabulary(&$vocabulary)函数返回SAVED_NEW
或者 SAVED_UPDATED。
taxonomy_del_vocabulary($vid)
这个函数的参数$vid是词汇表的ID。删除一个词汇表的同时，会删除词汇表中的所有词语，通过为每个词语调用taxonomy_del_term()来删除词语。taxonomy_del_vocabulary($vid)函数返回SAVED_DELETED。
取回关于词语的信息
下面所列的内置函数用来取回关于词语的信息，一般以对象或者对象数组的形式。
taxonomy_get_term($tid)
这个函数取回一个词语（参数$tid是词语的ID），并返回一个词语对象。它在内部缓存词语对象，所以对同一词语的多次调用并不费事。
taxonomy_get_term_by_name($text)
taxonomy_get_term_by_name($text)函数搜索匹配一个字符串（参数$text是一个字符串）的所有词语。$text中左边或者右边的空格将被除去，而匹配操作将使用SQL的LIKE比较操作符：WHERE
LOWER($text) LIKE LOWER(name)。这个函数返回一个词语对象数组。
taxonomy_node_get_terms($nid, $key)
这个函数查找与某一节点相关联的所有词语。参数$nid是要取回词语的节点的ID，而参数$key默认为tid并且有一个点难以理解。它影响结果返回的方式。taxonomy_node_get_terms($nid, $key)返回一个数组的数组，根据$key生成键。因此，结果数组在默认情况下是以词语ID为键的，但是你也可以使用term_data表(tid,
vid,
name,
description,
weight)中的任意一列。这个函数在内部会为每个节点缓存结果。
taxonomy_node_get_terms_by_vocabulary($nid, $vid, $key)
这个函数将在一个词汇表($vid)中查找与某一节点($nid)相联系的所有词语。参数$key的描述可参看taxonomy_node_get_terms($nid,
$key)中的解释。
添加，修改，和删除词语
下面的函数用于创建、修改、和删除词语。它们返回一个状态代码，其值为Drupal常量SAVED_UPDATED、
SAVED_NEW、 o
SAVED_DELETED中的一个。
taxonomy_save_term(&$term)
这个函数创建一个新的词语或者更新一个已存在的词语。参数$term是一个包含下列键的关联数组（注意它不是一个对象）：
•
name: 词语的名称。
•
description: 词语的描述。Drupal的默认用户接口中用不到该值，但是它可能在你的模块或者其它第3方模块中用到。
•
vid:词语所在的词汇表的ID。
•
weight: 词语的重量。它影响词语下拉列表中各个词语的相对位置。
•
relations: 一个可选的数组，包含与该词语相联系的所有词语的ID。
•
parent: 可以是一个字符串，用来代表父词语的词语ID；或者是一个数组，其元素既或者是字符串，或者是子数组，其中字符串为用来代表父词语的词语ID，而子数组是包含这样字符串的数组。
•
synonyms: 一个可选的字符串，包含以换行字符(/n)分隔的同义词。
•
tid: 词语的ID。如果这个键值为空的话，那么将创建一个新的词语。
这个函数返回SAVED_NEW
或者 SAVED_UPDATED。
taxonomy_del_term($tid)
taxonomy_del_term($tid)函数用来删除一个词语；参数$tid是词语ID。如果一个词语是在一个多层级的词汇表中并且具有子词语，那么子词语也将一同被删除，除非子词语拥有多个父词语。
取回关于词语层级的信息
当使用多层级的词汇表时，下面的函数会非常有用。
taxonomy_get_parents($tid, $key)
这个函数找出一个词语父词语（不包含父词语的父词语）；参数$tid是词语ID。参数$key默认为tid，它是term_data表（tid,
vid,
name,description,
weight）中的一列。taxonomy_get_parents($tid, $key)返回一个关于词语对象的关联数组，其中根据$key生成键值。
taxonomy_get_parents_all($tid)
这个函数找出一个词语的所有祖先；参数$tid是词语的ID。这个函数返回一个包含词语对象的数组。
taxonomy_get_children($tid, $vid, $key)
taxonomy_get_children($tid, $vid, $key)函数找出一个词语的所有孩子。参数$tid是词语的ID。参数$vid是可选的；如果一个词汇表的ID传了进来，那么该词语的孩子将被限制在这个词汇表中（注意，只有当词语有多个父亲，而父词语有位于不同的词汇表时，这才有用，而这种情况非常稀少）。参数$key默认为tid，它是term_data表（tid,
vid,
name,description,
weight）中的一列。这个函数返回一个关于词语对象的关联数组，其中根据$key生成键值。
taxonomy_get_tree($vid, $parent, $depth, $max_depth)
这个函数生成一个词汇表的层级化表示。参数$vid就是用来生成层级树的词汇表的词汇表ID。如果你不想为一个词汇表生成一个整树的话，而只想生成一个以$parent声明的词语ID为根的子树，这时你可以声明参数$parent。参数$depth是内部使用的参数，默认为-1.参数$max_depth是一个整数，用来指出返回树的层级数，它默认为NULL，这意味着所有的层级。这个函数返回了一个包含词语对象的数组，这里向词语对象添加了“depth”
和 “parents”键。“depth” 键是一个整数，用来指示词语在树中所处的层级；而“parents”键是一个数组，包含了词语的所有父词语的词语ID。例如，让我们为表14-3所列的词汇表得到相应的结果，它的词汇表ID为2：
$vid = 2;
print_r($taxonomy_get_tree($vid));
结果如下：
Array (
[0] => stdClass Object (
[tid] => 1
[vid] => 2
[name] => Canada
[description] => A mari usque ad mare.
[weight] => 0
[depth] => 0
[parents] => Array (
[0] => 0 )
)
[1] => stdClass Object (
[tid] => 4
[vid] => 2
[name] => Ontario
[description] => Ut incepit fidelis sic permanet.
[weight] => 0
[depth] => 1
[parents] => Array (
[0] => 1 )
)
[2] => stdClass Object (
[tid] => 5
[vid] => 2
[name] => Toronto
[description] => Diversity Our Strength.
[weight] => 0
[depth] => 2
[parents] => Array (
[0] => 4 )
)
[3] => stdClass Object (
[tid] => 2
[vid] => 2
[name] => British Columbia
[description] => Splendor sine occasu.
[weight] => 0
[depth] => 1
[parents] => Array (
[0] => 1 )
)
[4] => stdClass Object (
[tid] => 3
[vid] => 2
[name] => Vancouver
[description] => By Land, Sea and Air We Prosper.
[weight] => 0
[depth] => 2
[parents] => Array (
[0] => 2 )
)
)
取回关于词语同义词的信息
如果你的模块需要实现对同义词支持的话，下面的函数对你将会非常有用。
taxonomy_get_synonyms($tid)
使用这个函数为给定词语取回关于其同义词的数组。参数$tid是词语的ID。函数返回一个字符串数组；每个字符串就是词语的一个同义词。
taxonomy_get_synonym_root($synonym)
给定参数$synonym一个字符串，这个函数将执行一个针对term_synonym表的精确匹配查询。它返回一个单个词语对象，代表示使用该同义词找到的第一个词语。
查找带有特定词语的节点
有时，你想要一种简单的方式来查询具有特定词语的节点，或者输出这样一个查询的结果。此时，下面的函数将对你非常有用。
这个函数，通过根据给定参数构建和执行一个数据库查询，来查找匹配特定条件的节点。它返回一个指向查询结果的资源标识符。参数$tids是一个词语ID的数组。参数$operator是“or”或者“and”，它用来声明如何解释$tids数组。参数$depth指示分类树中要遍历的层级深度，默认为0，意味着“不要查找$tids中声明词语的所有孩子”。将$depth设为1，意味着查找$tids中声明词语的所有子词语（不包含子词语的孩子，也就是孙子，重孙，等等）。将$depth设为all，意味着查找$tids中声明词语的所有子词语（包含孙子，重孙，等等）。参数$pager是一个布尔值，用来指示是否要对一个节点结果页面使用一个分页器，它默认为TRUE。如果你要生成一个XML种子，你可以将$pager设置为FALSE。参数$order包含了字面上的order语句，它在查询的SQL中使用，而且默认为“n.sticky
DESC, n.created DESC”。
如果你为许多词语进行搜索，那么这个函数是非常耗费数据库资源的；参看本章前面的“使用一个定制查询根据词语对结果分组”部分的另一种解决方式。
taxonomy_render_nodes($result)
如果你使用taxonomy_select_nodes()来查询匹配特定分类条件的节点，那么我们在这里就可以使用taxonomy_render_nodes()作为一个起点来为你的查询创建一个简单输出。
额外资源
许多模块在许多地方都使用了分类，从添加访问控制（taxonomy_access.module），到动态分类浏览（taxonomy_browser.module），再到在一个区块中根据分类词语展示相关联的节点（related_nodes.module）。Drupal参考手册含有关于分类的更多信息，也包含许多基于分类的第3方模块的截图，位于http://drupal.org/handbook/modules/taxonomy。
我们鼓励你尝试views模块，特别是在主体化分类列表时（http://drupal.org/project/views）。
总结
读完本章后，你应该能够
• 理解什么是分类
• 理解词语，词汇表，以及它们不同的选项
• 扁平结构，层级结构，和多层级结构词汇表之间的区别
• 使用AND
和 OR构建URL来对分类词语进行搜索
• 为分类词语和词语联合的RSS种子构建URL
• 理解分类是如何存储的
• 知道如何在你自己的模块中使用词汇表
• 将对分类所做的修改通知给你的模块
•
构建针对分类表的定制查询