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 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>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});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>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
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 dimentions
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 as well as an optional time parameter in milliseconds to animate the scroll. If no animation is desired then time should be omitted or specified as 0.
document.getElementById('myScreen').scrollTo(0,100,250);If you want to scroll relative to the current scroll position (i.e. scroll 10 pixels down) then you can specify true for the relative parameter.
document.getElementById('myScreen').scrollTo(0, 10, 20, true); 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 and an optional time parameter for how long you want the animation to last.
var element = document.getElementById('myitem');
document.getElementById('myScreen').scrollToElement(element, 100);