Issue #1021568 by skottler, sven.lauer, jhodgdon: Fixed hook_theme() variables vs render elements.

1 files changed, 26 insertions, 15 deletions

diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index c760462fb..0ae9b1187 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -1971,6 +1971,12 @@ function hook_permission() {
 /**
  * Register a module (or theme's) theme implementations.
  *
+ * The implementations declared by this hook have two purposes: either they
+ * specify how a particular render array is to be rendered as HTML (this is
+ * usually the case if the theme function is assigned to the render array's
+ * #theme property), or they return the HTML that should be returned by an
+ * invocation of theme().
+ *
  * The following parameters are all optional.
  *
  * @param array $existing
@@ -1998,21 +2004,26 @@ function hook_permission() {
  * @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.
+ *   containing information about the hook. Each information array must contain
+ *   either a 'variables' element or a 'render element' element, but not both.
+ *   Use 'render element' if you are theming a single element or element tree
+ *   composed of elements, such as a form array, a page array, or a single
+ *   checkbox element. Use 'variables' if your theme implementation is
+ *   intended to be called directly through theme() and has multiple arguments
+ *   for the data and style; in this case, the variables not supplied by the
+ *   calling function will be given default values and passed to the template
+ *   or theme function. The returned theme information array can contain the
+ *   following key/value pairs:
+ *   - variables: (see above) Each array key is the name of the variable, and
+ *     the value given is used as the default value if the function calling
+ *     theme() does not supply it. Template implementations receive each array
+ *     key as a variable in the template file (so they must be legal PHP
+ *     variable names). Function implementations are passed the variables in a
+ *     single $variables function argument.
+ *   - render element: (see above) The name of the renderable element or element
+ *     tree to pass to the theme function. This name is used as the name of the
+ *     variable that holds the renderable element or tree in preprocess and
+ *     process functions.
  *   - 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