From a7a2fc59bf6bcb9641be665dced7108802879a43 Mon Sep 17 00:00:00 2001 From: Manu MA Date: Tue, 22 Jan 2019 20:03:47 +0100 Subject: [PATCH] docs(angular): adds docs to angular API (#17211) --- .../navigation/ion-router-outlet.ts | 20 +++- angular/src/providers/dom-controller.ts | 8 ++ angular/src/providers/nav-controller.ts | 92 +++++++++++++++++-- angular/src/providers/platform.ts | 50 ++++++++++ angular/src/util/overlay.ts | 9 ++ 5 files changed, 165 insertions(+), 14 deletions(-) diff --git a/angular/src/directives/navigation/ion-router-outlet.ts b/angular/src/directives/navigation/ion-router-outlet.ts index ff9ba35e6c..491d240a06 100644 --- a/angular/src/directives/navigation/ion-router-outlet.ts +++ b/angular/src/directives/navigation/ion-router-outlet.ts @@ -182,20 +182,32 @@ export class IonRouterOutlet implements OnDestroy, OnInit { }); } - canGoBack(deep = 1, stackId?: string) { + /** + * Returns `true` if there are pages in the stack to go back. + */ + canGoBack(deep = 1, stackId?: string): boolean { return this.stackCtrl.canGoBack(deep, stackId); } - pop(deep = 1, stackId?: string) { + /** + * Resolves to `true` if it the outlet was able to sucessfully pop the last N pages. + */ + pop(deep = 1, stackId?: string): Promise { return this.stackCtrl.pop(deep, stackId); } - getLastUrl(stackId?: string) { + /** + * Returns the URL of the active page of each stack. + */ + getLastUrl(stackId?: string): string | undefined { const active = this.stackCtrl.getLastUrl(stackId); return active ? active.url : undefined; } - getActiveStackId() { + /** + * Returns the active stack ID. In the context of ion-tabs, it means the active tab. + */ + getActiveStackId(): string | undefined { return this.stackCtrl.getActiveStackId(); } } diff --git a/angular/src/providers/dom-controller.ts b/angular/src/providers/dom-controller.ts index 7caea0894a..a10680e9f0 100644 --- a/angular/src/providers/dom-controller.ts +++ b/angular/src/providers/dom-controller.ts @@ -5,10 +5,18 @@ import { Injectable } from '@angular/core'; }) export class DomController { + /** + * Schedules a task to run during the READ phase of the next frame. + * This task should only read the DOM, but never modify it. + */ read(cb: RafCallback) { getQueue().read(cb); } + /** + * Schedules a task to run during the WRITE phase of the next frame. + * This task should write the DOM, but never READ it. + */ write(cb: RafCallback) { getQueue().write(cb); } diff --git a/angular/src/providers/nav-controller.ts b/angular/src/providers/nav-controller.ts index 43390e8a08..7fb4cb21a7 100644 --- a/angular/src/providers/nav-controller.ts +++ b/angular/src/providers/nav-controller.ts @@ -47,34 +47,85 @@ export class NavController { platform.backButton.subscribeWithPriority(0, () => this.pop()); } + /** + * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood, + * it's equivalent to call `this.router.navigateByUrl()`, but it's explicit about the **direction** of the transition. + * + * Going **forward** means that a new page it's going to be pushed to the stack of the outlet (ion-router-outlet), + * and that it will show a "forward" animation by default. + * + * Navigating forward can also be trigger in a declarative manner by using the `[routerDirection]` directive: + * + * ```html + * Link + * ``` + */ navigateForward(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise { this.setDirection('forward', options.animated, options.animationDirection); return this.navigate(url, options); } + /** + * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood, + * it's equivalent to call: + * + * ```ts + * this.navController.setDirection('back'); + * this.router.navigateByUrl(path); + * ``` + * + * Going **back** means that all the pages in the stack until the navigated page is found will be pop, + * and that it will show a "back" animation by default. + * + * Navigating back can also be trigger in a declarative manner by using the `[routerDirection]` directive: + * + * ```html + * Link + * ``` + */ navigateBack(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise { this.setDirection('back', options.animated, options.animationDirection); return this.navigate(url, options); } + /** + * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood, + * it's equivalent to call: + * + * ```ts + * this.navController.setDirection('root'); + * this.router.navigateByUrl(path); + * ``` + * + * Going **root** means that all existing pages in the stack will be removed, + * and the navigated page will become the single page in the stack. + * + * Navigating root can also be trigger in a declarative manner by using the `[routerDirection]` directive: + * + * ```html + * Link + * ``` + */ navigateRoot(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise { this.setDirection('root', options.animated, options.animationDirection); return this.navigate(url, options); } - private navigate(url: string | UrlTree | any[], options: NavigationOptions) { - if (Array.isArray(url)) { - return this.router!.navigate(url, options); - } else { - return this.router!.navigateByUrl(url, options); - } - } - + /** + * Same as [Location](https://angular.io/api/common/Location)'s back() method. + * It will use the standard `window.history.back()` under the hood, but featuring a `back` animation. + */ back(options: AnimationOptions = { animated: true, animationDirection: 'back' }) { this.setDirection('back', options.animated, options.animationDirection); return this.location.back(); - } + } + /** + * This methods goes back in the context of ionic's stack navigation. + * + * It recursivelly finds the top active `ion-router-outlet` and calls `pop()`. + * This is the recommended way to go back when you are using `ion-router-outlet`. + */ async pop() { let outlet = this.topOutlet; @@ -85,17 +136,30 @@ export class NavController { outlet = outlet.parentOutlet; } } - } + } + /** + * This methods specifies the direction of the next navigation performed by the angular router. + * + * `setDirection()` does not trigger any transition, it just sets a set of flags to be consumed by `ion-router-outlet`. + * + * It's recommended to use `navigateForward()`, `navigateBack()` and `navigateBack()` instead of `setDirection()`. + */ setDirection(direction: RouterDirection, animated?: boolean, animationDirection?: 'forward' | 'back') { this.direction = direction; this.animated = getAnimation(direction, animated, animationDirection); } + /** + * @internal + */ setTopOutlet(outlet: IonRouterOutlet) { this.topOutlet = outlet; } + /** + * @internal + */ consumeTransition() { let direction: RouterDirection = 'root'; let animation: NavDirection | undefined; @@ -115,6 +179,14 @@ export class NavController { animation }; } + + private navigate(url: string | UrlTree | any[], options: NavigationOptions) { + if (Array.isArray(url)) { + return this.router!.navigate(url, options); + } else { + return this.router!.navigateByUrl(url, options); + } + } } function getAnimation(direction: RouterDirection, animated: boolean | undefined, animationDirection: 'forward' | 'back' | undefined): NavDirection | undefined { diff --git a/angular/src/providers/platform.ts b/angular/src/providers/platform.ts index 7e8fdfc83d..5a5be7f2c6 100644 --- a/angular/src/providers/platform.ts +++ b/angular/src/providers/platform.ts @@ -131,10 +131,45 @@ export class Platform { return getPlatforms(window); } + /** + * Returns a promise when the platform is ready and native functionality + * can be called. If the app is running from within a web browser, then + * the promise will resolve when the DOM is ready. When the app is running + * from an application engine such as Cordova, then the promise will + * resolve when Cordova triggers the `deviceready` event. + * + * The resolved value is the `readySource`, which states which platform + * ready was used. For example, when Cordova is ready, the resolved ready + * source is `cordova`. The default ready source value will be `dom`. The + * `readySource` is useful if different logic should run depending on the + * platform the app is running from. For example, only Cordova can execute + * the status bar plugin, so the web should not run status bar plugin logic. + * + * ``` + * import { Component } from '@angular/core'; + * import { Platform } from 'ionic-angular'; + * + * @Component({...}) + * export MyApp { + * constructor(public platform: Platform) { + * this.platform.ready().then((readySource) => { + * console.log('Platform ready from', readySource); + * // Platform now ready, execute any required native code + * }); + * } + * } + * ``` + */ ready(): Promise { return this._readyPromise; } + /** + * Returns if this app is using right-to-left language direction or not. + * We recommend the app's `index.html` file already has the correct `dir` + * attribute value set, such as `` or ``. + * [W3C: Structural markup and right-to-left text in HTML](http://www.w3.org/International/questions/qa-html-dir) + */ get isRTL(): boolean { return document.dir === 'rtl'; } @@ -146,10 +181,16 @@ export class Platform { return readQueryParam(window.location.href, key); } + /** + * Returns `true` if the app is in landscape mode. + */ isLandscape(): boolean { return !this.isPortrait(); } + /** + * Returns `true` if the app is in portait mode. + */ isPortrait(): boolean { return window.matchMedia('(orientation: portrait)').matches; } @@ -158,14 +199,23 @@ export class Platform { return navigator.userAgent.indexOf(expression) >= 0; } + /** + * Get the current url. + */ url() { return window.location.href; } + /** + * Gets the width of the platform's viewport using `window.innerWidth`. + */ width() { return window.innerWidth; } + /** + * Gets the height of the platform's viewport using `window.innerHeight`. + */ height(): number { return window.innerHeight; } diff --git a/angular/src/util/overlay.ts b/angular/src/util/overlay.ts index d2d49a61ce..0ad9950a6d 100644 --- a/angular/src/util/overlay.ts +++ b/angular/src/util/overlay.ts @@ -3,14 +3,23 @@ import { proxyMethod } from './util'; export class OverlayBaseController { constructor(private ctrl: string) {} + /** + * Creates a new overlay + */ create(opts?: Opts): Promise { return proxyMethod(this.ctrl, 'create', opts); } + /** + * When `id` is not provided, it dismisses the top overlay. + */ dismiss(data?: any, role?: string, id?: string): Promise { return proxyMethod(this.ctrl, 'dismiss', data, role, id); } + /** + * Returns the top overlay. + */ getTop(): Promise { return proxyMethod(this.ctrl, 'getTop'); }