toolbar.api.php 5 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Hooks provided by the toolbar module.
6
 */
7
use Drupal\Core\Url;
8 9 10 11 12 13 14

/**
 * @addtogroup hooks
 * @{
 */

/**
15
 * Add items to the toolbar menu.
16
 *
17
 * The toolbar is a container for administrative and site-global interactive
18
 * components.
19
 *
20
 * The toolbar provides a common styling for items denoted by the
21
 * .toolbar-tab class.
22 23
 *
 * The toolbar provides a construct called a 'tray'. The tray is a container
24
 * for content. The tray may be associated with a toggle in the administration
25 26 27 28 29 30 31 32 33
 * bar. The toggle shows or hides the tray and is optimized for small and
 * large screens. To create this association, hook_toolbar() returns one or
 * more render elements of type 'toolbar_item', containing the toggle and tray
 * elements in its 'tab' and 'tray' properties.
 *
 * The following properties are available:
 *   - 'tab': A renderable array.
 *   - 'tray': Optional. A renderable array.
 *   - '#weight': Optional. Integer weight used for sorting toolbar items in
34
 *     administration bar area.
35 36
 *
 * This hook is invoked in toolbar_pre_render().
37 38 39 40
 *
 * @return
 *   An array of toolbar items, keyed by unique identifiers such as 'home' or
 *   'administration', or the short name of the module implementing the hook.
41
 *   The corresponding value is a render element of type 'toolbar_item'.
42
 *
43
 * @see toolbar_pre_render()
44 45 46 47 48
 * @ingroup toolbar_tabs
 */
function hook_toolbar() {
  $items = array();

49 50 51 52 53 54 55 56 57 58 59 60 61 62
  // Add a search field to the toolbar. The search field employs no toolbar
  // module theming functions.
  $items['global_search'] = array(
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'search',
      '#attributes' => array(
        'placeholder' => t('Search the site'),
        'class' => array('search-global'),
      ),
    ),
    '#weight' => 200,
    // Custom CSS, JS or a library can be associated with the toolbar item.
    '#attached' => array(
63 64
      'library' => array(
        'search/global',
65 66 67 68 69 70
      ),
    ),
  );

  // The 'Home' tab is a simple link, which is wrapped in markup associated
  // with a visual tab styling.
71
  $items['home'] = array(
72
    '#type' => 'toolbar_item',
73
    'tab' => array(
74 75
      '#type' => 'link',
      '#title' => t('Home'),
76
      '#url' => Url::fromRoute('<front>'),
77 78 79
      '#options' => array(
        'attributes' => array(
          'title' => t('Home page'),
80
          'class' => array('toolbar-icon', 'toolbar-icon-home'),
81
        ),
82 83
      ),
    ),
84
    '#weight' => -20,
85 86
  );

87 88 89 90 91 92 93 94
  // A tray may be associated with a tab.
  //
  // When the tab is activated, the tray will become visible, either in a
  // horizontal or vertical orientation on the screen.
  //
  // The tray should contain a renderable array. An optional #heading property
  // can be passed. This text is written to a heading tag in the tray as a
  // landmark for accessibility.
95
  $items['commerce'] = array(
96
    '#type' => 'toolbar_item',
97
    'tab' => array(
98 99
      '#type' => 'link',
      '#title' => t('Shopping cart'),
100
      '#url' => Url::fromRoute('cart'),
101 102 103 104 105
      '#options' => array(
        'html' => FALSE,
        'attributes' => array(
          'title' => t('Shopping cart'),
        ),
106 107 108 109
      ),
    ),
    'tray' => array(
      '#heading' => t('Shopping cart actions'),
110
      'shopping_cart' => array(
111 112 113 114
        '#theme' => 'item_list',
        '#items' => array( /* An item list renderable array */ ),
      ),
    ),
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
    '#weight' => 150,
  );

  // The tray can be used to render arbritrary content.
  //
  // A renderable array passed to the 'tray' property will be rendered outside
  // the administration bar but within the containing toolbar element.
  //
  // If the default behavior and styling of a toolbar tray is not desired, one
  // can render content to the toolbar element and apply custom theming and
  // behaviors.
  $items['user_messages'] = array(
    // Include the toolbar_tab_wrapper to style the link like a toolbar tab.
    // Exclude the theme wrapper if custom styling is desired.
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'link',
      '#theme' => 'user_message_toolbar_tab',
      '#theme_wrappers' => array(),
      '#title' => t('Messages'),
135
      '#url' => Url::fromRoute('user.message'),
136 137 138 139 140 141 142 143 144 145 146
      '#options' => array(
        'attributes' => array(
          'title' => t('Messages'),
        ),
      ),
    ),
    'tray' => array(
      '#heading' => t('User messages'),
      'messages' => array(/* renderable content */),
    ),
    '#weight' => 125,
147 148 149 150 151 152
  );

  return $items;
}

/**
153
 * Alter the toolbar menu after hook_toolbar() is invoked.
154 155 156 157 158 159 160
 *
 * This hook is invoked by toolbar_view() immediately after hook_toolbar(). The
 * toolbar definitions are passed in by reference. Each element of the $items
 * array is one item returned by a module from hook_toolbar(). Additional items
 * may be added, or existing items altered.
 *
 * @param $items
161
 *   Associative array of toolbar menu definitions returned from hook_toolbar().
162 163 164
 */
function hook_toolbar_alter(&$items) {
  // Move the User tab to the right.
165
  $items['commerce']['#weight'] = 5;
166 167 168 169 170
}

/**
 * @} End of "addtogroup hooks".
 */