Drupal 7 Module Development

Chapter 3
As you can see, the link type specifies that the render element should be passed
to two #pre_render functions. And it is the drupal_pre_render_link() function
that looks for the special render element properties in our example's link element,
namely, #title, #href, and #options.
So to reiterate, hook_element_info() defines the default properties for its render
element types, and it also specifies render callbacks that have their own internal API,
defining render element properties.
Using this framework, modules can create their own complex render element
by implementing hook_element_info(), using the properties specified by
drupal_render(), and by creating any render callbacks and associated APIs.
hook_page_alter()
So what's the point? By creating these complex render elements, we delay rendering
of the data and allow opportunities to alter that data before it is rendered into a
string. Before render elements were used in Drupal's theme system, themers and
module developers often had to completely re-render data after it had been rendered
the default way. This was obviously inefficient. Now each of these render elements
can be altered in preprocess functions or even directly in a template file with the
show() and hide() functions.
Now that we've looked at the guts of the Render API, it becomes much easier to
understand how the template-embedded hide() function works. If a template file
calls hide($element['child']); it simply sets the #printed property to TRUE, so
when print render($element); is later called, the child element is not printed.
We can then later call print render($element['child']); and render() will set
#printed to FALSE and pass $element to drupal_render().
Drupal's theme implementations use render elements in various places throughout
its theme hooks. But the two primary places render elements get used are in the
block and page theme hooks.
Any hook_block_view() implementation should return a renderable element,
and any menu callback which supplies a page's main content should also return
a render element.
Once the page's main content is retrieved, drupal_render_page() will
decorate the $page element using hook_page_build(). During the block module's
block_page_build(), all of the page's regions are added to the $page element as
child elements; and each of the region's child elements contain child elements for
each of the blocks in that region. drupal_render_page() will then allow modules
to modify the giant $page render element using hook_page_alter().
[ 81 ]