Screens
The bbUI toolkit builds the application's UI in the most optimized fashion for the target operating system. It follows a methodology of a single web page that has screens loaded into it as HTML fragments. Each screen is its own HTML fragment file. The toolkit then uses AJAX to push and pop screens off of the stack. The toolkilt manages the screen stack and loading the content. This ensures the best use of device memory.
To open a new screen in an appliction using bbUI you simply call bb.pushScreen('mypage.htm', 'mypagename'). To close the top screen you simply call bb.popScreen(). The toolkit is designed to use the Application Event WebWorks API so that it can trap the "back" hardware key and automatically handle popping the last screen off of the stack.
If you want to override the back button handling on BB5/BB6/BB7, and substitute it with your own handler, you can simply assign the onbackkey property of the bb.init() function with your own function that will now be invoked when the back button is clicked. If you override the onbackkey it is up to you to handle all back button navigation.
<html>
<head>
<meta name="viewport" content="initial-scale=1.0,width=device-width,user-scalable=no,target-densitydpi=device-dpi" />
<link rel="stylesheet" type="text/css" href="bbui-0.9.3.css"></link>
<script type="text/javascript" src="bbui-0.9.3.js"></script>
</head>
<body onload="bb.pushScreen('menu.htm', 'menu');">
</body>
</html>Creating a screen to be used with bbUI is as simple as creating an HTML file and placing the screen fragment markup in the file. A screen declaration is simply a <div> with an attribute data-bb-type="screen". You then place all the contents for your screen inside this <div>.
A display effect can also be declared on your screen using the data-bb-effect attribute. Attribute values can be one of the following. NOTE: fade is the only transition effect supported on BB7. No effects are supported on BB5/BB6
- fade : Fade screen in from transparent to fully visible
- slide-left : Slide screen in towards the left (right-to-left)
- slide-right : Slide screen in towards the right (left-to-right)
- slide-up : Slide screen in upwards from the bottom (bottom-to-top)
- slide-down : Slide screen in downwards from the top (top-to-bottom)
These animations are reversed on popScreen().
You can also create a nested data-bb-type="title" <div> in your screen to declare a title bar. 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:
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.
Inertial screen scrolling effects with elastic ends are implemented by default for PlayBook only (this means no scrolling effects for other devices at the moment). This has been accomplished by integrating iScroll into bbUI.
This will provide a native scrolling experience on each of your screens. If you do not want the scrolling effects applied to a screen you can simply turn them off using the data-bb-scroll-effect="off" attribute on the
<screen> element. You may want to remove these effects on screens where you want all the content within the screen to be fixed without providing an elastic pull down effect on the content.
<div data-bb-type="screen" data-bb-scroll-effect="off">
</div>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');};NOTE: The following changes are currently in the "next" branch and will be part of v0.9.4
New functionality has been added to the pushScreen() function which allows you to pass parameters to the screen that you are opening. A third optional parameter can now be passed into the pushScreen() function. This is any object of your choice. It could be a simple string, or a JSON object. This third optional parameter will then be passed into the onscreenready and ondomready events (provided in the toolkit initialization) when they fire for the associated screen.
bb.pushScreen('foo.htm', 'myScreenId', {'hello': 'world', 'foo': 2});