topbar: Native top bar¶
The topbar module displays a fixed native header bar in mobile apps and provides a Javascript API to modify it at runtime.
To get an idea of how these headers can look, see our blog post, How to build hybrid mobile apps combining native UI components with HTML5.
Config¶
The topbar module must be enabled in config.json as follows:
{
"modules": {
"topbar": true
}
}
Style Guidlines¶
The setTitleImage method and icon option in the addButton method allow you to specify images within the topbar element. These guidelines may help you to make them look good across devices:
- The title image will be scaled down (but not up) to fit the height of the topbar exactly. This means any padding should be included in the image, and the image should be at least 100px high.
- The button icons will also be scaled down (but not up) to fit the height of the button precisely. The width of the button is the width of the icon (or text) plus a small amount of padding. We'd recommend button icons are at least 64px high to make sure they always fill the button.
- The total width of the title and buttons is not checked by Forge, so its up to you to test everything fits, We'd recommend leaving spare space to make sure devices with unexpected screen ratios don't overlap.
API¶
show¶
Platforms: Mobile
Shows the topbar. The topbar is shown by default and will only be hidden if you call topbar.hide().
- topbar.show(success, error)¶
Arguments: - success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
hide¶
Platforms: Mobile
Hides the topbar.
- topbar.hide(success, error)¶
Arguments: - success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
setTitle¶
Platforms: Mobile
Set the title displayed in the top bar.
- topbar.setTitle(title, success, error)¶
Arguments: - title (string) -- Title to be displayed
- success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
setTitleImage¶
Platforms: Mobile
Set the title displayed in the top bar to an image.
- topbar.setTitleImage(image, success, error)¶
Arguments: - image (file) -- file object as returned by something like forge.file.saveURL, or a string path relative to the src directory, e.g. "img/button.png"
- success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
setTint¶
Platforms: Mobile
Set a colour to tint the topbar with, in effect the topbar will become this colour with a gradient effect applied.
On iOS 6 this color will also be used to tint the status bar, you can use this in combination with hiding the topbar if you only want a colored status bar and not a topbar.
- topbar.setTint(color, success, error)¶
Arguments: - color (array) -- an array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255].
- success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
addButton¶
Platforms: Mobile
Add a button with an icon to the top bar. The first parameter is an object describing the button with the following properties:
- icon: An icon to be shown on the button: this should be relative to the src directory, e.g. "img/button.png".
- text: Text to be shown on the button, either text or icon must be set.
- type: Create a special type of button, the only option currently is "back" which means the button will cause the webview to go back when pressed.
- style: Use a predefined style for the button, currently this can either be "done" which will style a positive action (which may be overriden by tint), or "back" to show a back arrow style button on iOS.
- position: The position to display the button, either left or right. If not specified the first free space will be used.
- tint: The color of the button, defined as an array similar to setTint.
Example:
forge.topbar.addButton({
text: "Search",
position: "left"
}, function () {
alert("Search pressed");
});
- topbar.addButton(params, callback, error)¶
Arguments: - params (object) -- Button options, must contain at least icon or text
- callback (function()) -- callback to be invoked each time the button is pressed
- error (function(content)) -- called with details of any error which may occur