Ionic Navigation

---

ion-nav-view

When users navigate through your app, Ionic is able to detect the browsing history. By detecting the browsing history, views can be correctly transitioned when swiping left or right.

Using the AngularUI Router module, the application interfaces can be divided into different $states (states). At the core of Angular is the routing service, where URLs can be used to control views.

AngularUI Router provides more powerful state management, meaning states can be named, nested, and views combined, allowing more than one template to be rendered on the same page.

In addition, each state does not need to be bound to a URL, and data can be pushed to each state more flexibly.

In the following example, we will create an application containing navigation views with different states.

In our markup, we select ionNavView as the top-level directive. To display a header bar, we use the ionNavBar directive, which is updated through navigation.

Next, we need to set the state value that our app will render.

var app = angular.module('myApp', ['ionic']);
app.config(function($stateProvider) {
  $stateProvider
  .state('index', {
    url: '/',
    templateUrl: 'home.html'
  })
  .state('music', {
    url: '/music',
    templateUrl: 'music.html'
  });
});

When the app opens, $stateProvider will query the URL to see if it matches the index state, then load index.html into `<ion-nav-view>`.

Page loading is configured through URLs. In Angular, one of the simplest ways to create a template is to place it directly in an HTML template file and include it with `<script type="text/ng-template">`.

So this is also a way to include Home.html into our app:

<script id="home" type="text/ng-template">
  <!--  ion-view 标题将显示在 navbar 中 -->
  <ion-view view-title="Home">
    <ion-content ng-controller="HomeCtrl">
      <!-- The content of the page -->
      <a href="../index.html">Go to music page!</a>
    </ion-content>
  </ion-view>
</script>

Try it »

This is a good approach because the template will be loaded quickly and cached, so there is no need to load it again over the network.

---

Cache

Usually, views are cached to improve performance. When you leave a view, its elements are kept in the DOM, and its scope is removed from $watch.

When we navigate to a view that has already been cached, the view is activated, its scope is reconnected, and its elements are kept in the DOM. This also allows the previous scroll position of the view to be preserved.

Caching can also be enabled and disabled in many ways. By default, Ionic maxes out at 10 cached pages, and this is not the only thing that can be customized; applications can explicitly set whether a view should be cached.

Note that because we cache these views, we do not destroy scopes. Instead, its scope is also removed from $watch.

Because the scopes of these views are not destroyed and rebuilt, the controllers are not loaded again. If an app/controller needs to know when entering or leaving a view, view events emitted from within the ionView scope, such as $ionicView.enter, may be useful.

Globally Disable Caching

$ionicConfigProvider can be used to set the maximum number of allowed cached views, and by setting it to 0, all caching can be disabled.

$ionicConfigProvider.views.maxCache(0);

Disable Caching in the State Provider

$stateProvider.state('myState', {
   cache: false,
   url : '/myUrl',
   templateUrl : 'my-template.html'
})

Disable Caching via Attributes

<ion-view cache-view="false" view-title="My Title!">
  ...
</ion-view>

AngularUI Router

Please visitAngularUI Router's docsto learn more.

API

Attributes	Type	Details
name (Optional)	string	A name of the view. This name should be unique among other views in the same state. You can have views with the same name in different states. For more details, see the ui-router'sui-view documentation。

---

ion-view

Belongs to ionNavView. A content container for displaying views or navigation bar information.

Below is an example of a page loaded with a navigation bar titled "My Page".

<ion-nav-bar></ion-nav-bar>
<ion-nav-view class="slide-left-right">
  <ion-view title="我的页面">
    <ion-content>
      你好!
    </ion-content>
  </ion-view>
</ion-nav-view>

API

Attributes	Type	Details
title (Optional)	string	Displayed on the parentionNavBartitle.
hide-back-button (Optional)	boolean	By default, whether on the parentionNavBarhide the back button.
hide-nav-bar (Optional)	boolean	By default, whether to hide the parentionNavBar。

---

ion-nav-bar

Creates a top toolbar that updates when the app state changes.

Usage

<body ng-app="starter">
  <!-- 当我们浏览时，导航栏会随之更新。 -->
  <ion-nav-bar class="bar-positive nav-title-slide-ios7">
  </ion-nav-bar>

  <!-- 初始化时渲染视图模板 -->
  <ion-nav-view></ion-nav-view>
</body>

API

Attributes	Type	Details
delegate-handle (Optional)	string	This handle is used to$ionicNavBarDelegateidentify this navigation bar.
align-title (Optional)	string	The alignment position of the navigation bar title. Options: 'left', 'right', 'center'. Defaults to 'center'.

---

ion-nav-buttons

Belongs to ionNavView

Use ionNavButtons to set buttons on the ionNavBar within an ionView.

Any buttons you set will be placed in the corresponding positions in the navigation bar, and will be destroyed when the user leaves the parent view.

Usage

<ion-nav-bar>
</ion-nav-bar>
<ion-nav-view>
  <ion-view>
    <ion-nav-buttons side="left">
      <button class="button" ng-click="doSomething()">
        我是一个在导航栏左侧的按钮！
      </button>
    </ion-nav-buttons>
    <ion-content>
      这里是一些内容！
    </ion-content>
  </ion-view>
</ion-nav-view>

API

Attributes	Type	Details
side	string	On the parentionNavBarthe position where buttons are placed. Options: 'left' or 'right'.

---

ion-nav-back-button

Creates a button within an ionNavBar.

The back button will be displayed when the user can go back in the current navigation.

Usage

Default button behavior:

<ion-nav-bar>
  <ion-nav-back-button class="button-clear">
    <i class="ion-arrow-left-c"></i> 后退
  </ion-nav-back-button>
</ion-nav-bar>

Custom click action, using $ionicNavBarDelegate:

<ion-nav-bar ng-controller="MyCtrl">
  <ion-nav-back-button class="button-clear"
    ng-click="canGoBack && goBack()">
    <i class="ion-arrow-left-c"></i> 后退
  </ion-nav-back-button>
</ion-nav-bar>

function MyCtrl($scope, $ionicNavBarDelegate) {
  $scope.goBack = function() {
    $ionicNavBarDelegate.back();
  };
}

Also use $ionicNavBarDelegate to display the previous title on the back button.

<ion-nav-bar ng-controller="MyCtrl">
  <ion-nav-back-button class="button-icon">
    <i class="icon ion-arrow-left-c"></i>{{getPreviousTitle() || 'Back'}}
  </ion-nav-back-button>
</ion-nav-bar>

function MyCtrl($scope, $ionicNavBarDelegate) {
  $scope.getPreviousTitle = function() {
    return $ionicNavBarDelegate.getPreviousTitle();
  };
}

---

nav-clear

nav-clear is an attribute directive used when clicking elements in a view, such as an `<a href>` or a `<button ui-sref>`.

When clicked, nav-clear will cause the given element to disable the next view transition. This directive is useful, for example, for links inside a sidebar menu.

Usage

Below is a link inside a sidebar menu with the nav-clear directive added. Clicking this link will disable any animations between views.

<a nav-clear menu-close href="../index.html" class="item">首页</a>

---

ion-nav-title

ion-nav-title is used to set the title in the ion-view template.

Usage

<ion-nav-bar>
</ion-nav-bar>
<ion-nav-view>
  <ion-view>
    <ion-nav-title>
      <img src="logo.svg.html">
    </ion-nav-title>
    <ion-content>
      Some super content here!
    </ion-content>
  </ion-view>
</ion-nav-view>

---

nav-transition

Set the transition type used, which can be: ios, android, and none.

Usage

<a nav-transition="none" href="../index.html">Home</a>

---

nav-direction

Set the direction of the transition animation in the navigation view, which can be forward, back, enter, exit, swap.

Usage

<a nav-direction="forward" href="../index.html">Home</a>

---

$ionicNavBarDelegate

Delegate to control the ion-nav-bar directive.

Usage

<body ng-controller="MyCtrl">
  <ion-nav-bar>
    <button ng-click="setNavTitle('banana')">
      Set title to banana!
    </button>
  </ion-nav-bar>
</body>

function MyCtrl($scope, $ionicNavBarDelegate) {
  $scope.setNavTitle = function(title) {
    $ionicNavBarDelegate.title(title);
  }
}

Methods

align([direction])

Go back in the browsing history.

Parameters	Type	Details
event (Optional)	DOMEvent	Event object (e.g., from a click event)

align([direction])

Aligns the title with buttons to the specified direction.

Parameters	Type	Details
direction (Optional)	string	The direction to align the title text. Options: 'left', 'right', 'center'. Default: 'center'.

Return value:Boolean, whether the back button is displayed.

showBar(show)

Set or get whether the ion-nav-bar is displayed.

Parameters	Type	Details
show	boolean	Whether the navigation bar is displayed.

Return value:Boolean, whether the navigation bar is displayed.

showBackButton([show])

Set or get whether the ion-nav-back-button is displayed.

Parameters	Type	Details
show (Optional)	boolean	Whether to show the back button

title(title)

Sets the title for the ion-nav-bar.

Parameters	Type	Details
title	string	The new title to display.

---

$ionicHistory

$ionicHistory is used to track the user's browsing history within the app.

Methods

viewHistory()

Used to view the history records.

currentView()

The app's current view.

currentHistoryId()

The ID of the history stack, which is the parent container of the current view.

currentTitle([val])

Get or set the title of the current view.

backView()

Returns the last viewed view.

backTitle()

Get the title of the last viewed view.

forwardView()

Return to the previous view of the current view in the history stack.

currentStateName()

Return the current state name.

goBack([backCount])

App falls back to the view, if the fallback view exists.

Other extensions