|5 – 8||
Renders HTML given a structured array tree.
Recursively iterates over each of the array elements, generating HTML code.
HTML generation is controlled by two properties containing theme functions, #theme and #theme_wrappers.
#theme is the theme function called first. If it is set and the element has any children, they have to be rendered there. For elements that are not allowed to have any children, e.g. buttons or textfields, it can be used to render the element itself. If #theme is not present and the element has children, they are rendered and concatenated into a string by drupal_render_children().
The #theme_wrappers property contains an array of theme functions which will be called, in order, after #theme has run. These can be used to add further markup around the rendered children; e.g., fieldsets add the required markup for a fieldset around their rendered child elements. All wrapper theme functions have to include the element's #children property in their output, as it contains the output of the previous theme functions and the rendered children.
For example, for the form element type, by default only the #theme_wrappers property is set, which adds the form markup around the rendered child elements of the form. This allows you to set the #theme property on a specific form to a custom theme function, giving you complete control over the placement of the form's children while not at all having to deal with the form markup itself.
drupal_render() can optionally cache the rendered output of elements to improve performance. To use drupal_render() caching, set the element's #cache property to an associative array with one or several of the following keys:
This function is usually called from within another function, like drupal_get_form() or a theme function. Elements are sorted internally using uasort(). Since this is expensive, when passing already sorted elements to drupal_render(), for example from a database query, set $elements['#sorted'] = TRUE to avoid sorting them a second time.
drupal_render() flags each element with a '#printed' status to indicate that the element has been rendered, which allows individual elements of a given array to be rendered independently and prevents them from being rendered more than once on subsequent calls to drupal_render() (e.g., as part of a larger array). If the same array or array element is passed more than once to drupal_render(), it simply returns a NULL value.
$elements The structured array describing the data to be rendered.
The rendered HTML.