drupal_render()只是对theme()的调用做了包装，真正做任务的还是theme()。
function theme($hook, $variables = array()) {
... ...
}
theme()的开头检查了module_load_all()是否有执行。theme()只能在所有模块装入后才能执行。
// If called before all modules are loaded, we do not necessarily have a full
// theme registry to work with, and therefore cannot process the theme
// request properly. See also _theme_load_registry().
if (!module_load_all(NULL) && !defined(‘MAINTENANCE_MODE‘)) {
throw new Exception(t(‘theme() may not be called until all modules are loaded.‘));
}
theme_get_registry()返回所有的theme hooks。
$hooks = theme_get_registry(FALSE);
参数$hook可以是一个数组，包含所有可用的备选theme hook。theme()会取第一个存在的theme hook。
// If an array of hook candidates were passed, use the first one that has an
// implementation.
if (is_array($hook)) {
foreach ($hook as $candidate) {
if (isset($hooks[$candidate])) {
break;
}
}
$hook = $candidate;
}
处理theme hook suggestion。什么是theme hook
suggestion？以请求q=node/sports/5为例，可以优先匹配node__sports__5，再匹配node__sports，最后再匹配node。如果存在node__sports__5的theme
hook，则后面的就不予考虑，后面的以此类推。注意theme hook suggestion是以双下划线分开的。
// If there‘s no implementation, check for more generic fallbacks. If there‘s
// still no implementation, log an error and return an empty string.
if (!isset($hooks[$hook])) {
// Iteratively strip everything after the last ‘__‘ delimiter, until an
// implementation is found.
while ($pos = strrpos($hook, ‘__‘)) {
$hook = substr($hook, 0, $pos);
if (isset($hooks[$hook])) {
break;
}
}
if (!isset($hooks[$hook])) {
// Only log a message when not trying theme suggestions ($hook being an
// array).
// 只有$hook是数组的时候才记录日志信息
if (!isset($candidate)) {
watchdog(‘theme‘, ‘Theme hook %hook not found.‘, array(‘%hook‘ => $hook), WATCHDOG_WARNING);
}
return ‘‘;
}
}
$info保存当前hook信息。$theme_path是一个全局变量，在theme()执行过程中会替换为当前theme
hook对应的路径，theme()后面会还原回来。
$info = $hooks[$hook];
global $theme_path;
$temp = $theme_path;
// point path_to_theme() to the currently used theme path:
$theme_path = $info[‘theme path‘];
引入$info[‘includes‘]相关文件。
// Include a file if the theme function or variable processor is held
// elsewhere.
if (!empty($info[‘includes‘])) {
foreach ($info[‘includes‘] as $include_file) {
include_once DRUPAL_ROOT . ‘/‘ . $include_file;
}
}
重新整理$variables数组。
// If a renderable array is passed as $variables, then set $variables to
// the arguments expected by the theme function.
if (isset($variables[‘#theme‘]) || isset($variables[‘#theme_wrappers‘])) {
$element = $variables;
$variables = array();
if (isset($info[‘variables‘])) {
foreach (array_keys($info[‘variables‘]) as $name) {
if (isset($element["#$name"])) {
$variables[$name] = $element["#$name"];
}
}
}
else {
$variables[$info[‘render element‘]] = $element;
}
}// Merge in argument defaults.
if (!empty($info[‘variables‘])) {
$variables += $info[‘variables‘];
}
elseif (!empty($info[‘render element‘])) {
$variables += array($info[‘render element‘] => array());
}
定义theme hook时，允许定义theme hook执行时必需的变量和默认值。可以使用render
element定义单个变量，也可以用variables定义多个变量。用render element定义单个变量的例子：
function practice_theme() {
return array(
‘flash_messages‘ => array(
‘render element‘ => ‘messages‘,
‘template‘ => ‘flash_messages‘,
),
);
}
// 整理后的$variables大致是这样：
$variables = array(
‘messages‘ => $element,
);
用variables定义多个变量的例子：
function practice_theme() {
return array(
‘flash_messages‘ => array(
‘variables‘ => array(
‘foo‘ => array(),
‘bar‘ => array()
),
‘template‘ => ‘flash_messages‘,
),
);
}
// 整理后的$variables大致是这样：
$variables = array(
‘foo‘ => isset($element[‘foo‘]) ? $element[‘foo‘] : array(),
‘bar‘ => isset($element[‘bar‘]) ? $element[‘bar‘] : array(),
);
如果$info[‘base hook‘]不为空，则后面调用的preprocess functions和process
functions要是base hook的，不能是当前$hook的。但还是要保证theme_hook_suggestion是当前$hook。
// If the hook is a suggestion of a base hook, invoke the variable processors of
// the base hook, but retain the suggestion as a high priority suggestion to
// be used unless overridden by a variable processor function.
if (isset($info[‘base hook‘])) {
$base_hook = $info[‘base hook‘];
$base_hook_info = $hooks[$base_hook];
// Include files required by the base hook, since its variable processors
// might reside there.
if (!empty($base_hook_info[‘includes‘])) {
foreach ($base_hook_info[‘includes‘] as $include_file) {
include_once DRUPAL_ROOT . ‘/‘ . $include_file;
}
}
if (isset($base_hook_info[‘preprocess functions‘]) || isset($base_hook_info[‘process functions‘])) {
$variables[‘theme_hook_suggestion‘] = $hook;
$hook = $base_hook;
$info = $base_hook_info;
}
}
调用preprocess functions和process
functions。这两类函数有两个目的，一是处理$variables，二是处理theme hook
suggestion。theme_hook_suggestion的优先级大于theme_hook_suggestions（注意是suggestion复数），theme_hook_suggestions再安装FILO先进后出的原则匹配，最后加入的优先级最高。
// Invoke the variable processors, if any. The processors may specify
// alternate suggestions for which hook‘s template/function to use.
if (isset($info[‘preprocess functions‘]) || isset($info[‘process functions‘])) {
$variables[‘theme_hook_suggestions‘] = array();
foreach (array(‘preprocess functions‘, ‘process functions‘) as $phase) {
if (!empty($info[$phase])) {
foreach ($info[$phase] as $processor_function) {
if (function_exists($processor_function)) {
// We don‘t want a poorly behaved process function changing $hook.
$hook_clone = $hook; // 不要让某些人将$hook搞坏了
$processor_function($variables, $hook_clone);
}
}
}
}
// If the preprocess/process functions specified hook suggestions, and the
// suggestion exists in the theme registry, use it instead of the hook that
// theme() was called with. This allows the preprocess/process step to
// route to a more specific theme hook. For example, a function may call
// theme(‘node‘, ...), but a preprocess function can add ‘node__article‘ as
// a suggestion, enabling a theme to have an alternate template file for
// article nodes. Suggestions are checked in the following order:
// - The ‘theme_hook_suggestion‘ variable is checked first. It overrides
// all others.
// - The ‘theme_hook_suggestions‘ variable is checked in FILO order, so the
// last suggestion added to the array takes precedence over suggestions
// added earlier.
$suggestions = array();
if (!empty($variables[‘theme_hook_suggestions‘])) {
$suggestions = $variables[‘theme_hook_suggestions‘];
}
if (!empty($variables[‘theme_hook_suggestion‘])) {
$suggestions[] = $variables[‘theme_hook_suggestion‘];
}
foreach (array_reverse($suggestions) as $suggestion) {
if (isset($hooks[$suggestion])) {
$info = $hooks[$suggestion];
break;
}
}
}
产生输出可以用函数也可以用模版。$info[‘function‘]表示调用函数产生输出。
if (isset($info[‘function‘])) {
if (function_exists($info[‘function‘])) {
$output = $info[‘function‘]($variables);
}
}
$info[‘template‘]表示使用模板产生输出。theme_render_template()是默认的模板输出函数，.tpl.php是默认的模板文件扩展名。
// Default render function and extension.
$render_function = ‘theme_render_template‘;
$extension = ‘.tpl.php‘;
不同的theme engine允许有不同的模板输出函数和模板文件扩展名。
// The theme engine may use a different extension and a different renderer.
global $theme_engine;
if (isset($theme_engine)) {
if ($info[‘type‘] != ‘module‘) {
if (function_exists($theme_engine . ‘_render_template‘)) {
$render_function = $theme_engine . ‘_render_template‘;
}
$extension_function = $theme_engine . ‘_extension‘;
if (function_exists($extension_function)) {
$extension = $extension_function();
}
}
}
通过template_preprocess()为$varialbes添加默认变量。使用$variables[‘directory‘]判断template_preprocess()有没有执行过。
// In some cases, a template implementation may not have had
// template_preprocess() run (for example, if the default implementation is
// a function, but a template overrides that default implementation). In
// these cases, a template should still be able to expect to have access to
// the variables provided by template_preprocess(), so we add them here if
// they don‘t already exist. We don‘t want to run template_preprocess()
// twice (it would be inefficient and mess up zebra striping), so we use the
// ‘directory‘ variable to determine if it has already run, which while not
// completely intuitive, is reasonably safe, and allows us to save on the
// overhead of adding some new variable to track that.
if (!isset($variables[‘directory‘])) {
$default_template_variables = array();
template_preprocess($default_template_variables, $hook);
$variables += $default_template_variables;
}
调用模板输出函数$render_function产生输出内容。
// Render the output using the template file.
$template_file = $info[‘template‘] . $extension;
if (isset($info[‘path‘])) {
$template_file = $info[‘path‘] . ‘/‘ . $template_file;
}
$output = $render_function($template_file, $variables);
Drupal使用PHPTemplate作为默认的主题引擎。PHPTemplate的输出函数theme_render_template()很简单，include模板文件就OK。
/**
* Renders a system default template, which is essentially a PHP template.
*
* @param $template_file
* The filename of the template to render.
* @param $variables
* A keyed array of variables that will appear in the output.
*
* @return
* The output generated by the template.
*/
function theme_render_template($template_file, $variables) {
// Extract the variables to a local namespace
extract($variables, EXTR_SKIP);// Start output buffering
ob_start();// Include the template file
include DRUPAL_ROOT . ‘/‘ . $template_file;// End buffering and return its contents
return ob_get_clean();
}
最后，theme()还原$theme_path，返回输出$output。
// restore path_to_theme()
$theme_path = $temp;
return $output;
解析theme(),码迷,mamicode.com