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.
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>.
You can also define a Title Bar for your screen that will add extra functionality depending on the BlackBerry Operating system.
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().
When using BlackBerry 10 styling an additional data-bb-indicator="true" attribute is available. When this attribute is specified, an Activity Indicator will be shown inside your screen content (between the Action Bar and the screen Title) until you have finished processing your data in the ondomready event for the screen.
Once processing in the ondomready has completed, the Activity Indicator will disappear and your screen's content will be shown.
<div data-bb-type="screen" data-bb-indicator="true">
</div>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>
<link rel="stylesheet" type="text/css" href="bbui.css"></link>
<script type="text/javascript" src="bbui.js"></script>
<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript">
document.addEventListener('webworksready', function(e) {
bb.init();
// Open our first screen
bb.pushScreen('firstScreen.htm', 'firstScreen');
}, false);
</script>
</head>
<body>
</body>
</html>The pushScreen() function also 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});An example of retrieving the contents of your parameter in the onscreen ready event is shown below
bb.init({onscreenready : function(element, id, params) {
if (id == 'myScreenId') {
alert(params.hello + ' ' + params.foo);
}
}
});Inertial screen scrolling effects with elastic ends are implemented by default for PlayBook and BlackBerry 10 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>The following JavaScript interfaces are available for dynamically manipulating a Screen after the screen has been added to the DOM
NOTE: Screen scrolling functions only work if you have scrolling effects turned on for your screen. This means it is only available on BlackBerry PlayBook and BlackBerry 10 styling
Screens now support an onscroll event. If you want to know when the user is scrolling screen content you can assign a handler to the onscroll event
<div data-bb-type="screen" onscroll="doSomething()">
...
</div>If you have manipulated the content of a screen via JavaScript (added, removed, changed sizes of elements) you will want to call refresh() so that it can recalculate its scrolling dimensions. NOTE: This is only necessary for PlayBook
document.getElementById('myScreen').refresh();You can also scroll to a specific x,y coordinate by using the scrollTo() function. It takes both an x and y coordinate. The y coordinate is for future use, but currently isn't implemented.
document.getElementById('myScreen').scrollTo(100,0);If you have an element in the screen that you would like to scroll to, you can use the scrollToElement() function. This function takes in the element to scroll to.
var element = document.getElementById('myitem');
document.getElementById('myScreen').scrollToElement(element); The getActionBarHeight() function is available on the bb.screen object for BlackBerry 10 styling. This will return the standard height of the action bar in pixels.
alert(bb.screen.getActionBarHeight()); The getTitleBarHeight() function is available on the bb.screen object for BlackBerry 10 styling. This will return the standard height of the title bar in pixels.
alert(bb.screen.getTitleBarHeight());