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. Action bars also allow you to navigate back to the previous screen using an optional built in back button.

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. 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 actionBarDark property in the bb.int() function. Simply set actionBarDark 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.

To set a tab's initial state to selected you can set its data-bb-selected="true" attribute.

    <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>

Action Item Image Sizes

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

Action Overflow Menu

You must explicitly mark each action item you wish to 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.

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.

"Pinning" an Overflow Action

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>

Tab Overflow Menu

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.

Tab overflow actions also have a data-bb-accent-text attribute that can be used to add complimentary text that will appear below the action title on the tab overflow. This allows you to bring further context to your tab.

<div data-bb-type="action-bar">
   <div data-bb-type="action" data-bb-style="tab" data-bb-img="cog.png" data-bb-accent-text="Bar">Foo</div>
</div>

Sample Action Bar Layouts

Some sample layouts of the action bar can be seen below:

Action Bar JavaScript Interface

If your action bar has a back button you can set the caption of the button using setBackCaption()

document.getElementById('actionBarID').setBackCaption('Return');

To change the current selected tab via JavaScript you can use the setSelectedTab() function by passing in the tab to be selected

var tab = document.getElementById('myTab'),
    actionBar = document.getElementById('myActionBar');

actionBar.setSelectedTab(tab);

Action Button/Tab JavaScript Interface

The following JavaScript interfaces are available for dynamically manipulating, an Action Bar and its Actions after the screen has been added to the DOM.

The caption and image of an action item (tab and button) can be changed using the setCaption() and setImage() functions.

var myAction = document.getElementById('myAction');
myAction.setCaption('hello world');
myAction.setImage('images/newImage.png');

You can retrieve the caption and image details of an action by using the getCaption(), getImage() functions

var myAction = document.getElementById('myAction');
alert(myAction.getCaption());
alert(myAction.getImage());