Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
project
drupal
Commits
fe2fdd4f
Commit
fe2fdd4f
authored
Apr 28, 2010
by
Dries
Browse files
- Patch
#736326
by jhodgdon, aspilicious: hook_process() and associated hooks are undocumented.
parent
114d70db
Changes
2
Hide whitespace changes
Inline
Side-by-side
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.
*
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment