预处理函数仅适用于模板形式的主题钩子.它的主要作用是设置模板文件(*.tpl.php)中所用到的变量。在预处理器(Preprocessor)中,一般涉及不到普通的主题函数。
对于单个主题钩子,可以有多个预处理器。内核,模块,引擎,主题,每层都可以有一个预处理器,来逐步的构建显示在模板文件中的变量集。通过将大部分逻辑放到这些预处理器中,可使得模板文件更加简洁,易于使用。
下面是预期的预处理器。当它们同时存在时,按照下面的顺序运行:
- template_preprocess -这个是由内核提供的,也是始终存在的。这里声称的变量在所有的模板钩子中都可以使用.
- template_preprocess_hook -实现了主题钩子的内核或者模块提供该处理器。特定于某个钩子的变量,通常首先在这里生成。
- moduleName_preprocess -不要将这个与前面的预处理器混淆了。对于那些最初没有实现钩子的模块,它允许影响变量集。它将在所有的钩子中运行。
- moduleName_preprocess_hook -和第3个一样,但是特定于某个钩子。
- engineName_engine_preprocess -主题引擎的预处理器。适用于所有的钩子。
- engineName_engine_preprocess_hook -主题引擎的另一个预处理器,特定于单个钩子。
- engineName_preprocess -这是第一个可以在主题内部使用的预处理器。命名方式为,主题所用引擎名称+预处理器名。适用于所有的钩子。
- engineName_preprocess_hook -这个和第7个一样,但是特定于单个钩子。
- themeName_preprocess -命名方式为:主题名+预处理器名。适用于所有的钩子。
- themeName_preprocess_hook -与前者一样,但是特定于单个钩子。
这里有多种方式可修改变量集。在大多数情况下,只有前两个预处理器存在。第一个,添加了所有的默认基本变量,而第2个添加了特定于该主题钩子的变量。第3方模块,如果用到了第3和第4个预处理器的话,需要添加注释对其进行详细说明。这里就不对此展开讨论了。
尽管可以这样做,但是默认的PHPTemplate没有对变量集进行修改。
从列表中的第7个开始,所有的预处理器都是放置在主题中的。这个预处理器列表最多是可以超过10个的,那就是使用子主题,子主题是基于第9和第10个预处理的前缀主题名的,但是这种情况在实际中很少用到。
注意:
- 一般推荐在基主题的预处理器中使用引擎名称。这有利于代码在主题之间的迁移,同时有利于在Drupal.org上发布代码片断。
- 而只有在子主题(sub-themes)中才使用主题名称。这将减少潜在的重名冲突,在PHP中是不允许重名的。
- 为了识别你主题的预处理器,与钩子相关联的模板必须位于主题内部。如果存在默认的模板的话,将其拷贝到你的主题下面,并清空注册表。
注意,这些函数中都没有返回值,所有的变量都是通过引用传递的,前面都有符号“&”,比如&$var。
由于这里适用的是引用方式,所以在前面设置的变量,在后面的预处理器中都会存在,所以你一定要小心,不要在这里出什么乱子。重置以前的变量是可以的,但重置以后,你总会疑神疑鬼,感情哪里会出漏子。
这个例子,来自于实现了钩子"foo"的模块:
[syntaxHighLighter brush="php"]function template_preprocess_foo(&$variables) {
$variables['foo_list'] = array(
'list item 1',
'list item 2',
'list item 3',
);
}[/syntaxHighLighter]
在主题的预处理器中添加变量集:
[syntaxHighLighter brush="php"]function drop_preprocess_foo(&$variables) {
// Do not do this unless you mean to:
$variables['foo_list'] = array('list item 4');
// Instead do this:
$variables['foo_list'][] = 'list item 4';
}[/syntaxHighLighter]
在模板文件中使用的变量,就是$variables的键。所以,在上面的例子中,在模板文件中可用的变量就是$foo_list。