Navigation Bar

The navigation bar is shown above the actual HTML view. Since it is implemented on the native side, it is always in the correct position – you don't have to worry about CSS classes for content or anything like that.

The navigation bar has two main functions:

  • It displays a title and optional navigation bar buttons for the current view
  • When applicable, it provides you with an automatic back button for going back in the navigation stack

To learn more about how app navigation works, see the Navigation guides.

Using <super-navbar>

The <super-navbar> HTML element is a web component that can be used to declaratively define the navigation bar in your app. Adding the <super-navbar> element on a page will display the navigation bar, and the <super-navbar-title> child element will allow you to define a title text for your view.

<super-navbar>
  <super-navbar-title>
    Awesome App
  </super-navbar-title>
</super-navbar>

The <super-navbar-title> web component listens to changes in its text content and will update the navigation bar accordingly. Thus, you can use your favorite framework to make a dynamic title. For example, with AngularJS:

<super-navbar>
  <super-navbar-title ng-bind="viewTitle"></super-navbar-title>
</super-navbar>

In the above example, changes to $scope.viewTitle will cause the navigation bar to update with the new content.

Using <super-navbar-button>

You can also add native buttons to the navigation bar with the <super-navbar-button> web component. They have to be defined as children of <super-navbar>. The text content of the element defines the button text:

<super-navbar>
  <super-navbar-button>
    Tap me
  </super-navbar-button>
  <super-navbar-title>
    Awesome App
  </super-navbar-title>
</super-navbar>

Tapping the button fires a click event on the <super-navbar-button> element that you can hook to with any framework. For example, with AngularJS:

<super-navbar>
  <super-navbar-button ng-click="buttonTapped()">
    Tap me
  </super-navbar-button>
  <super-navbar-title>
    Awesome App
  </super-navbar-title>
</super-navbar>

In the above example, the function bound to $scope.buttonTapped will be called when the "Tap me" button is tapped.

To display a button on the right side of the navigation bar title, use the side="right" attribute:

<super-navbar>
  <super-navbar-title>
    Awesome App
  </super-navbar-title>
  <super-navbar-button side="right">
    Right
  </super-navbar-button>
</super-navbar>

Styling with CSS

Both the <super-navbar> and <super-navbar-button> elements can have id, class and style attributes that can be used to define how the navigation bar looks like. You can read more about the available CSS selectors in the Styling Navigation Bar guide.

However, there's a few caveats you should know.

Navigation Bar Styles Apply to the Whole Navigation Stack

Currently (due to OS limitations that we are yet to overcome) the navigation bar is shared by the whole navigation stack.

This means that if you set a CSS class for the navigation bar in index.html, the same styles will be applied to the navigation bar in show.html too, and visa versa.

However, navigation bar buttons and title are unique for the view, so you don't have to worry about them overlapping.

Note that each navigation stack has its own navigation bar (tabs and modals have their own navigation stacks).

Programmatic APIs

In addition to the web components, you can also interact with the navigation bar directly via JavaScript APIs.

Note that there are two namespaces:

  • supersonic.ui.navigationBar that deals with the navigation bar for the whole navigation stack, i.e. its visibility and CSS styles
  • supersonic.ui.views.current.navigationBar that deals with just the current view's navigation bar, i.e. its title and buttons


API Reference: supersonic.ui.navigationBar.show()

Shows the native navigation bar for the current view.

Example usage

supersonic.ui.navigationBar.show();

// with options
var options = {
  animated: false
}

supersonic.ui.navigationBar.show(options).then( function() {
  supersonic.logger.debug("Navigation bar shown without animation.");
});
supersonic.ui.navigationBar.show()

# with options
options =
  animated: false
supersonic.ui.navigationBar.show(options).then ->
  supersonic.logger.log "Navigation bar shown without animation."

Parameters

supersonic.ui.navigationBar.show: (
  options?:
    animated?: Boolean
) => Promise
Name Type Default Details
options Object {}

An object of optional parameters which define how the navigation bar will be shown.

animated Boolean true

Determines if the navigation bar will be shown with an animation.

Returns

A Promise that will be resolved after the navigation bar is shown.

Also supports callbacks.

API Reference: supersonic.ui.navigationBar.hide()

Hides the native navigation bar for the current view.

Example usage

supersonic.ui.navigationBar.hide();

// with options
var options = {
  animated: true
}

supersonic.ui.navigationBar.hide(options).then( function() {
  supersonic.logger.debug("Navigation bar hidden without animation.");
});
supersonic.ui.navigationBar.hide()

# with options
options =
  animated: true

supersonic.ui.navigationBar.hide(options).then ->
  supersonic.logger.debug "Navigation bar hidden without animation."

Parameters

supersonic.ui.navigationBar.hide: (
  options?:
    animated?: Boolean
) => Promise
Name Type Default Details
options Object

An object of optional parameters which define how the navigation bar will be hidden.

animated Boolean true

If false, the navigation bar will be hidden without an animation.

Returns

A Promise that will be resolved after the navigation bar is hidden. If the navigation bar cannot be hidden (e.g. it is already hidden), the promise will be rejected.

Also supports callbacks.

API Reference: supersonic.ui.navigationBar.update()

Updates the navigation bar. Only properties defined in the options object are affected. Other properties will continue to use the previous (or default) value.

Example usage

leftButton = new supersonic.ui.NavigationBarButton( {
  title: "Left",
  onTap: function() {
    supersonic.ui.dialog.alert("Left button tapped!");
  }
});

options = {
  title: "New title",
  overrideBackButton: true,
  buttons: {
    left: [leftButton]
  }
}

supersonic.ui.navigationBar.update(options);
leftButton = new supersonic.ui.NavigationBarButton
  title: "Left"
  onTap: ->
    supersonic.ui.dialog.alert "Left button tapped!"

options =
  title: "New title"
  overrideBackButton: true
  buttons:
    left: [leftButton]

supersonic.ui.navigationBar.update options

Parameters

supersonic.ui.navigationBar.update: (
  options:
    title?: String
    overrideBackButton?: Boolean
    backButton?: NavigationBarButton
    buttons?:
      left?: Array<NavigationBarButton>
      right?: Array<NavigationBarButton>
)
Name Type Default Details
options Object

An object of optional parameters which defines how the navigation bar will be updated.

title String

Navigation bar title text.

overrideBackButton Boolean false

If true, the automatic back button will not be shown. If defined, the first left button will be shown on its place.

backButton NavigationBarButton

A supersonic.ui.NavigationBarButton that will be used in place of the native back button.

buttons Object

An object determining the buttons that will be shown on either side of the navigation bar.

left Array<NavigationBarButton []

An array of NavigationBarButtons to be shown on the left side of the navigation bar (i.e. left side of the title text/image). Passing an empty array will remove all buttons.

right Array<NavigationBarButton []

An array of NavigationBarButtons to be shown on the right side of the navigation bar (i.e. right side of the title text/image). Passing an empty array will remove all buttons.

Returns

A Promise that will be resolved after the navigation bar has been updated. If the navigation bar cannot be updated, the promise will be rejected.

Also supports callbacks.

API Reference: supersonic.ui.navigationBar.setClass()

Adds a CSS class name to the navigation bar. Any previous CSS classes will be overriden. **Note:** At the moment, setting CSS classes for the navigation bar affects the whole navigation stack, not just the current view.

Example usage

supersonic.ui.navigationBar.setClass("my-class").then(function() {
  supersonic.logger.log("Navigation bar class was set.");
});
supersonic.ui.navigationBar.setClass("my-class").then () ->
  supersonic.logger.log "Navigation bar class was set."

Parameters

setClass: (
  className: String
) => Promise
Name Type Default Details
className String ""

A string of one or more CSS class names, separated by spaces.

Returns

A Promise that will be resolved after the navigation bar CSS class is set.

Also supports callbacks.

API Reference: supersonic.ui.navigationBar.setStyle()

Sets inline CSS styling to the navigation bar. Any previous inline styles are overridden. **Note:** At the moment, setting inline CSS styles for the navigation bar affects the whole navigation stack, not just the current view.

Example usage

supersonic.ui.navigationBar.setStyle("background-color: #ff0000;").then(function() {
  supersonic.logger.log("Navigation bar style was set.");
});
supersonic.ui.navigationBar.setStyle("background-color: #ff0000;").then () ->
  supersonic.logger.log "Navigation bar style was set."

Parameters

setStyle: (
  inlineCssString: String
) => Promise
Name Type Default Details
inlineCssString String ""

A string of inline CSS styling.

Returns

A Promise that will be resolved after the navigation bar style is set.

Also supports callbacks.

API Reference: supersonic.ui.navigationBar.setStyleId()

Sets a CSS style id for navigation bar. Any previous id will be overridden. **Note:** At the moment, setting a CSS style id for the navigation bar affects the whole navigation stack, not just the current view.

Example usage

supersonic.ui.navigationBar.setStyleId("the-button").then(function() {
  supersonic.logger.log("Navigation bar style id was set.");
});
supersonic.ui.navigationBar.setStyleId("the-button").then () ->
  supersonic.logger.log "Navigation bar style id was set."

Parameters

setStyleId: (
  id: String
) => Promise
Name Type Default Details
id String ""

The style id to set.

Returns

A Promise that will be resolved after the navigation bar style id is set.

Also supports callbacks.