Action Bar
The BlackBerry 10 action bar allows for a combination of buttons and tabs. Action Bars are currently only supported on PlayBook and BB10 devices. It is essentially a toolbar that appears at the bottom of the screen allowing for scrolling content above it.
If you have a title bar with a back button specified for PlayBook, and an action bar is not already specified for your screen, an action bar will be created with a back button as long as you don't already have an action bar defined with tabs. Action bars allow you to both navigate back to the previous screen but also provide tabs and/or buttons for your user.
NOTE: Combining a back button and tabs on an action bar is not allowed
If you provide a data-bb-back-caption attribute on the action bar, a back button will automatically be created. If you are using tabs on your screen, you can specify their tab styles using the data-bb-tab-style attribute. Currently only "highlight" is supported. Each item on the bar is defined as a data-bb-type="action" and its type is defined by the data-bb-style attribute which can either be a "tab" or a "button". Tabs automatically handle the highlighting of the selected tab. it is recommended that you group your tabs and buttons together to provide a clean user interface.
You can handle the selection of the action by assigning an onclick event handler.
The color style of the action bar is either a dark or light theme. This is applied using the bb10ActionBarDark property in the bb.int() function. Simply set bb10ActionBarDark to true/false to have the dark or light theme. This theme will be carried over for the entire application to ensure a consistent look and feel.
<div data-bb-type="action-bar" data-bb-tab-style="highlight">
<div data-bb-type="action" data-bb-style="tab" data-bb-img="images/actionBar/cog_dark_theme.png">Library</div>
<div data-bb-type="action" data-bb-style="tab" data-bb-selected="true" data-bb-img="images/actionBar/cog_dark_theme.png">Smart</div>
<div data-bb-type="action" data-bb-style="button" data-bb-img="images/actionBar/cog_dark_theme.png" onclick="alert('Find');">Find</div>
</div>Images used for Actions will be scaled to the following resolutions and centered on the action bar items.
- BlackBerry PlayBook - 40 x 40 pixels
- BlackBerry 10 - 80 x 80 pixels
If there are more than 5 total actions that are added to the action bar (including the back button) an overflow action menu will be created on the far right of the action bar. This button will trigger a slide in overflow menu that will contain the remaining items that were defined on the action bar.
NOTE: These changes are currently in the "next" branch and will make their way into the official 0.9.3 release
Action bar's no longer have the data-bb-tab-style attribute. There's only one style of tabs supported.
You must explicitly mark each action item you wish to have appear on the tab overflow or action overflow menus. This is accomplished by using the data-bb-overflow="true" attribute. By adding this attribute to your button or tab action, it will appear on its associated overflow menu.
<div data-bb-type="action-bar">
<div data-bb-type="action" data-bb-style="tab" data-bb-overflow="true" data-bb-img="cog.png">Library</div>
<div data-bb-type="action" data-bb-style="tab" data-bb-selected="true" data-bb-img="cog.png">Smart</div>
<div data-bb-type="action" data-bb-style="button" data-bb-overflow="true" data-bb-img="cog.png">Find</div>
</div>Only 5 "viewable" actions in total are allowed on the action bar at any time. This total includes the system back button, tab overflow and action overflow buttons. It's the developer's responsibility keep the "main actions" only in the Action bar and relegate other actions to the tab overflow and action overflow menus in order to make sure that the screen's main function is clear and the user is not distracted by secondary actions.
When you mark one or more tabs as an overflow action, the tab will appear in the tab overflow menu. This will also create a tab overflow menu button on the far left of the action bar. This tab overflow menu button uses up one of the 5 available visible action slots.
Tab overflows are meant for other parts of your screen that are not as common as the tabs which you decide to display on the action bar itself. When a user presses the tab overflow menu button, a menu of all the available tabs will slide into display (both those marked for overflow and those that appear on the action bar). When the user selects one of the tabs on the overflow menu it will fire the tab's onclick event.
If the tab selected was one of the tab's marked as an overflow action, the tab overflow menu button will display the information for that action. Moving back to a tab that was not marked as overflow will trigger the tab overflow menu button to go back to its initial state.
Some sample layouts of the action bar can be seen below:
There are scenarios where you have a specific action that you wish to call out in your action bar overflow menu as something different or special ("Delete" is a good example). To make this action stand out it can be "pinned" to the bottom of the action overflow menu away from your other actions. This can be done by providing both the data-bb-overflow="true" and data-bb-pin="true" attributes for a button action.
<div data-bb-type="action-bar">
<div data-bb-type="action" data-bb-style="button" data-bb-img="cog.png">Do Something</div>
<div data-bb-type="action" data-bb-style="button" data-bb-overflow="true" data-bb-img="cog.png">Smart</div>
<div data-bb-type="action" data-bb-style="button" data-bb-overflow="true" data-bb-pin="true" data-bb-img="cog.png">Delete</div>
</div>