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

/**
 * @file
5
 * Hooks provided by the toolbar module.
6 7 8 9 10 11 12 13
 */

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

/**
14
 * Add items to the toolbar menu.
15
 *
16 17
 * The toolbar is a container for adminstrative and site-global interactive
 * components.
18
 *
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
 * The toolbar provides a common styling for items denoted by the .tab class.
 * The theme wrapper toolbar_tab_wrapper is provided to wrap a toolbar item
 * with the appropriate markup to apply the styling.
 *
 * 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 adminstration
 * 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
 *     adminstration bar area.
 *
 * 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 63 64 65 66 67 68 69 70
  // 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(
      'css' => array(
        drupal_get_path('module', 'search') . '/css/search.base.css',
      ),
    ),
  );

  // 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 76 77 78 79 80 81
      '#type' => 'link',
      '#title' => t('Home'),
      '#href' => '<front>',
      '#options' => array(
        'attributes' => array(
          'title' => t('Home page'),
          'class' => array('icon', 'icon-home'),
        ),
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 100 101 102 103 104 105
      '#type' => 'link',
      '#title' => t('Shopping cart'),
      '#href' => '/cart',
      '#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 135 136 137 138 139 140 141 142 143 144 145 146
    '#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'),
      '#href' => '/user/messages',
      '#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".
 */