The initial commit of the responsive toolbar patch included a basic definition of the array structure to be returned by modules that implement
$items[$group_name] = array(
'tab' => array(
'title' => t(''),
'href' => '',
'attributes' => array(
'class' => array('icon', 'icon-menu'),
'tray' => array(
'#heading' => t(''),
'content' => array(/* renderable content */),
'weight' => -15,
The structure returned by modules implementing
hook_toolbar is needed to produce:
- A top-level tab.
- An optional tray of links or control structures. The content of the tray is arbitrary.
Tabs are returned as link structures and merge into an array passed to
theme_links passes each link to the l() function or directly renders the item with a span. This results in the tab items not running through the full drupal_render process. Pre and post render functions cannot be associated with the tabs for example. The edit module, in particular, needs to determine if its tab should be rendered in a post render function.
We need to determine an array structure to be returned from
hook_toolbar that is flexible and simple to implement.
The Countcount module wants to have a drop-down list in the Tab area: Zero, One, Many. So far, so good: my patch allows any render element to be used for a tab. Next, when the user clicks on "Many", the corresponding tray should open, so that the user can select the actual number.
Show the avatar image of an authenticated user in the User tab.
Show the number of items a user has in their shopping cart in a toolbar tab. Clicking the tab brings the user to the shopping cart management page. The ShoppingCart module maintainers also want to provide a "drop button" like menu with the option "Check out" on the toolbar tab. This should not be a toolbar tray.
A hypothetical MessageStream module wants to place a button in the toolbar that opens a sidebar with a list of system messages. The placement and styling of the button should not be like a toolbar tab. In fact, all styling and behavior will be custom. In this case, the MessageStream module is using the toolbar as a simple container.
The purpose of
hook_toolbar is to provide module developers a means to add components to the toolbar. The toolbar is meant to be a container for top-level site actions and configuration. See the use cases above for examples of what a module might add to the toolbar.
In toolbar also provides a construct known as a "tray". A tray is a container that will display vertically on narrow screens and can be display horizontally on wide screens. A module developer can specify renderable content that should be placed in a tray. The tray is controlled by a trigger, normally an HTML link element.
jessebeach and benjifisher have been working through an approach to improve the processing of
hook_toolbar so that developers can leverage the toolbar tray system, but also be able to pass any renderable element as a component of the toolbar.
- An implementation of
hook_toolbar()should return a keyed array of render elements, each element of type
- New render elements
- We define a new type of render element,
toolbar_item, with properties
'#weight'. The tab and tray can be any render elements, and the weight is an integer. This type is given a default pre-render function,
toolbar_pre_render_item(), theme function,
theme_toolbar_item(), and theme wrapper,
theme_toolbar_tab_wrapper(). We also define a new
- Theme functions
theme_toolbar(): Responsible for theming the toolbar and its child components.
theme_toolbar_item(): Responsible for theming the toolbar_item element. This renders only the tab, leaving the tray for
theme_toolbar_tab_wrapper(): Wraps the
#childrenof an element in a div with the class
tab. Provide common styling for "tab" elements in the toolbar.
theme_tray_heading_wrapper(): Appends an
<h3>heading with the contents of a
#headingproperty to a tray. Used for accessibility landmarking.
theme_toolbar_tray_wrapper(): Wraps the
#childrenof a rendered content of a toolbar component's
trayproperty in markup that styles and provides behavior attachment for a toolbar tray.
Some of the follow-up issues may add default properties of the toolbar_item type and/or change the list of theme functions, but we have settled on the
'#weight' properties of the toolbar_item type.
Under this patch, a module might return the following renderable in
hook_toolbar(). This code would create a tab in the toolbar with the label "Shopping cart" and an associated tray with actions associated with the cart.
$items['commerce'] = array(
'#type' => 'toolbar_item',
'#tab' => array(
'#type' => 'link',
'#title' => t('Shopping cart'),
'#href' => '/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,
- Gather feedback and opinions on the proposed patch in #58.
- Manual testing.
User interface changes
None most likely.
Original report by jessebeach
This issue is a followup to: #1137920: Fix toolbar on small screen sizes and redesign toolbar for desktop