From 06585e6b6b13804f472cc4d5d7ec47b27b01079f Mon Sep 17 00:00:00 2001
From: Angie Byron <webchick@24967.no-reply.drupal.org>
Date: Thu, 29 Apr 2010 04:57:59 +0000
Subject: [PATCH] #718860 by djac, jhodgdon: Fixes to hook_theme()
documentation.
---
modules/system/system.api.php | 147 +++++++++++++++++-----------------
1 file changed, 74 insertions(+), 73 deletions(-)
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 02cf2747a9ad..b292d3feea2c 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -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(
--
GitLab