Commit 06585e6b authored by webchick's avatar webchick
Browse files

#718860 by djac, jhodgdon: Fixes to hook_theme() documentation.

parent 06a1a255
......@@ -1587,91 +1587,92 @@ function hook_permission() {
/**
* Register a module (or theme's) theme implementations.
*
* Modules and themes implementing this return an array of arrays. The key
* to each sub-array is the internal name of the hook, and the array contains
* info about the hook. Each array may contain the following items:
*
* - variables: (required if "render element" not present) An array of
* variables that this theme hook uses. This value allows the theme layer to
* properly utilize templates. Each array key represents the name of the
* variable and the value will be used as the default value if it is not given
* when theme() is called. Template implementations receive these arguments as
* variables in the template file. Function implementations are passed this
* array data in the $variables parameter.
* - render element: (required if "variables" not present) A string that is the
* name of the sole renderable element to pass to the theme function. The
* string represents the name of the "variable" that will hold the renderable
* array inside any optional preprocess or process functions. Cannot be used
* with the "variables" item; only one or the other, not both, can be present
* in a hook's info array.
* - file: The file the implementation resides in. This file will be included
* prior to the theme being rendered, to make sure that the function or
* preprocess function (as needed) is actually loaded; this makes it possible
* to split theme functions out into separate files quite easily.
* - path: Override the path of the file to be used. Ordinarily the module or
* theme path will be used, but if the file will not be in the default path,
* include it here. This path should be relative to the Drupal root
* directory.
* - template: If specified, this theme implementation is a template, and this
* is the template file <b>without an extension</b>. Do not put .tpl.php
* on this file; that extension will be added automatically by the default
* rendering engine (which is PHPTemplate). If 'path', above, is specified,
* the template should also be in this path.
* - function: If specified, this will be the function name to invoke for this
* implementation. If neither file nor function is specified, a default
* function name will be assumed. For example, if a module registers
* the 'node' theme hook, 'theme_node' will be assigned to its function.
* If the chameleon theme registers the node hook, it will be assigned
* 'chameleon_node' as its function.
* - pattern: A regular expression pattern to be used to allow this theme
* implementation to have a dynamic name. The convention is to use __ to
* differentiate the dynamic portion of the theme. For example, to allow
* forums to be themed individually, the pattern might be: 'forum__'. Then,
* when the forum is themed, call: <code>theme(array('forum__' . $tid, 'forum'),
* $forum)</code>.
* - preprocess functions: A list of functions used to preprocess this data.
* Ordinarily this won't be used; it's automatically filled in. By default,
* for a module this will be filled in as template_preprocess_HOOK. For
* a theme this will be filled in as phptemplate_preprocess and
* phptemplate_preprocess_HOOK as well as themename_preprocess and
* themename_preprocess_HOOK.
* - override preprocess functions: Set to TRUE when a theme does NOT want the
* standard preprocess functions to run. This can be used to give a theme
* FULL control over how variables are set. For example, if a theme wants
* total control over how certain variables in the page.tpl.php are set,
* this can be set to true. Please keep in mind that when this is used
* by a theme, that theme becomes responsible for making sure necessary
* variables are set.
* - type: (automatically derived) Where the theme hook is defined:
* 'module', 'theme_engine', or 'theme'.
* - theme path: (automatically derived) The directory path of the theme or
* module, so that it doesn't need to be looked up.
*
* The following parameters are all optional.
*
* @param $existing
* @param array $existing
* An array of existing implementations that may be used for override
* purposes. This is primarily useful for themes that may wish to examine
* existing implementations to extract data (such as arguments) so that
* it may properly register its own, higher priority implementations.
* @param $type
* What 'type' is being processed. This is primarily useful so that themes
* tell if they are the actual theme being called or a parent theme.
* May be one of:
* - module: A module is being checked for theme implementations.
* - base_theme_engine: A theme engine is being checked for a theme which is a parent of the actual theme being used.
* - theme_engine: A theme engine is being checked for the actual theme being used.
* - base_theme: A base theme is being checked for theme implementations.
* - theme: The actual theme in use is being checked.
* Whether a theme, module, etc. is being processed. This is primarily useful
* so that themes tell if they are the actual theme being called or a parent
* theme. May be one of:
* - 'module': A module is being checked for theme implementations.
* - 'base_theme_engine': A theme engine is being checked for a theme that is
* a parent of the actual theme being used.
* - 'theme_engine': A theme engine is being checked for the actual theme
* being used.
* - 'base_theme': A base theme is being checked for theme implementations.
* - 'theme': The actual theme in use is being checked.
* @param $theme
* The actual name of theme that is being being checked (mostly only useful for
* theme engine).
* The actual name of theme, module, etc. that is being being processed.
* @param $path
* The directory path of the theme or module, so that it doesn't need to be
* looked up.
*
* @return
* A keyed array of theme hooks.
* @return array
* An associative array of theme hook information. The keys on the outer
* array are the internal names of the hooks, and the values are arrays
* containing information about the hook. Each array may contain the
* following elements:
* - variables: (required if "render element" not present) An array of
* variables that this theme hook uses. This value allows the theme layer to
* properly utilize templates. Each array key represents the name of the
* variable and the value will be used as the default value if it is not
* given when theme() is called. Template implementations receive these
* arguments as variables in the template file. Function implementations
* are passed this array data in the $variables parameter.
* - render element: (required if "variables" not present) A string that is
* the name of the sole renderable element to pass to the theme function.
* The string represents the name of the "variable" that will hold the
* renderable array inside any optional preprocess or process functions.
* Cannot be used with the "variables" item; only one or the other, not
* both, can be present in a hook's info array.
* - file: The file the implementation resides in. This file will be included
* prior to the theme being rendered, to make sure that the function or
* preprocess function (as needed) is actually loaded; this makes it
* possible to split theme functions out into separate files quite easily.
* - path: Override the path of the file to be used. Ordinarily the module or
* theme path will be used, but if the file will not be in the default path,
* include it here. This path should be relative to the Drupal root
* directory.
* - template: If specified, this theme implementation is a template, and this
* is the template file without an extension. Do not put .tpl.php on this
* file; that extension will be added automatically by the default rendering
* engine (which is PHPTemplate). If 'path', above, is specified, the
* template should also be in this path.
* - function: If specified, this will be the function name to invoke for this
* implementation. If neither file nor function is specified, a default
* function name will be assumed. For example, if a module registers
* the 'node' theme hook, 'theme_node' will be assigned to its function.
* If the chameleon theme registers the node hook, it will be assigned
* 'chameleon_node' as its function.
* - pattern: A regular expression pattern to be used to allow this theme
* implementation to have a dynamic name. The convention is to use __ to
* differentiate the dynamic portion of the theme. For example, to allow
* forums to be themed individually, the pattern might be: 'forum__'. Then,
* when the forum is themed, call:
* @code
* theme(array('forum__' . $tid, 'forum'), $forum)
* @endcode
* - preprocess functions: A list of functions used to preprocess this data.
* Ordinarily this won't be used; it's automatically filled in. By default,
* for a module this will be filled in as template_preprocess_HOOK. For
* a theme this will be filled in as phptemplate_preprocess and
* phptemplate_preprocess_HOOK as well as themename_preprocess and
* themename_preprocess_HOOK.
* - override preprocess functions: Set to TRUE when a theme does NOT want the
* standard preprocess functions to run. This can be used to give a theme
* FULL control over how variables are set. For example, if a theme wants
* total control over how certain variables in the page.tpl.php are set,
* this can be set to true. Please keep in mind that when this is used
* by a theme, that theme becomes responsible for making sure necessary
* variables are set.
* - type: (automatically derived) Where the theme hook is defined:
* 'module', 'theme_engine', or 'theme'.
* - theme path: (automatically derived) The directory path of the theme or
* module, so that it doesn't need to be looked up.
*/
function hook_theme($existing, $type, $theme, $path) {
return array(
......
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