Time8网络信息网

philquotes 模块需要注册一个主题函数，这个函数接受一个名言内容条目作为参数并把它格式化成 HTML 区块以便显示。

本质上，当注册一个主题时，它声明新的主题钩子，主题系统的其它部分就可以使用或覆写这些钩子。

要注册模块的默认主题，我们需要实现主题注册钩子(hook_theme())，并遵循命名约定 <modulename>_theme()，其中 <modulename> 是模块的名字：

/**
 * Implementation of hook_theme().
 */
function philquotes_theme() {
  return array('philquotes_quote' =>
               array('arguments' =>
                     array('text' => NULL, 'origin' => NULL),),);
}

一言以蔽之，这个函数为主题系统提供了一个全面的列表，说明此模块提供了哪些主题函数（钩子），以及应该如何调用每个函数。

我们也许想让主题钩子具有很多不同的配置。不幸的是，这样做的结果就是hook_theme() 必须返回的数据结构变成了令人恐怖的嵌套关联数组。

在上例中，数组嵌套了三层。我们先看最外层的数组。

最外层的数组包含的元素形式为：'theme_function_name' => configuration_array。在上例中，是这样的：

return array(
  'philquotes_quote' => array(
    // Contents of the array...
  ),
);

theme_function_name 字符串应该是这个模块实现或提供的主题钩子的名字。例如，在我们的例子中，我们将为 philquotes_quote 提供主题。

主题钩子函数的实际名字应是 theme_philquotes_quote()，但注册时 theme_ 部分被省略了。

数组元素的值 configuration_array 是另一个关联数组，它为 Drupal 提供关于此模块如何处理主题的信息。我们稍后研究这个数组。

外层数组可以一次注册多个主题函数。例如，我们可以为某个模块注册三个不同的主题函数，如下：

return array(
  'mytheme_a' => array( /* settings */ );
  'mytheme_b' => array( /* settings */ );
  'mytheme_c' => array( /* settings */ );
);

这段代码注册了三个主题钩子，每个都带有一个配置选项数组。

不过，我们只注册了一个主题钩子，现在我们来仔细看看第二层关联数组。

这个数组包含有关此模块如何实现主题钩子的配置信息。让我们看看philquotes_quote 将具有的配置选项：

'philquotes_quote' => array(
  'arguments' => array( /* parameter info */ ),
),

外层数组中，键 philquotes_quote 的值，本身也是一个关联数组。这个数组中保存的键值都有清晰的定义，hook_theme() API 文档中详细说明了全部 8 个键(key): http://api.drupal.org/api/function/hook_theme/

例如 template 键可以用于指向一个模板文件，此时应该使用这个模板文件而不用主题函数。假如，我们选择使用模板文件 philquotes_quote.tpl.php，我们可以这样进行调用：

p
'philquotes_quote' => array(
  'template' => 'philquotes_quote',
  'arguments' => array( /* parameter info */ ),
),

当我们用这些参数调用 theme_philquotes_quote() 时，它将在 philquotes 模块目录中查找一个名为 philquotes_quote.tpl.php 的文件。（模板文件的扩展名是自动加上的。）

在本例中，arguments数组中的item将被作为参数传递给模板。想看模块模板的例子，参见第八章。

还有其它类似指令，用于添加预处理函数、包含其它 PHP 文件，等等。

不过，对于我们的模块，我们把钩子作为函数来实现。这个数组中唯一的指令是arguments。

对于钩子函数（相对于模板），这个数组条目用于指明哪些参数将被传递给函数。

对于我们的模块钩子，我们只需要两个：text 和 origin。
 

/**
 * Implementation of hook_theme()
 */
function philquotes_theme() {
  return array(
    'philquotes_quote' => array(
      'arguments' => array('text' => NULL, 'origin' => NULL),
     ),
  );
}

arguments数组中的item，形式为：'argument_name' => default_value.

刚开始，我们把两个变量的值都设为 NULL；但是，如果我们想提供更加鲁棒的默认值，就可以在此处设置。

根据这个数组，我们现在就可以构造主题钩子的函数签名了，它将如下所示：
 

function theme_philquotes_quote($text, $origin)

函数名是钩子名前面加上 theme_ 前缀，这里的两个参数与arguments数组的两个元素相对应。

现在我们准备创建这个函数。