W3cubDocs

/Drupal 8

function hook_toolbar

hook_toolbar()

Add items to the toolbar menu.

The toolbar is a container for administrative and site-global interactive components.

The toolbar provides a common styling for items denoted by the .toolbar-tab class.

The toolbar provides a construct called a 'tray'. The tray is a container for content. The tray may be associated with a toggle in the administration 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 administration bar area.

This hook is invoked in toolbar_pre_render().

Return value

An array of toolbar items, keyed by unique identifiers such as 'home' or 'administration', or the short name of the module implementing the hook. The corresponding value is a render element of type 'toolbar_item'.

See also

toolbar_pre_render()

Related topics

Hooks
Define functions that alter the behavior of Drupal core.

File

core/modules/toolbar/toolbar.api.php, line 47
Hooks provided by the toolbar module.

Code

function hook_toolbar() {
  $items = array();

  // 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(
      'library' => array(
        'search/global',
      ),
    ),
  );

  // The 'Home' tab is a simple link, which is wrapped in markup associated
  // with a visual tab styling.
  $items['home'] = array(
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'link',
      '#title' => t('Home'),
      '#url' => Url::fromRoute('<front>'),
      '#options' => array(
        'attributes' => array(
          'title' => t('Home page'),
          'class' => array('toolbar-icon', 'toolbar-icon-home'),
        ),
      ),
    ),
    '#weight' => -20,
  );

  // 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.
  $items['commerce'] = array(
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'link',
      '#title' => t('Shopping cart'),
      '#url' => Url::fromRoute('cart'),
      '#options' => array(
        'attributes' => array(
          'title' => t('Shopping cart'),
        ),
      ),
    ),
    'tray' => array(
      '#heading' => t('Shopping cart actions'),
      'shopping_cart' => array(
        '#theme' => 'item_list',
        '#items' => array(/* An item list renderable array */),
      ),
    ),
    '#weight' => 150,
  );

  // The tray can be used to render arbitrary 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'),
      '#url' => Url::fromRoute('user.message'),
      '#options' => array(
        'attributes' => array(
          'title' => t('Messages'),
        ),
      ),
    ),
    'tray' => array(
      '#heading' => t('User messages'),
      'messages' => array(/* renderable content */),
    ),
    '#weight' => 125,
  );

  return $items;
}

© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.
https://api.drupal.org/api/drupal/core!modules!toolbar!toolbar.api.php/function/hook_toolbar/8.1.x