render_example.module

<?php


/**
 * @file
 * Demonstrates render arrays.
 */

/**
 * @defgroup render_example Example: Render
 * @ingroup examples
 * @{
 * Demonstrate how render arrays are arranged and how they can be altered.
 * This alters blocks and the page to show the actual render array
 * that is being used to create each item.
 *
 * @see drupal_render()
 */
// This allows drupal_var_export() to work.
require_once 'includes/utility.inc';

/**
 * Implements hook_menu().
 */
function render_example_menu() {
    $items['examples/render_example'] = array(
        'title' => 'Render Example',
        'page callback' => 'render_example_info',
        'access callback' => TRUE,
    );
    $items['examples/render_example/altering'] = array(
        'title' => 'Alter pages and blocks',
        'page callback' => 'drupal_get_form',
        'page arguments' => array(
            'render_example_demo_form',
        ),
        'access arguments' => array(
            'access devel information',
        ),
    );
    $items['examples/render_example/arrays'] = array(
        'title' => 'Render array examples',
        'page callback' => 'render_example_arrays',
        'access callback' => TRUE,
    );
    return $items;
}

/**
 * Simple basic information about the module; an entry point.
 */
function render_example_info() {
    return t('The render example provides a <ul><li><a href="!arrays">demonstration of of render array usage</a></li><li><a href="!alter">using hook_page_alter()</a> to make various changes on a page.</li></ul>', array(
        '!arrays' => url('examples/render_example/arrays'),
        '!alter' => url('examples/render_example/altering'),
    ));
}

/**
 * Provides a number of render arrays and show what they do.
 *
 * Each array is keyed by a description; it's returned for rendering at page
 * render time. It's easy to add new examples to this.
 *
 * The array items in $demos are intended to be raw, normal render arrays
 * that can be experimented with to end up with different outcomes.
 */
function render_example_arrays() {
    // Interval in seconds for cache update with #cache.
    $interval = 60;
    $demos = array(
        // Demonstrate the simplest markup, a #markup element.
t('Super simple #markup') => array(
            '#markup' => t('Some basic text in a #markup (shows basic markup and how it is rendered)'),
        ),
        // Shows how #prefix and #suffix can add markup into an array.
t('Using #prefix and #suffix') => array(
            '#markup' => t('This one adds a prefix and suffix, which put a div around the item'),
            '#prefix' => '<div><br/>(prefix)<br/>',
            '#suffix' => '<br/>(suffix)</div>',
        ),
        // When #theme is provided, it is the #theme function's job to figure out
        // the meaning of the render array. The #theme function receives the entire
        // element in $variables and must return it, where it will be the content
        // of '#children'. When a #theme or other function is provided, custom
        // properties can be invented and used as needed, as the #separator
        // property provided here.
        //
        // If #theme is not provided, either explicitly or by the underlying
        // element, then the children are rendered using their own properties and
        // the results go into #children.
t('theme for an element') => array(
            'child' => array(
                t('This is some text that should be put together'),
                t('This is some more text that we need'),
            ),
            // An element we've created which will be used by our theming function.
'#separator' => ' | ',
            '#theme' => 'render_example_aggregate',
        ),
        // #theme_wrappers provides an array of theme functions which theme the
        // envelope or "wrapper" of a set of child elements. The theme function
        // finds its element children (the sub-arrays) already rendered in
        // '#children'.
t('theme_wrappers demonstration') => array(
            'child1' => array(
                '#markup' => t('Markup for child1'),
            ),
            'child2' => array(
                '#markup' => t('Markup for child2'),
            ),
            '#theme_wrappers' => array(
                'render_example_add_div',
                'render_example_add_notes',
            ),
        ),
        // Add '#pre_render' and '#post_render' handlers.
        // - '#pre_render' functions get access to the array before it is rendered
        //   and can change it. This is similar to a theme function, but it is a
        //   specific fixed function and changes the array in place rather than
        //   rendering it..
        // - '#post_render' functions get access to the rendered content, but also
        //   have the original array available.
t('pre_render and post_render') => array(
            '#markup' => '<div style="color:green">' . t('markup for pre_render and post_render example') . '</div>',
            '#pre_render' => array(
                'render_example_add_suffix',
            ),
            '#post_render' => array(
                'render_example_add_prefix',
            ),
        ),
        // Cache an element for $interval seconds using #cache.
        // The assumption here is that this is an expensive item to render, perhaps
        // large or otherwise expensive. Of course here it's just a piece of markup,
        // so we don't get the value.
        //
        // #cache allows us to set
        // - 'keys', an array of strings that will create the string cache key.
        // - 'bin', the cache bin
        // - 'expire', the expire timestamp. Note that this is actually limited
        //   to the granularity of a cron run.
        // - 'granularity', a bitmask determining at what level the caching is done
        //   (user, role, page).
t('cache demonstration') => array(
            // If your expensive function were to be executed here it would happen
            // on every page load regardless of the cache. The actual markup is
            // added via the #pre_render function, so that drupal_render() will only
            // execute the expensive function if this array has not been cached.
'#markup' => '',
            '#pre_render' => array(
                'render_example_cache_pre_render',
            ),
            '#cache' => array(
                'keys' => array(
                    'render_example',
                    'cache',
                    'demonstration',
                ),
                'bin' => 'cache',
                'expire' => time() + $interval,
                'granularity' => DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE,
            ),
        ),
    );
    // The rest of this function just places the above arrays in a context where
    // they can be rendered (hopefully attractively and usefully) on the page.
    $page_array = array();
    foreach ($demos as $key => $item) {
        $page_array[$key]['#theme_wrappers'] = array(
            'render_array',
        );
        $page_array[$key]['#description'] = $key;
        $page_array[$key]['unrendered'] = array(
            '#prefix' => '<div class="unrendered-label">' . t('Unrendered array (as plain text and with a krumo version)') . ':</div>',
            '#type' => 'markup',
            '#markup' => htmlentities(drupal_var_export($item)),
        );
        $page_array[$key]['kpr'] = array(
            // The kpr() function is from devel module and is here only allow us
            // to output the array in a way that's easy to explore.
'#markup' => kpr($item, TRUE),
        );
        $page_array[$key]['hr'] = array(
            '#markup' => '<hr/>',
        );
        $page_array[$key]['rendered'] = array(
            $item,
        );
        $page_array[$key]['rendered']['#prefix'] = '<p><em>Rendered version (light blue)</em>:</p>' . '<div class="rendered">';
        $page_array[$key]['rendered']['#suffix'] = '</div>';
    }
    return $page_array;
}

/**
 * A '#pre_render' function.
 *
 * @param array $element
 *   The element which will be rendered.
 *
 * @return array
 *   The altered element. In this case we add the #markup.
 */
function render_example_cache_pre_render($element) {
    $element['#markup'] = render_example_cache_expensive();
    // The following line is due to the bug described in
    // http://drupal.org/node/914792. A #markup element's #pre_render must set
    // #children because it replaces the default #markup pre_render, which is
    // drupal_pre_render_markup().
    $element['#children'] = $element['#markup'];
    return $element;
}

/**
 * A potentially expensive function.
 *
 * @return string
 *   Some demo text.
 */
function render_example_cache_expensive() {
    $interval = 60;
    $time_message = t('The current time was %time when this was cached. Updated every %interval seconds', array(
        '%time' => date('r'),
        '%interval' => $interval,
    ));
    // Uncomment the following line to demonstrate that this function is not
    // being run when the rendered array is cached.
    // drupal_set_message($time_message);
    return $time_message;
}

/**
 * A '#pre_render' function.
 *
 * @param array $element
 *   The element which will be rendered.
 *
 * @return array
 *   The altered element. In this case we add a #prefix to it.
 */
function render_example_add_suffix($element) {
    $element['#suffix'] = '<div style="color:red">' . t('This #suffix was added by a #pre_render') . '</div>';
    // The following line is due to the bug described in
    // http://drupal.org/node/914792. A #markup element's #pre_render must set
    // #children because it replaces the default #markup pre_render, which is
    // drupal_pre_render_markup().
    $element['#children'] = $element['#markup'];
    return $element;
}

/**
 * A '#post_render' function to add a little markup onto the end markup.
 *
 * @param string $markup
 *   The rendered element.
 * @param array $element
 *   The element which was rendered (for reference)
 *
 * @return string
 *   Markup altered as necessary. In this case we add a little postscript to it.
 */
function render_example_add_prefix($markup, $element) {
    $markup = '<div style="color:blue">This markup was added after rendering by a #post_render</div>' . $markup;
    return $markup;
}

/**
 * A #theme function.
 *
 * This #theme function has the responsibility of consolidating/rendering the
 * children's markup and returning it, where it will be placed in the
 * element's #children property.
 */
function theme_render_example_aggregate($variables) {
    $output = '';
    foreach (element_children($variables['element']['child']) as $item) {
        $output .= $variables['element']['child'][$item] . $variables['element']['#separator'];
    }
    return $output;
}

/*************** Altering Section **************************
 * The following section of the example builds and arranges the altering
 * example.
 */

/**
 * Builds the form that offers options of what items to show.
 */
function render_example_demo_form($form, &$form_state) {
    $form['description'] = array(
        '#type' => 'markup',
        '#markup' => t('This example shows what render arrays look like in the building of a page. It will not work unless the user running it has the "access devel information" privilege. It shows both the actual arrays used to build a page or block and also the capabilities of altering the page late in its lifecycle.'),
    );
    $form['show_arrays'] = array(
        '#type' => 'fieldset',
        '#title' => t('Show render arrays'),
    );
    foreach (array(
        'block',
        'page',
    ) as $type) {
        $form['show_arrays']['render_example_show_' . $type] = array(
            '#type' => 'checkbox',
            '#title' => t('Show @type render arrays', array(
                '@type' => $type,
            )),
            '#default_value' => variable_get('render_example_show_' . $type, FALSE),
        );
    }
    $form['page_fiddling'] = array(
        '#type' => 'fieldset',
        '#title' => t('Make changes on page via hook_page_alter()'),
    );
    $form['page_fiddling']['render_example_note_about_render_arrays'] = array(
        '#title' => t('Add a note about render arrays to top of sidebar_first (if it exists)'),
        '#description' => t('Creates a simple render array that displays the use of #pre_render, #post_render, #theme, and #theme_wrappers.'),
        '#type' => 'checkbox',
        '#default_value' => variable_get('render_example_note_about_render_arrays', FALSE),
    );
    $form['page_fiddling']['render_example_move_navigation_menu'] = array(
        '#title' => t('Move the navigation menu to the top of the content area'),
        '#description' => t('Uses hook_page_alter() to move the navigation menu into another region.'),
        '#type' => 'checkbox',
        '#default_value' => variable_get('render_example_move_navigation_menu', FALSE),
    );
    $form['page_fiddling']['render_example_reverse_sidebar'] = array(
        '#title' => t('Reverse ordering of sidebar_first elements (if it exists) - will affect the above'),
        '#description' => t('Uses hook_page_alter() to reverse the ordering of items in sidebar_first'),
        '#type' => 'checkbox',
        '#default_value' => variable_get('render_example_reverse_sidebar', FALSE),
    );
    $form['page_fiddling']['render_example_prefix'] = array(
        '#title' => t('Use #prefix and #suffix to wrap a div around every block'),
        '#description' => t('Uses hook_page_alter to wrap all blocks with a div using #prefix and #suffix'),
        '#type' => 'checkbox',
        '#default_value' => variable_get('render_example_prefix'),
    );
    return system_settings_form($form);
}

/**
 * Implements hook_page_alter().
 *
 * Alters the page in several different ways based on how the form has been
 * configured.
 */
function render_example_page_alter(&$page) {
    // Re-sort the sidebar in reverse order.
    if (variable_get('render_example_reverse_sidebar', FALSE) && !empty($page['sidebar_first'])) {
        $page['sidebar_first'] = array_reverse($page['sidebar_first']);
        foreach (element_children($page['sidebar_first']) as $element) {
            // Reverse the weights if they exist.
            if (!empty($page['sidebar_first'][$element]['#weight'])) {
                $page['sidebar_first'][$element]['#weight'] *= -1;
            }
        }
        $page['sidebar_first']['#sorted'] = FALSE;
    }
    // Add a list of items to the top of sidebar_first.
    // This shows how #theme and #theme_wrappers work.
    if (variable_get('render_example_note_about_render_arrays', FALSE) && !empty($page['sidebar_first'])) {
        $items = array(
            t('Render arrays are everywhere in D7'),
            t('Leave content unrendered as much as possible'),
            t('This allows rearrangement and alteration very late in page cycle'),
        );
        $note = array(
            '#title' => t('Render Array Example'),
            '#items' => $items,
            // The functions in #pre_render get to alter the actual data before it
            // gets rendered by the various theme functions.
'#pre_render' => array(
                'render_example_change_to_ol',
            ),
            // The functions in #post_render get both the element and the rendered
            // data and can add to the rendered data.
'#post_render' => array(
                'render_example_add_hr',
            ),
            // The #theme theme operation gets the first chance at rendering the
            // element and its children.
'#theme' => 'item_list',
            // Then the theme operations in #theme_wrappers can wrap more around
            // what #theme left in #chilren.
'#theme_wrappers' => array(
                'render_example_add_div',
                'render_example_add_notes',
            ),
            '#weight' => -9999,
        );
        $page['sidebar_first']['render_array_note'] = $note;
        $page['sidebar_first']['#sorted'] = FALSE;
    }
    // Move the navigation menu into the content area.
    if (variable_get('render_example_move_navigation_menu', FALSE) && !empty($page['sidebar_first']['system_navigation']) && !empty($page['content'])) {
        $page['content']['system_navigation'] = $page['sidebar_first']['system_navigation'];
        $page['content']['system_navigation']['#weight'] = -99999;
        unset($page['content']['#sorted']);
        unset($page['sidebar_first']['system_navigation']);
    }
    // Show the render array used to build the page render array display.
    if (variable_get('render_example_show_page', FALSE)) {
        $form['render_example_page_fieldset'] = array(
            '#type' => 'fieldset',
            '#title' => t('Page render array'),
            '#collapsible' => TRUE,
            '#collapsed' => TRUE,
        );
        $form['render_example_page_fieldset']['markup'] = array(
            // The kpr() function is from devel module and is here only allow us
            // to output the array in a way that's easy to explore.
'#markup' => kpr($page, TRUE),
        );
        $page['content']['page_render_array'] = drupal_get_form('render_example_embedded_form', $form);
        $page['content']['page_render_array']['#weight'] = -999999;
        $page['content']['#sorted'] = FALSE;
    }
    // Add render array to the bottom of each block.
    if (variable_get('render_example_show_block', FALSE)) {
        foreach (element_children($page) as $region_name) {
            foreach (element_children($page[$region_name]) as $block_name) {
                // Push the block down a level so we can add another block after it.
                $old_block = $page[$region_name][$block_name];
                $page[$region_name][$block_name] = array(
                    $block_name => $old_block,
                );
                $form = array();
                $form['render_example_block_fieldset'] = array(
                    '#type' => 'fieldset',
                    '#title' => t('Block render array'),
                    '#collapsible' => TRUE,
                    '#collapsed' => TRUE,
                );
                $form['render_example_block_fieldset']['markup'] = array(
                    '#type' => 'item',
                    '#title' => t('%blockname block render array', array(
                        '%blockname' => $block_name,
                    )),
                    // The kpr() function is from devel module and is here only allow us
                    // to output the array in a way that's easy to explore.
'#markup' => kpr($old_block, TRUE),
                );
                // Add the new block that contains the render array.
                $page[$region_name][$block_name]['render_example_block_render_array'] = drupal_get_form('render_example_embedded_form', $form);
                $page[$region_name][$block_name]['render_example_block_render_array']['#weight'] = 999;
            }
        }
    }
    // Add #prefix and #suffix to a block to wrap a div around it.
    if (variable_get('render_example_prefix', FALSE)) {
        foreach (element_children($page) as $region_name) {
            foreach (element_children($page[$region_name]) as $block_name) {
                $block =& $page[$region_name][$block_name];
                $block['#prefix'] = '<div class="block-prefix"><p>Prefixed</p>';
                $block['#suffix'] = '<span class="block-suffix">Block suffix</span></div>';
            }
        }
    }
}

/**
 * Utility function to build a named form given a set of form elements.
 *
 * This is a standard form builder function that takes an additional array,
 * which is itself a form.
 *
 * @param array $form
 *   Form API form array.
 * @param array $form_state
 *   Form API form state array.
 * @param array $form_items
 *   The form items to be included in this form.
 */
function render_example_embedded_form($form, &$form_state, $form_items) {
    return $form_items;
}

/**
 * Implements hook_theme().
 */
function render_example_theme() {
    $items = array(
        'render_example_add_div' => array(
            'render element' => 'element',
        ),
        'render_example_add_notes' => array(
            'render element' => 'element',
        ),
        'render_array' => array(
            'render element' => 'element',
        ),
        'render_example_aggregate' => array(
            'render element' => 'element',
        ),
    );
    return $items;
}

/**
 * Wraps a div around the already-rendered #children.
 */
function theme_render_example_add_div($variables) {
    $element = $variables['element'];
    $output = '<div class="render-example-wrapper-div">';
    $output .= $element['#children'];
    $output .= '</div>';
    return $output;
}

/**
 * Wraps a div and add a little text after the rendered #children.
 */
function theme_render_example_add_notes($variables) {
    $element = $variables['element'];
    $output = '<div class="render-example-notes-wrapper-div">';
    $output .= $element['#children'];
    $output .= '<em>' . t('This is a note added by a #theme_wrapper') . '</em>';
    $output .= '</div>';
    return $output;
}

/**
 * Themes the render array (from the demonstration page).
 */
function theme_render_array($variables) {
    $heading = '<div class="render-header">' . $variables['element']['#description'] . '</div>';
    $rendered = '<div class="render-array">' . $heading . $variables['element']['#children'] . '</div>';
    return $rendered;
}

/**
 * Adds a #type to the element before it gets rendered.
 *
 * In this case, changes from the default 'ul' to 'ol'.
 *
 * @param array $element
 *   The element to be altered, in this case a list, ready for theme_item_list.
 *
 * @return array
 *   The altered list (with '#type')
 */
function render_example_change_to_ol($element) {
    $element['#type'] = 'ol';
    return $element;
}

/**
 * Alter the rendered output after all other theming.
 *
 * This #post_render function gets to alter the rendered output after all
 * theme functions have acted on it, and it receives the original data, so
 * can make decisions based on that. In this example, no use is made of the
 * passed-in $element.
 *
 * @param string $markup
 *   The already-rendered data
 * @param array $element
 *   The data element that was rendered
 *
 * @return string
 *   The altered data.
 */
function render_example_add_hr($markup, $element) {
    $output = $markup . '<hr />';
    return $output;
}

/**
 * @} End of "defgroup render_example".
 */