summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJennifer Hodgdon2013-07-30 13:04:30 (GMT)
committerJennifer Hodgdon2013-07-30 13:04:30 (GMT)
commit9143ca30006dfd9b05de1834c687d1d2277e5708 (patch)
tree45a929720f522351e933ad30c11bbb7b71320e87
parent9f75c68768a995388a5c49d41a1dfddce37f7277 (diff)
Issue #2031319 by jlindsey15, pplantinga, thedavidmeister, Kingdutch, Kiphaas7: Document that theme() should really be called via drupal_render().
-rw-r--r--core/includes/theme.inc11
1 files changed, 9 insertions, 2 deletions
diff --git a/core/includes/theme.inc b/core/includes/theme.inc
index 84d4752..c276c57 100644
--- a/core/includes/theme.inc
+++ b/core/includes/theme.inc
@@ -793,11 +793,17 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) {
/**
* Generates themed output.
*
- * All requests for themed output must go through this function. It examines
- * the request and routes it to the appropriate
+ * All requests for themed output must go through this function (however,
+ * calling the theme() function directly is strongly discouraged - see next
+ * paragraph). It examines the request and routes it to the appropriate
* @link themeable theme function or template @endlink, by checking the theme
* registry.
*
+ * Avoid calling this function directly. It is preferable to replace direct
+ * calls to the theme() function with calls to drupal_render() by passing a
+ * render array with a #theme key to drupal_render(), which in turn calls
+ * theme().
+ *
* @section sec_theme_hooks Theme Hooks
* Most commonly, the first argument to this function is the name of the theme
* hook. For instance, to theme a taxonomy term, the theme hook name is
@@ -897,6 +903,7 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) {
* An HTML string representing the themed output or FALSE if the passed $hook
* is not implemented.
*
+ * @see drupal_render()
* @see themeable
* @see hook_theme()
* @see template_preprocess()