Commit 5f9eda19 authored by Dries's avatar Dries
Browse files

- Patch #930000 by jhodgdon, bleen18: show(), hide(), and render() documentation is misleading.

parent 4bf9e43e
...@@ -5694,13 +5694,17 @@ function drupal_render_children(&$element, $children_keys = NULL) { ...@@ -5694,13 +5694,17 @@ function drupal_render_children(&$element, $children_keys = NULL) {
} }
/** /**
* Render and print an element. * Render an element.
* *
* This function renders an element using drupal_render(). The top level * This function renders an element using drupal_render(). The top level
* element is always rendered even if hide() had been previously used on it. * element is shown with show() before rendering, so it will always be rendered
* even if hide() had been previously used on it.
* *
* Any nested elements are only rendered if they haven't been rendered before * @param $element
* or if they have been re-enabled with show(). * The element to be rendered.
*
* @return
* The rendered element.
* *
* @see drupal_render() * @see drupal_render()
* @see show() * @see show()
...@@ -5721,6 +5725,21 @@ function render(&$element) { ...@@ -5721,6 +5725,21 @@ function render(&$element) {
/** /**
* Hide an element from later rendering. * Hide an element from later rendering.
* *
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to hide an
* element, be sure to call hide() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
*
* @param $element
* The element to be hidden.
*
* @return
* The element.
*
* @see render() * @see render()
* @see show() * @see show()
*/ */
...@@ -5730,10 +5749,25 @@ function hide(&$element) { ...@@ -5730,10 +5749,25 @@ function hide(&$element) {
} }
/** /**
* Show a hidden or already printed element from later rendering. * Show a hidden element for later rendering.
*
* You can also use render($element), which shows the element while rendering
* it.
*
* The first time render() or drupal_render() is called on an element tree,
* as each element in the tree is rendered, it is marked with a #printed flag
* and the rendered children of the element are cached. Subsequent calls to
* render() or drupal_render() will not traverse the child tree of this element
* again: they will just use the cached children. So if you want to show an
* element, be sure to call show() on the element before its parent tree is
* rendered for the first time, as it will have no effect on subsequent
* renderings of the parent tree.
* *
* Alternatively, render($element) could be used which automatically shows the * @param $element
* element while rendering it. * The element to be shown.
*
* @return
* The element.
* *
* @see render() * @see render()
* @see hide() * @see hide()
......
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