www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/toolbar/toolbar.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by the toolbar module.
   6  */
   7
   8 use Drupal\Core\Url;
   9
  10 /**
  11  * @addtogroup hooks
  12  * @{
  13  */
  14
  15 /**
  16  * Add items to the toolbar menu.
  17  *
  18  * The toolbar is a container for administrative and site-global interactive
  19  * components.
  20  *
  21  * The toolbar provides a common styling for items denoted by the
  22  * .toolbar-tab class.
  23  *
  24  * The toolbar provides a construct called a 'tray'. The tray is a container
  25  * for content. The tray may be associated with a toggle in the administration
  26  * bar. The toggle shows or hides the tray and is optimized for small and
  27  * large screens. To create this association, hook_toolbar() returns one or
  28  * more render elements of type 'toolbar_item', containing the toggle and tray
  29  * elements in its 'tab' and 'tray' properties.
  30  *
  31  * The following properties are available:
  32  *   - 'tab': A renderable array.
  33  *   - 'tray': Optional. A renderable array.
  34  *   - '#weight': Optional. Integer weight used for sorting toolbar items in
  35  *     administration bar area.
  36  *
  37  * This hook is invoked in toolbar_pre_render().
  38  *
  39  * @return
  40  *   An array of toolbar items, keyed by unique identifiers such as 'home' or
  41  *   'administration', or the short name of the module implementing the hook.
  42  *   The corresponding value is a render element of type 'toolbar_item'.
  43  *
  44  * @see toolbar_pre_render()
  45  * @ingroup toolbar_tabs
  46  */
  47 function hook_toolbar() {
  48   $items = [];
  49
  50   // Add a search field to the toolbar. The search field employs no toolbar
  51   // module theming functions.
  52   $items['global_search'] = [
  53     '#type' => 'toolbar_item',
  54     'tab' => [
  55       '#type' => 'search',
  56       '#attributes' => [
  57         'placeholder' => t('Search the site'),
  58         'class' => ['search-global'],
  59       ],
  60     ],
  61     '#weight' => 200,
  62     // Custom CSS, JS or a library can be associated with the toolbar item.
  63     '#attached' => [
  64       'library' => [
  65         'search/global',
  66       ],
  67     ],
  68   ];
  69
  70   // The 'Home' tab is a simple link, which is wrapped in markup associated
  71   // with a visual tab styling.
  72   $items['home'] = [
  73     '#type' => 'toolbar_item',
  74     'tab' => [
  75       '#type' => 'link',
  76       '#title' => t('Home'),
  77       '#url' => Url::fromRoute('<front>'),
  78       '#options' => [
  79         'attributes' => [
  80           'title' => t('Home page'),
  81           'class' => ['toolbar-icon', 'toolbar-icon-home'],
  82         ],
  83       ],
  84     ],
  85     '#weight' => -20,
  86   ];
  87
  88   // A tray may be associated with a tab.
  89   //
  90   // When the tab is activated, the tray will become visible, either in a
  91   // horizontal or vertical orientation on the screen.
  92   //
  93   // The tray should contain a renderable array. An optional #heading property
  94   // can be passed. This text is written to a heading tag in the tray as a
  95   // landmark for accessibility.
  96   $items['commerce'] = [
  97     '#type' => 'toolbar_item',
  98     'tab' => [
  99       '#type' => 'link',
 100       '#title' => t('Shopping cart'),
 101       '#url' => Url::fromRoute('cart'),
 102       '#options' => [
 103         'attributes' => [
 104           'title' => t('Shopping cart'),
 105         ],
 106       ],
 107     ],
 108     'tray' => [
 109       '#heading' => t('Shopping cart actions'),
 110       'shopping_cart' => [
 111         '#theme' => 'item_list',
 112         '#items' => [/* An item list renderable array */],
 113       ],
 114     ],
 115     '#weight' => 150,
 116   ];
 117
 118   // The tray can be used to render arbitrary content.
 119   //
 120   // A renderable array passed to the 'tray' property will be rendered outside
 121   // the administration bar but within the containing toolbar element.
 122   //
 123   // If the default behavior and styling of a toolbar tray is not desired, one
 124   // can render content to the toolbar element and apply custom theming and
 125   // behaviors.
 126   $items['user_messages'] = [
 127     // Include the toolbar_tab_wrapper to style the link like a toolbar tab.
 128     // Exclude the theme wrapper if custom styling is desired.
 129     '#type' => 'toolbar_item',
 130     'tab' => [
 131       '#type' => 'link',
 132       '#theme' => 'user_message_toolbar_tab',
 133       '#theme_wrappers' => [],
 134       '#title' => t('Messages'),
 135       '#url' => Url::fromRoute('user.message'),
 136       '#options' => [
 137         'attributes' => [
 138           'title' => t('Messages'),
 139         ],
 140       ],
 141     ],
 142     'tray' => [
 143       '#heading' => t('User messages'),
 144       'messages' => [/* renderable content */],
 145     ],
 146     '#weight' => 125,
 147   ];
 148
 149   return $items;
 150 }
 151
 152 /**
 153  * Alter the toolbar menu after hook_toolbar() is invoked.
 154  *
 155  * This hook is invoked by Toolbar::preRenderToolbar() immediately after
 156  * hook_toolbar(). The toolbar definitions are passed in by reference. Each
 157  * element of the $items array is one item returned by a module from
 158  * hook_toolbar(). Additional items may be added, or existing items altered.
 159  *
 160  * @param $items
 161  *   Associative array of toolbar menu definitions returned from hook_toolbar().
 162  */
 163 function hook_toolbar_alter(&$items) {
 164   // Move the User tab to the right.
 165   $items['commerce']['#weight'] = 5;
 166 }
 167
 168 /**
 169  * @} End of "addtogroup hooks".
 170  */