Title Bars

A title bar can be created by nesting a data-bb-type="title" <div> in your screen. If defined, a standard title bar will appear showing the declared text. The data-bb-caption attribute defines the text to show in this title area.

    <div data-bb-type="screen" data-bb-effect="fade">
        <div data-bb-type="title" data-bb-caption="User Interface Examples" ></div>
    </div>

You can also add a back button to your title bar that will ONLY appear when you display your content on a PlayBook or a BlackBerry 10 device. To define a back button in your title bar, add the caption of your back button to the data-bb-back-caption attribute.

    <div data-bb-type="title" data-bb-caption="User Interface Examples" data-bb-back-caption="Back"></div>

For PlayBook this will appear as the standard back button in your UI as seen below:

BlackBerry 10 Title Bar Additions

For BlackBerry 10 the title bar provides additional functionality by allowing you to specify a second action button.

    <div data-bb-type="title" data-bb-caption="Edit Contact" data-bb-back-caption="Cancel" data-bb-action-caption="Save" onactionclick="doSave()"></div>

The additional action button also allows you to place an onactionclick event so that you can handle the user's additional action.

On BlackBerry 10 the typical user experience is to provide a back button and action using the Action Bar unless your screen's primary purpose is for data entry. When entering data into your screen the virtual keyboard will appear and cover the action bar causing your user to first close the keyboard and then press the back button or action. By placing the back/cancel button and most common action in the title bar, your user will have quick access to the two main actions performed on the screen.

Title Bar Styling

Title Bars on BlackBerry 10 can also specify an data-bb-accent-text and data-bb-img attribute to display an image and left justified text. Text is only left justified if you provide an image and/or accent text for the title. NOTE: You cannot use this layout in combination with back buttons or action buttons. If you use back buttons or action buttons with your title, your main title caption will be centered and the image and accent text will not be displayed.

Sample markup for the title bar image and accent text is shown below

<div data-bb-type="title" data-bb-caption="Tim Neil" data-bb-accent-text="Available" data-bb-img="foo.png"></div>

JavaScript Interface

NOTE: These changes are currently only supported with BlackBerry 10 styling

    setCaption(value);        
    getCaption();
    setBackCaption(value);
    getBackCaption();
    setActionCaption(value);
    getActionCaption();

All captions of the title bar, including buttons, can be retrieved or set via JavaScript. An example of using these functions can be found below:

    var titleBar = document.getElementById('mytitlebar');
    titleBar.setCaption('my new caption');
    alert(titleBar.getBackCaption());

An example of reassigning the onactionclick of the title bar is shown below:

    document.getElementById('mytitlebar').onactionclick = function(){alert('new');};

Upcoming Changes in v0.9.5

NOTE: These changes are in the "next" branch and will be included in the upcoming release of v0.9.5

If you would like to have colored title bars based on the highlightColor property passed into bb.init() you can specify coloredTitleBar:true in the bb.init() function.

bb.init({coloredTitleBar: true});

This will give your title bar a little bit more visual "pop". This is a nice visual touch when using the light colored controls.

JavaScript Interface

NOTE: These changes are currently only supported with BlackBerry 10 styling

You can retrieve the title bar's accent text by using the getAccentText() function.

document.getElementById('myTitle').getAccentText();