topbar by Trigger.io

Currently displaying version

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 options

statusBarStyle
Sets the status bar style on iOS, UIStatusBarStyleDefault will use black text, UIStatusBarStyleLightContent will use white text.

API

forge.topbar.show(success, error)

iOS, Android

Shows the topbar. The topbar is shown by default and will only be hidden if you call forge.topbar.hide().

Parameters:
success
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.topbar.hide(success, error)

iOS, Android

Hides the topbar.

Parameters:
success
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.topbar.setTitle(title, success, error)

iOS, Android

Set the title displayed in the top bar.

Parameters:
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

forge.topbar.setTitleImage(image, success, error)

iOS, Android

Set the title displayed in the top bar to an image.

Parameters:
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

forge.topbar.setTint(color, success, error)

iOS, Android

Set a color to tint the topbar with, in effect the topbar will become this color.

Parameters:
color
array an array of four integers in the range [0,255] that make up the RGBA color of the topbar. 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

Note: On iOS 6 and 7 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.

forge.topbar.setTitleTint(color, success, error)

iOS, Android

Set a color to tint the topbar title with.

Parameters:
color
array an array of four integers in the range [0,255] that make up the RGBA color of the title text. 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

forge.topbar.setTranslucent(translucent, success, error)

iOS

Set the translucency effect for the TopBar on iOS.

Parameters:
translucent
bool Sets whether TopBar translucency is enabled or not.
success
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.topbar.setStatusBarStyle(style, success, error)

iOS 7 only

Set the status bar style on iOS 7, default will use black text, light_content will use white text.

Parameters:
style
string either "default or "light_content".
success
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.topbar.addButton(params, callback, error)

iOS, Android

Add a button with an icon to the top bar.

Parameters:
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

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.
  • prerendered: (Android and iOS 7 only) If true and an icon is provided the icon will not be modified when displayed, if false (or missing) the icon will be coloured with the tint colour.

Example:

forge.topbar.addButton({
  text: "Search",
  position: "left"
}, function () {
  alert("Search pressed");
});

forge.topbar.removeButtons(success, error)

iOS, Android

Remove currently added buttons from the top bar.

Parameters:
success
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

Style Guidlines

The forge.topbar.setTitleImage method and icon option in the forge.topbar.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.