render_example.module

<?php


/**
 * @file
 * Demonstrates using Drupal's Render API.
 */

/**
 * @defgroup render_example Example: Render API
 * @ingroup examples
 * @{
 * The  @link https://www.drupal.org/docs/8/api/render-api Render API @endlink
 * consists of two parts: one, structured arrays that provide data, and hints
 * about how that data should be rendered, and two, a rendering pipeline that
 * can be used to render these arrays into various output formats. This example
 * module looks at how to define content using render arrays, as well as how to
 * use alter hooks to manipulate render arrays created by other modules.
 *
 * For more on the rendering pipeline see @link
 * https://www.drupal.org/docs/8/api/render-api/the-drupal-8-render-pipeline The
 * Drupal 8 Render Pipeline @endlink.
 *
 * In order to ensure that a theme can completely customize the markup output
 * by Drupal, module developers should avoid directly writing HTML markup for
 * pages, blocks, and other user-visible output in their modules, and should
 * instead return structured "render arrays". Checkout the example code in
 * \Drupal\render_example\Controller\RenderExampleController::arrays() for an
 * explanation of how to define new renderable arrays. The output from that
 * code can be viewed at examples/render_example/arrays.
 *
 * One of the primary benefits of using arrays to define content instead of
 * strings of HTML is that arrays are easier to manipulate. There are dozens of
 * hooks, and other ways to gain access to and manipulate existing render arrays
 * during the rendering process both from within a module, and via a theme. As
 * a rule of thumb the process of rendering an array into HTML is delayed for as
 * long as possible. In most cases it's not until the variable containing the
 * content to be rendered is printed out in a Twig template file that it is
 * finally rendered.
 *
 * For examples of altering render arrays checkout the code in
 * render_example_preprocess_page() and render_example_preprocess_block(). There
 * is a form at examples/render_example/altering that can be used to turn these
 * features on and off if you would like to see the results of the array
 * altering code on your site.
 *
 * This module contains code that can display the render array used to build
 * each page, and/or block, as you navigate through a site as a way to show some
 * examples of real render arrays being used. This functionality requires that
 * the @link https://www.drupal.org/project/devel Devel module @endlink be
 * installed in order to work.
 *
 * Modules can also provide new render element types. A powerful way to
 * encapsulate complex display logic into a reusable widget. This can help to
 * cut down on code repetition, and allow other module developers to build off
 * of your work. See an example of a new render element definition by looking at
 * \Drupal\render_example\Element\Marquee.
 *
 * Forms are generated using a superset of the Render API. You can see examples
 * of how the Render API is used when creating forms in the fapi_example module.
 *
 * @see theme_render
 * @see \Drupal\Core\Render\RendererInterface::render()
 * @see \Drupal\Core\Template\TwigExtension::renderVar()
 */
use Drupal\Core\Render\Element;

/**
 * Implements hook_theme().
 */
function render_example_theme() {
    return [
        // These theme hooks are both used by examples in
        // \Drupal\render_example\Controller\RenderExampleController::arrays().
'render_example_add_div' => [
            'render element' => 'element',
        ],
        'render_array' => [
            'render element' => 'element',
        ],
        // This is used in combination with \Drupal\render_example\Element\Marquee
        // to define a new custom render element type that allows for the use of
        // '#type' => 'marquee' elements in a render array.
'render_example_marquee' => [
            'variables' => [
                'content' => '',
                'attributes' => [],
            ],
        ],
    ];
}

/**
 * Implements hook_preprocess_page().
 *
 * Demonstrates using a preprocess function to alter the renderable array that
 * represents the page currently being viewed.
 */
function render_example_preprocess_page(&$variables) {
    // Only modify the 'altering' page.
    if (\Drupal::routeMatch()->getRouteName() !== 'render_example.altering') {
        return;
    }
    $config = \Drupal::config('render_example.settings');
    // Preprocess hooks are invoked by the theme layer, and are used to give
    // modules a chance to manipulate the variables that are going to be made
    // available to a specific template file. Since content is still defined as
    // renderable arrays at this point you can do quite a bit to manipulate the
    // eventual output by altering these arrays.
    //
    // The $page variable in this case contains the complete content of the page
    // including all regions, and the blocks placed within each region.
    //
    // The actual process of converting a renderable array to HTML is started when
    // this variable is printed out within a Twig template. Drupal's Twig
    // extension provides a wrapper around the Twig code that prints out variables
    // which checks to see if the variable being printed is a renderable array and
    // passes it through \Drupal\Core\Render\RendererInterface::render() before
    // printing it to the screen.
    $page =& $variables['page'];
    // Move the breadcrumbs into the content area.
    if ($config->get('move_breadcrumbs') && !empty($page['breadcrumb']) && !empty($page['content'])) {
        $page['content']['breadcrumb'] = $page['breadcrumb'];
        unset($page['breadcrumb']);
        $page['content']['breadcrumb']['#weight'] = -99999;
        // Force the content to be re-sorted.
        $page['content']['#sorted'] = FALSE;
    }
    // Re-sort the contents of the sidebar in reverse order.
    if ($config->get('reverse_sidebar') && !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;
            }
        }
        // This forces the sidebar to be re-sorted.
        $page['sidebar_first']['#sorted'] = FALSE;
    }
    // Show the render array used to build the current page.
    // This relies on the Devel module's variable dumper service.
    // https://wwww.drupal.org/project/devel
    if (Drupal::moduleHandler()->moduleExists('devel') && $config->get('show_page')) {
        $page['content']['page_render_array'] = [
            '#type' => 'markup',
            '#prefix' => '<h2>' . t('The page render array') . '</h2>',
            // The devel.dumper service is provided by the devel module and makes for
            // and easier to read var_dump(). Especially if the companion Kint module
            // is enabled.
'dump' => \Drupal::service('devel.dumper')->exportAsRenderable($page, '$page'),
            '#weight' => -99999,
        ];
        $page['content']['#sorted'] = FALSE;
    }
}

/**
 * Implements hook_preprocess_block().
 */
function render_example_preprocess_block(&$variables) {
    // Only modify the 'altering' page.
    if (\Drupal::routeMatch()->getRouteName() !== 'render_example.altering') {
        return;
    }
    $config = \Drupal::config('render_example.settings');
    // This example shows how you can manipulate an existing renderable array. In
    // this case by adding #prefix and #suffix properties to the block in order to
    // wrap a <div> around it.
    if ($config->get('wrap_blocks')) {
        $variables['content']['#prefix'] = '<div class="block-prefix"><p>' . t('Prefixed') . '</p>';
        $variables['content']['#suffix'] = '<span class="block-suffix">' . t('Block suffix') . '</span></div>';
    }
    // Show the render array used to build each block if the Devel module is
    // installed and the feature is enabled.
    if (Drupal::moduleHandler()->moduleExists('devel') && $config->get('show_block')) {
        $variables['content']['block_render_array'] = [
            '#type' => 'markup',
            '#prefix' => '<h2>' . t('The block render array for @block_id.', [
                '@block_id' => $variables['plugin_id'],
            ]) . '</h2>',
            'dump' => \Drupal::service('devel.dumper')->exportAsRenderable($variables, $variables['plugin_id']),
        ];
    }
}

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