annotate core/modules/toolbar/toolbar.api.php @ 19:fa3358dc1485 tip

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