From e9615191a87de0d8bdc30263d2673b3c2dd0a1f4 Mon Sep 17 00:00:00 2001 From: Tim Lancina Date: Fri, 2 Oct 2015 13:18:41 -0500 Subject: [PATCH] chore(docs): nav and navcontroller docs --- ionic/components/nav/nav-controller.ts | 29 +++++- ionic/components/nav/nav.ts | 138 +++++++++++++++++++++++-- 2 files changed, 160 insertions(+), 7 deletions(-) diff --git a/ionic/components/nav/nav-controller.ts b/ionic/components/nav/nav-controller.ts index c264b8e8d5..3eaeac525a 100644 --- a/ionic/components/nav/nav-controller.ts +++ b/ionic/components/nav/nav-controller.ts @@ -12,7 +12,16 @@ import {SwipeBackGesture} from './swipe-back'; import * as util from 'ionic/util'; /** - * TODO + * NavController is the base class for navigation controller components like + * [`Nav`](../Nav/) and [`Tab`](../../Tabs/Tab/). At a basic level, it is an array of + * [views](#creating_views) representing a particular history (of a Tab for example). + * This array can be manipulated to navigate throughout an app by pushing, + * popping, inserting and removing views. + * + *

How do I create views?

+ * Any class that is annotated with [@IonicView](../../../config/IonicView/) will + * create a view, that is, a component that can be navigated to. + * */ export class NavController extends Ion { @@ -383,6 +392,10 @@ export class NavController extends Ion { } + /** + * @private + * TODO + */ compileView(componentType) { // create a new ion-view annotation let annotation = new Component({ @@ -401,6 +414,10 @@ export class NavController extends Ion { return this.compiler.compileInHost(ionViewComponentType); } + /** + * @private + * TODO + */ createViewComponetRef(hostProtoViewRef, contentContainerRef, viewCtrlBindings) { let bindings = this.bindings.concat(Injector.resolve(viewCtrlBindings)); @@ -420,6 +437,10 @@ export class NavController extends Ion { return new ComponentRef(newLocation, newComponent, dispose); } + /** + * @private + * TODO + */ getBindings(viewCtrl) { // create bindings to this ViewController and its NavParams return this.bindings.concat(Injector.resolve([ @@ -429,6 +450,7 @@ export class NavController extends Ion { } /** + * @private * TODO */ swipeBackStart() { @@ -478,6 +500,7 @@ export class NavController extends Ion { } /** + * @private * TODO * @param {TODO} progress TODO */ @@ -555,6 +578,10 @@ export class NavController extends Ion { } + /** + * @private + * TODO + */ _runSwipeBack() { if (this.canSwipeBack()) { // it is possible to swipe back diff --git a/ionic/components/nav/nav.ts b/ionic/components/nav/nav.ts index d3ea7286ab..fb776d192a 100644 --- a/ionic/components/nav/nav.ts +++ b/ionic/components/nav/nav.ts @@ -5,7 +5,89 @@ import {IonicComponent} from '../../config/decorators'; import {NavController} from './nav-controller'; /** - * TODO + * Nav is a basic navigation controller component. It handles animating between + * incoming and outgoing views, and as a subclass of [NavController](../NavController/) + * it also exposes the underlying navigation stack. + * + * For more information on using navigation controllers like Nav or [Tabs](../../Tabs/Tabs/), + * please take a look at the [NavController API reference](../NavController/). + * + * Here is a diagram of how Nav animates smoothly between [views](../NavController/#creating_views): + * + *
+ * 
+ *                           +-------+
+ *                           |  App  |
+ *                           +---+---+
+ *                           <ion-app>
+ *                               |
+ *                  +------------+-------------+
+ *                  |   Ionic Nav Controller   |
+ *                  +------------+-------------+
+ *                           <ion-nav>
+ *                               |
+ *                               |
+ *             Pane 3  +--------------------+
+ *           Pane 2  +--------------------+ |          Has header, animates into pane 1
+ *         Pane 1  +--------------------+ | |              +--------------------+
+ *                 | | Header (Pane 1)  |<-----------------|       Login        |
+ *                 +--------------------+ | |              +--------------------+
+ *                 | | |                | | |              | Username:          |
+ *                 | | |                | | |              | Password:          |
+ *                 | | |  Pane 3 is     | | |              |                    |
+ *                 | | |  only content  | | |              |                    |
+ *                 | | |                |<-----------------|                    |
+ *                 | | |                | | |              |                    |
+ *                 | | |                | | |              |                    |
+ *                 | +------------------|-+ |              |                    |
+ *                 | | Footer (Pane 2)--|-|-+              |                    |
+ *                 | +------------------|-+                |                    |
+ *                 +--------------------+                  +--------------------+
+ *                       <ion-pane>                              <ion-view>
+ *
+ *                   Pane 1                    Pane 2                    Pane 3
+ *           +--------------------+    +--------------------+    +--------------------+
+ *           | Header             |    | Content            |    | Content            |
+ *           +--------------------+    |                    |    |                    |
+ *           | Content            |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    |                    |    |                    |
+ *           |                    |    +--------------------+    |                    |
+ *           |                    |    | Footer             |    |                    |
+ *           +--------------------+    +--------------------+    +--------------------+
+ *
+ *
+ *
+ * + * ### Panes + * + * NOTE: You don't have to do anything with panes, it is all taken care of for you. + * This is just an explanation of how Nav works to accompany the diagram above. + * + * When you push a new view onto the navigation stack using [NavController.push()](../NavController/#push) + * or the [NavPush directive](../NavPush/), Nav animates the new view into the + * appropriate pane. + * + * Panes are the containers Nav creates to animate views into. They do not have + * any content of their own, as they are just a structural reference for where + * views should animate into. + * + * The easiest scenario is animating between views with the same structure. If + * you have a view with a header and content, and navigate to another view that + * also has a header and content, Nav can smoothly animate the incoming view into + * the pane the exiting view is leaving. This allows for things like seamless header + * animations between views that both have headers. + * + * But suppose you have a view with a header and content and want to navigate to + * a view with no header. The view controller creates a new pane with no header + * that is directly behind the current pane. It then animates the exiting view + * out of the current pane and the new view into the new content-only pane. + * */ @IonicComponent({ selector: 'ion-nav', @@ -40,7 +122,7 @@ export class Nav extends NavController { } /** - * TODO + * @private */ onInit() { super.onInit(); @@ -57,6 +139,15 @@ export class Nav extends NavController { this.isSwipeBackEnabled( isSwipeBackEnabled ); } + /** + * @private + * TODO + * @param {TODO} hostProtoViewRef TODO + * @param {TODO} componentType TODO + * @param {TODO} viewCtrl TODO + * @param {Function} done TODO + * @return {TODO} TODO + */ loadContainer(hostProtoViewRef, componentType, viewCtrl, done) { // this gets or creates the Pane which similar nav items live in // Nav items with just a navbar/content would all use the same Pane @@ -129,6 +220,14 @@ export class Nav extends NavController { } } + /** + * @private + * TODO + * @param {TODO} structure TODO + * @param {TODO} viewCtrl TODO + * @param {Function} done TODO + * @return {TODO} TODO + */ getPane(structure, viewCtrl, done) { let pane = this.panes[this.panes.length - 1]; @@ -164,11 +263,22 @@ export class Nav extends NavController { } } - + /** + * @private + * TODO + * @param {TODO} pane TODO + * @return {TODO} TODO + */ addPane(pane) { this.newPane = pane; } + /** + * @private + * TODO + * @param {TODO} componentProtoViewRef TODO + * @return {TODO} TODO + */ inspectStructure(componentProtoViewRef) { let navbar = false; let tabs = false; @@ -199,10 +309,20 @@ export class Nav extends NavController { } +/** + * @private + * TODO + * @param {TODO} elementBinder TODO + * @param {TODO} id TODO + * @return {TODO} TODO + */ function isComponent(elementBinder, id) { return (elementBinder && elementBinder.componentDirective && elementBinder.componentDirective.metadata.id == id); } +/** + * @private + */ @Directive({selector: 'template[pane-anchor]'}) class NavPaneAnchor { constructor(@Host() nav: Nav, elementRef: ElementRef) { @@ -210,7 +330,9 @@ class NavPaneAnchor { } } - +/** + * @private + */ @Directive({selector: 'template[navbar-anchor]'}) class NavBarAnchor { constructor( @@ -221,7 +343,9 @@ class NavBarAnchor { } } - +/** + * @private + */ @Directive({selector: 'template[content-anchor]'}) class ContentAnchor { constructor( @@ -232,7 +356,9 @@ class ContentAnchor { } } - +/** + * @private + */ @Component({ selector: 'ion-pane', host: {