diff options
Diffstat (limited to 'modules/system/system.api.php')
| -rw-r--r-- | modules/system/system.api.php | 147 |
1 files changed, 74 insertions, 73 deletions
diff --git a/modules/system/system.api.php b/modules/system/system.api.php index 02cf2747a..b292d3fee 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( |