Skip to content

GitLab

Commit fe2fdd4f authored by Dries's avatar Dries
Browse files

- Patch #736326 by jhodgdon, aspilicious: hook_process() and associated hooks are undocumented.

parent 114d70db
Hide whitespace changes
Inline Side-by-side
Showing with 181 additions and 121 deletions
includes/theme.inc
View file @ fe2fdd4f
......@@ -621,130 +621,88 @@ function list_themes($refresh = FALSE) {
}
/**
* Generate the themed output.
*
* All requests for theme hooks must go through this function. It examines
* the request and routes it to the appropriate theme function. The theme
* registry is checked to determine which implementation to use, which may
* be a function or a template.
*
* If the implementation is a template, the following functions may be used to
* modify the $variables array. They are processed in two distinct phases;
* "preprocess" and "process" functions. The order listed here is the order in
* which they execute.
*
* - template_preprocess(&$variables)
* This sets a default set of variables for all template implementations.
*
* - template_preprocess_HOOK(&$variables)
* This is the first preprocessor called specific to the hook; it should be
* implemented by the module that registers it.
*
* - MODULE_preprocess(&$variables)
* This will be called for all templates; it should only be used if there
* is a real need. It's purpose is similar to template_preprocess().
*
* - MODULE_preprocess_HOOK(&$variables)
* This is for modules that want to alter or provide extra variables for
* theming hooks not registered to itself. For example, if a module named
* "foo" wanted to alter the $classes_array variable for the hook "node" a
* preprocess function of foo_preprocess_node() can be created to intercept
* and alter the variable.
*
* - ENGINE_engine_preprocess(&$variables)
* This function should only be implemented by theme engines and exists
* so that it can set necessary variables for all hooks.
*
* - ENGINE_engine_preprocess_HOOK(&$variables)
* This is the same as the previous function, but it is called for a single
* theming hook.
*
* - THEME_preprocess(&$variables)
* This is for themes that want to alter or provide extra variables. For
* example, if a theme named "foo" wanted to alter the $classes_array variable
* for the hook "node" a preprocess function of foo_preprocess_node() can be
* created to intercept and alter the variable.
*
* - THEME_preprocess_HOOK(&$variables)
* The same applies from the previous function, but it is called for a
* specific hook.
*
* - template_process(&$variables)
* This sets a default set of variables for all template implementations.
*
* - template_process_HOOK(&$variables)
* This is the first processor called specific to the hook; it should be
* implemented by the module that registers it.
*
* - MODULE_process(&$variables)
* This will be called for all templates; it should only be used if there
* is a real need. It's purpose is similar to template_process().
*
* - MODULE_process_HOOK(&$variables)
* This is for modules that want to alter or provide extra variables for
* theming hooks not registered to itself. For example, if a module named
* "foo" wanted to alter the $classes_array variable for the hook "node" a
* process function of foo_process_node() can be created to intercept
* and alter the variable.
*
* - ENGINE_engine_process(&$variables)
* This function should only be implemented by theme engines and exists
* so that it can set necessary variables for all hooks.
*
* - ENGINE_engine_process_HOOK(&$variables)
* This is the same as the previous function, but it is called for a single
* theming hook.
*
* - ENGINE_process(&$variables)
* This is meant to be used by themes that utilize a theme engine. It is
* provided so that the processor is not locked into a specific theme.
* This makes it easy to share and transport code but theme authors must be
* careful to prevent fatal re-declaration errors when using sub-themes that
* have their own processor named exactly the same as its base theme. In
* the default theme engine (PHPTemplate), sub-themes will load their own
* template.php file in addition to the one used for its parent theme. This
* increases the risk for these errors. A good practice is to use the engine
* name for the base theme and the theme name for the sub-themes to minimize
* this possibility.
*
* - ENGINE_process_HOOK(&$variables)
* The same applies from the previous function, but it is called for a
* specific hook.
*
* - THEME_process(&$variables)
* These functions are based upon the raw theme; they should primarily be
* used by themes that do not use an engine or by sub-themes. It serves the
* same purpose as ENGINE_process().
*
* - THEME_process_HOOK(&$variables)
* The same applies from the previous function, but it is called for a
* specific hook.
*
* If the implementation is a function, only the hook-specific preprocess
* Generates themed output.
*
* All requests for themed output must go through this function. It examines
* the request and routes it to the appropriate theme function or template, by
* checking the theme registry.
*
* The first argument to this function is the name of the theme hook. For
* instance, to theme a table, the theme hook name is 'table'. By default, this
* theme hook could be implemented by a function called 'theme_table' or a
* template file called 'table.tpl.php', but hook_theme() can override the
* default function or template name.
*
* If the implementation is a template file, several functions are called
* before the template file is invoked, to modify the $variables array. These
* fall into the "preprocessing" phase and the "processing" phase, and are
* executed (if they exist), in the following order (note that in the following
* list, HOOK indicates the theme hook name, MODULE indicates a module name,
* THEME indicates a theme name, and ENGINE indicates a theme engine name):
* - template_preprocess(&$variables, $hook): Creates a default set of variables
* for all theme hooks.
* - template_preprocess_HOOK(&$variables): Should be implemented by
* the module that registers the theme hook, to set up default variables.
* - MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all
* implementing modules.
* - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on
* all implementing modules, so that modules that didn't define the theme hook
* can alter the variables.
* - ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to
* set necessary variables for all theme hooks.
* - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set
* necessary variables for the particular theme hook.
* - THEME_preprocess(&$variables, $hook): Allows the theme to set necessary
* variables for all theme hooks.
* - THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary
* variables specific to the particular theme hook.
* - template_process(&$variables, $hook): Creates a default set of variables
* for all theme hooks.
* - template_process_HOOK(&$variables): This is the first processor specific
* to the theme hook; it should be implemented by the module that registers
* it.
* - MODULE_process(&$variables, $hook): hook_process() is invoked on all
* implementing modules.
* - MODULE_process_HOOK(&$variables): hook_process_HOOK() is invoked on
* on all implementing modules, so that modules that didn't define the theme
* hook can alter the variables.
* - ENGINE_engine_process(&$variables, $hook): Allows the theme engine to set
* necessary variables for all theme hooks.
* - ENGINE_engine_process_HOOK(&$variables): Allows the theme engine to set
* necessary variables for the particular theme hook.
* - ENGINE_process(&$variables, $hook): Allows the theme engine to process the
* variables.
* - ENGINE_process_HOOK(&$variables): Allows the theme engine to process the
* variables specific to the theme hook.
* - THEME_process(&$variables, $hook): Allows the theme to process the
* variables.
* - THEME_process_HOOK(&$variables): Allows the theme to process the
* variables specific to the theme hook.
*
* If the implementation is a function, only the theme-hook-specific preprocess
* and process functions (the ones ending in _HOOK) are called from the
* above list. This is because theme hooks with function implementations
* need to be fast, and calling the non-hook-specific preprocess and process
* functions for them would incur a noticeable performance penalty.
* list above. This is because theme hooks with function implementations
* need to be fast, and calling the non-theme-hook-specific preprocess and
* process functions for them would incur a noticeable performance penalty.
*
* There are two special variables that these preprocess and process functions
* can set:
* 'theme_hook_suggestion' and 'theme_hook_suggestions'. These will be merged
* together to form a list of 'suggested' alternate hooks to use, in
* reverse order of priority. theme_hook_suggestion will always be a higher
* priority than items in theme_hook_suggestions. theme() will use the
* highest priority implementation that exists. If none exists, theme() will
* use the implementation for the theme hook it was called with. These
* suggestions are similar to and are used for similar reasons as calling
* theme() with an array as the $hook parameter (see below). The difference
* is whether the suggestions are determined by the code that calls theme() or
* by a preprocess or process function.
* can set: 'theme_hook_suggestion' and 'theme_hook_suggestions'. These will be
* merged together to form a list of 'suggested' alternate theme hooks to use,
* in reverse order of priority. theme_hook_suggestion will always be a higher
* priority than items in theme_hook_suggestions. theme() will use the
* highest priority implementation that exists. If none exists, theme() will
* use the implementation for the theme hook it was called with. These
* suggestions are similar to and are used for similar reasons as calling
* theme() with an array as the $hook parameter (see below). The difference
* is whether the suggestions are determined by the code that calls theme() or
* by a preprocess or process function.
*
* @param $hook
* The name of the theme hook to call. If the name contains a
* double-underscore ('__') and there isn't an implementation for the full
* name, the part before the '__' is checked. This allows a fallback to a more
* generic implementation. For example, if theme('links__node', ...) is
* called, but there is no implementation of that hook, then the 'links'
* called, but there is no implementation of that theme hook, then the 'links'
* implementation is used. This process is iterative, so if
* theme('links__contextual__node', ...) is called, theme() checks for the
* following implementations, and uses the first one that exists:
......@@ -753,20 +711,20 @@ function list_themes($refresh = FALSE) {
* - links
* This allows themes to create specific theme implementations for named
* objects and contexts of otherwise generic theme hooks. The $hook parameter
* may also be an array, in which case the first hook that has an
* may also be an array, in which case the first theme hook that has an
* implementation is used. This allows for the code that calls theme() to
* explicitly specify the fallback order in a situation where using the '__'
* convention is not desired or insufficient.
*
* convention is not desired or is insufficient.
* @param $variables
* An associative array of variables to merge with defaults from the theme
* registry, pass to preprocess and process functions for modification, and
* finally, pass to the function or template implementing the theme hook.
* Alternatively, this can be a renderable array, in which case, its properties
* are mapped to variables expected by the theme hook implementations.
* Alternatively, this can be a renderable array, in which case, its
* properties are mapped to variables expected by the theme hook
* implementations.
*
* @return
* An HTML string that generates the themed output.
* An HTML string representing the themed output.
*/
function theme($hook, $variables = array()) {
static $hooks = NULL;
......
modules/system/theme.api.php
View file @ fe2fdd4f
......@@ -94,6 +94,108 @@ function hook_form_system_theme_settings_alter(&$form, &$form_state) {
);
}
/**
* Preprocess theme variables.
*
* This hook allows modules to preprocess theme variables for theme templates.
* It is called for all invocations of theme(), to allow modules to add to
* or override variables for all theme hooks.
*
* @param $variables
* The variables array (modify in place).
* @param $hook
* The name of the theme hook.
*/
function hook_preprocess(&$variables, $hook) {
static $hooks;
// Add contextual links to the variables, if the user has permission.
if (!user_access('access contextual links')) {
return;
}
if (!isset($hooks)) {
$hooks = theme_get_registry();
}
// Determine the primary theme function argument.
if (isset($hooks[$hook]['variables'])) {
$keys = array_keys($hooks[$hook]['variables']);
$key = $keys[0];
}
else {
$key = $hooks[$hook]['render element'];
}
if (isset($variables[$key])) {
$element = $variables[$key];
}
if (isset($element) && is_array($element) && !empty($element['#contextual_links'])) {
$variables['title_suffix']['contextual_links'] = contextual_links_view($element);
if (!empty($variables['title_suffix']['contextual_links'])) {
$variables['classes_array'][] = 'contextual-links-region';
}
}
}
/**
* Preprocess theme variables for a specific theme hook.
*
* This hook allows modules to preprocess theme variables for a specific theme
* hook. It should only be used if a module needs to override or add to the
* theme preprocessing for a theme hook it didn't define.
*
* @param $variables
* The variables array (modify in place).
*/
function hook_preprocess_HOOK(&$variables) {
// This example is from rdf_preprocess_image(). It adds an RDF attribute
// to the image hook's variables.
$variables['attributes']['typeof'] = array('foaf:Image');
}
/**
* Process theme variables.
*
* This hook allows modules to process theme variables for theme templates.
* It is called for all invocations of theme(), to allow modules to add to
* or override variables for all theme hooks.
*
* @param $variables
* The variables array (modify in place).
* @param $hook
* The name of the theme hook.
*/
function hook_process(&$variables, $hook) {
// Wraps variables in RDF wrappers.
if (!empty($variables['rdf_template_variable_attributes_array'])) {
foreach ($variables['rdf_template_variable_attributes_array'] as $variable_name => $attributes) {
$context = array(
'hook' => $hook,
'variable_name' => $variable_name,
'variables' => $variables,
);
$variables[$variable_name] = theme('rdf_template_variable_wrapper', array('content' => $variables[$variable_name], 'attributes' => $attributes, 'context' => $context));
}
}
}
/**
* Process theme variables for a specific theme hook.
*
* This hook allows modules to process theme variables for a specific theme
* hook. It should only be used if a module needs to override or add to the
* theme processing for a theme hook it didn't define.
*
* @param $variables
* The variables array (modify in place).
*/
function hook_process_HOOK(&$variables) {
$variables['classes'] .= ' my_added_class';
}
/**
* Respond to themes being enabled.
*
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment