The Definitive Guide to Drupal 7

Identifying Render Elements

An easy way to identify arrays as render elements is the presence of properties. Render elements are always arrays, and they always contain properties that always begin with a hash tag. In Figure 16–4, you can immediately tell that $page['sidebar_first'] is a render element because it contains a few properties: #sorted, #theme_wrappers, and #region. These properties are used by drupal_render() which is called when using drupal_render() to determine how to render the output. For details about drupal_render() see http://api.drupal.org/api/function/render/7.

As themers, you won’t be getting deep into the more developer-centric properties, but there are a few that will be helpful for you to make sense of out what these arrays mean. These are described in Table 16–1.

Table 16–1. Helpful render element properties
See the documentation at http://api.drupal.org/api/function/drupal_render/7 for more information.
Property Description
#theme Specifies the theme hook, which can be either a function or a template to use when rendering the element.
#theme_wrappers An array containing theme hook(s) to be used to wrap the rendered children of the element. For example, when theming a block, the #theme property would be block and the #theme_wrappers property would contain region. This ensures that after the block(s) are rendered, the children would be run through the region template as well.
#type The type of element that will be rendered. The default properties for element types are defined in hook_element_info() implementations.
#prefix and #suffix A string containing markup to be placed before (prefix) or after (suffix) the rendered element.
#weight A number that is used to sort the elements to determine the order in which they will print.
#sorted A Boolean (TRUE or FALSE) that indicates whether or not the children have been sorted. For example, this is used in conjunction with the #weight property to sort the blocks in a region. When reordering blocks in a theme via hook_page_alter(), you'll need to specify #sorted => FALSE in addition to the #weight to trigger a new sort when you need to move a block to any other position than below the already sorted elements.
#attached The #attached property is used to specify corresponding CSS, JavaScript, or libraries to load when the element is rendered.

You are reading content from two chapters on Theme Development from The Definitive Guide to Drupal 7, written by Jacine Luisi and published by Apress on July 19, 2011. All rights reserved.