toolbar.api.php 4.8 KB

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