Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(nav, tabs): moved details from component docs to api docs where … #7471

Merged
merged 1 commit into from
Aug 1, 2016
Merged

docs(nav, tabs): moved details from component docs to api docs where … #7471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 168 additions & 36 deletions src/components/nav/nav-controller.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,6 @@ import { ViewController } from './view-controller';
/**
* @name NavController
* @description
* _For examples on the basic usage of NavController, check out the
* [Navigation section](../../../../components/#navigation) of the Component
* docs._
*
* NavController is the base class for navigation controller components like
* [`Nav`](../Nav/) and [`Tab`](../../Tabs/Tab/). You use navigation controllers
Expand All @@ -38,6 +35,30 @@ import { ViewController } from './view-controller';
* specific NavController, most times you will inject and use a reference to the
* nearest NavController to manipulate the navigation stack.
*
* ## Basic usage
* The simplest way to navigate through an app is to create and initialize a new
* nav controller using the `<ion-nav>` component. `ion-nav` extends the `NavController`
* class.
*
* ```typescript
* import { Component } from `@angular/core`;
* import { ionicBootstrap } from 'ionic-angular';
* import { StartPage } from './start-page';
*
* @Component(
* template: `<ion-nav [root]="rootPage"></ion-nav>`
* })
* class MyApp {
* // set the rootPage to the first page we want displayed
* private rootPage: any = StartPage;
*
* constructor(){
* }
* }
*
* ionicBootstrap(MyApp);
* ```
*
* ### Injecting NavController
* Injecting NavController will always get you an instance of the nearest
* NavController, regardless of whether it is a Tab or a Nav.
Expand All @@ -52,16 +73,48 @@ import { ViewController } from './view-controller';
* [Menu](../../Menu/Menu/) and [Tab](../../Tab/Tab/)).
*
* ```ts
* import { NavController } from 'ionic-angular';
*
* class MyComponent {
* constructor(private nav: NavController) {
*
* }
* }
* ```
*
* ### Navigating from the Root component
* What if you want to control navigation from your root app component?
* You can't inject `NavController` because any components that are navigation
* controllers are _children_ of the root component so they aren't available
* to be injected.
*
* By adding a reference variable to the `ion-nav`, you can use `@ViewChild` to
* get an instance of the `Nav` component, which is a navigation controller
* (it extends `NavController`):
*
* ```typescript
*
* import { App, ViewChild } from '@angular/core';
* import { NavController } from 'ionic-angular';
*
* ## Page creation
* Pages are created when they are added to the navigation stack. For methods
* @App({
* template: '<ion-nav #myNav [root]="rootPage"></ion-nav>'
* })
* export class MyApp {
* @ViewChild('myNav') nav : NavController
* private rootPage = TabsPage;
*
* // Wait for the components in MyApp's template to be initialized
* // In this case, we are waiting for the Nav with id="my-nav"
* ngAfterViewInit() {
* // Let's navigate from TabsPage to Page1
* this.nav.push(Page1);
* }
* }
* ```
*
* ## View creation
* Views are created when they are added to the navigation stack. For methods
* like [push()](#push), the NavController takes any component class that is
* decorated with `@Component` as its first argument. The NavController then
* compiles that component, adds it to the app and animates it into view.
Expand All @@ -71,6 +124,94 @@ import { ViewController } from './view-controller';
* example). They are destroyed when removed from the navigation stack (on
* [pop()](#pop) or [setRoot()](#setRoot)).
*
* ## Pushing a View
* To push a new view on to the navigation stack, use the `push` method.
* If the page has an [`<ion-navbar>`](../api/components/nav-bar/NavBar/),
* a back button will automatically be added to the pushed view.
*
* Data can also be passed to a view by passing an object to the `push` method.
* The pushed view can then receive the data by accessing it via the `NavParams`
* class.
*
* ```typescript
* import { Component } from '@angular/core';
* import { NavController } from 'ionic-angular';
* import { OtherPage } from './other-page';
* @Component({
* template: `
* <ion-header>
* <ion-navbar>
* <ion-title>Login</ion-title>
* </ion-navbar>
* </ion-header>
*
* <ion-content>
* <button (click)="pushPage()">
* Go to OtherPage
* </button>
* </ion-content>
* `
* })
* export class StartPage {
* constructor(private nav: NavController) {
* }
*
* pushPage(){
* // push another page on to the navigation stack
* // causing the nav controller to transition to the new page
* // optional data can also be passed to the pushed page.
* this.nav.push(OtherPage, {
* id: "123",
* name: "Carl"
* });
* }
* }
*
* import { NavParams } from 'ionic-angular';
*
* @Component({
* template: `
* <ion-header>
* <ion-navbar>
* <ion-title>Other Page</ion-title>
* </ion-navbar>
* </ion-header>
* <ion-content>I'm the other page!</ion-content>`
* })
* class OtherPage {
* constructor(private navParams: NavParams) {
* let id = navParams.get('id');
* let name = navParams.get('name');
* }
* }
* ```
*
* ## Removing a view
* To remove a view from the stack, use the `pop` method.
* Popping a view will transition to the previous view.
*
* ```ts
* import { Component } from '@angular/core';
* import { NavController } from 'ionic-angular';
*
* @Component({
* template: `
* <ion-header>
* <ion-navbar>
* <ion-title>Other Page</ion-title>
* </ion-navbar>
* </ion-header>
* <ion-content>I'm the other page!</ion-content>`
* })
* class OtherPage {
* constructor(private navController: NavController ){
* }
*
* popView(){
* this.navController.pop();
* }
* }
* ```
*
* ## Lifecycle events
* Lifecycle events are fired during various stages of navigation. They can be
Expand Down Expand Up @@ -103,48 +244,39 @@ import { ViewController } from './view-controller';
* | `ionViewDidUnload` | Runs after the page has been destroyed and its elements have been removed.
*
*
* ## Nav Transition Promises
*
* Navigation transitions are asynchronous, meaning they take a few moments to finish, and
* the duration of a transition could be any number. In most cases the async nature of a
* transition doesn't cause any problems and the nav controller is pretty good about handling
* which transition was the most recent when multiple transitions have been kicked off.
* However, when an app begins firing off many transitions, on the same stack at
* *roughly* the same time, the nav controller can start to get lost as to which transition
* should be finishing, and which transitions should not be animated.
* ## Asynchronous Nav Transitions
*
* In cases where an app's navigation can be altered by other async tasks, which may or
* may not take a long time, it's best to rely on each nav transition's returned
* promise. So instead of firing and forgetting multiple `push` or `pop` nav transitions,
* it's better to fire the next nav transition when the previous one has finished.
* Navigation transitions are asynchronous operations. When a transition is started,
* the `push` or `pop` method will return immediately, before the transition is complete.
*
* In the example below, after the async operation has completed, we then want to transition
* to another page. Where the potential problem comes in, is that if the async operation
* completed 100ms after the first transition started, then kicking off another transition
* halfway through the first transition ends up with a janky animation. Instead, it's best
* to always ensure the first transition has already finished before starting the next.
* Generally, the developer does not need to be concerned about this. In the event
* multiple transitions need to be synchronized or transition timing is critical,
* the best practice is to chain the transitions together using the return value
* from the `push` and `pop` methods.
*
* ```ts
* // begin the first transition
* let navTransition = this.nav.push(SomePage);
* The `push` and `pop` methods return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
* Promises are a way to represent and chain together multiple asynchronous
* operations in order. Navigation actions can be chained together very easily using promises.
*
* // start an async call, we're not sure how long it'll take
* someAsyncOperation().then(() => {
* // incase the async operation completed faster than the time
* // it took to finish the first transition, this logic should
* // always ensure that the previous transition has resolved
* // first before kicking off the next transition
* navTransition.then(() => {
* this.nav.push(AnotherPage);
* });
* });
* ```typescript
* let navTransitionPromise = this.navController.push(Page2);
* navTransitionPromise.then( () => {
* // the transition has completed, so I can push another page now
* return this.navController.push(Page3);
* }).then( () => {
* // the second transition has completed, so I can push yet another page
return this.navController.push(Page4);
* }).then( () => {
* console.log('The transitions are complete!');
* })
* ```
*
* ## NavOptions
*
* Some methods on `NavController` allow for customizing the current transition.
* To do this, we can pass an object with the modified properites.
*
*
* | Property | Value | Description |
* |-----------|-----------|------------------------------------------------------------------------------------------------------------|
* | animate | `boolean` | Whether or not the transition should animate. |
Expand Down
84 changes: 11 additions & 73 deletions src/components/nav/nav.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,97 +11,35 @@ import { ViewController } from './view-controller';
/**
* @name Nav
* @description
* _For a quick walkthrough of navigation in Ionic, check out the
* [Navigation section](../../../../components/#navigation) of the Component
* docs._
*
* Nav is a basic navigation controller component. As a subclass of NavController
* you use it to navigate to pages in your app and manipulate the navigation stack.
* Nav automatically animates transitions between pages for you.
* `ion-nav` is the declarative component for a [NavController](../NavController/).
*
* For more information on using navigation controllers like Nav or [Tab](../../Tabs/Tab/),
* For more information on using nav controllers like Nav or [Tab](../../Tabs/Tab/),
* take a look at the [NavController API Docs](../NavController/).
*
*
* @usage
* You must set a root page to be loaded initially by any Nav you create, using
* the 'root' property:
*
* @usage
* ```ts
* import {Component} from '@angular/core';
* import {ionicBootstrap} from 'ionic-angular';
* import {GettingStartedPage} from './getting-started';
* import { Component } from '@angular/core';
* import { ionicBootstrap } from 'ionic-angular';
* import { GettingStartedPage } from './getting-started';
*
* @Component({
* template: `<ion-nav [root]="root"></ion-nav>`
* })
* class MyApp {
* root = GettingStartedPage;
* private root: any = GettingStartedPage;
*
* constructor(){
* }
* }
*
* ionicBootstrap(MyApp);
* ```
*
* ### Back Navigation
*
* If a [page](../NavController/#creating_pages) you navigate to has a [NavBar](../NavBar/),
* Nav will automatically add a back button to it if there is a page
* before the one you are navigating to in the navigation stack.
*
* Additionally, specifying the `swipeBackEnabled` property will allow you to
* swipe to go back:
* ```html
* <ion-nav swipeBackEnabled="false" [root]="rootPage"></ion-nav>
* ```
*
* Here is a diagram of how Nav animates smoothly between pages:
*
* <div class="highlight less-margin">
* <pre>
* +-------+
* | App |
* +---+---+
* &lt;ion-app&gt;
* |
* +------------+-------------+
* | Ionic Nav Controller |
* +------------+-------------+
* &lt;ion-nav&gt;
* |
* |
* Page 3 +--------------------+ LoginPage
* Page 2 +--------------------+ |
* Page 1 +--------------------+ | | +--------------------+
* | | Header |&lt;-----------------| Login |
* +--------------------+ | | +--------------------+
* | | | | | | | Username: |
* | | | | | | | Password: |
* | | | Page 3 is | | | | |
* | | | only content | | | | |
* | | | |&lt;-----------------| |
* | | | | | | | |
* | | | | | | | |
* | +------------------|-+ | | |
* | | Footer |-|-+ | |
* | +------------------|-+ | |
* +--------------------+ +--------------------+
*
* +--------------------+ +--------------------+ +--------------------+
* | Header | | Content | | Content |
* +--------------------+ | | | |
* | Content | | | | |
* | | | | | |
* | | | | | |
* | | | | | |
* | | | | | |
* | | | | | |
* | | | | | |
* | | | | | |
* | | +--------------------+ | |
* | | | Footer | | |
* +--------------------+ +--------------------+ +--------------------+
*
* </pre>
* </div>
*
* @demo /docs/v2/demos/navigation/
* @see {@link /docs/v2/components#navigation Navigation Component Docs}
Expand Down
3 changes: 2 additions & 1 deletion src/components/tabs/tab.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ import { ViewController} from '../nav/view-controller';
* The Tab component, written `<ion-tab>`, is styled based on the mode and should
* be used in conjunction with the [Tabs](../Tabs/) component.
*
* Each tab has a separate navigation controller. For more information on using
* Each `ion-tab` is a declarative component for a [NavController](../NavController/).
* Basically, each tab is a `NavController`. For more information on using
* navigation controllers take a look at the [NavController API Docs](../../nav/NavController/).
*
* See the [Tabs API Docs](../Tabs/) for more details on configuring Tabs.
Expand Down
Loading