docs(alert): dismissing and async navigation

ionic/components/alert/alert.ts

@@ -128,6 +128,62 @@ import {ViewController} from '../nav/view-controller';
  * }
  * ```
  *
+ *
+ * ### Dismissing And Async Navigation
+ *
+ * After an alert has been dismissed, the app may need to also transition
+ * to another page depending on the handler's logic. However, because multiple
+ * transitions were fired at roughly the same time, it's difficult for the
+ * nav controller to cleanly animate multiple transitions that may
+ * have been kicked off asynchronously. This is further described in the
+ * [`Nav Transition Promises`](../../nav/NavController) section. For alerts,
+ * this means it's best to wait for the alert to finish its transition
+ * out before starting a new transition on the same nav controller.
+ *
+ * In the example below, after the alert button has been clicked, its handler
+ * waits on async operation to complete, *then* it uses `pop` to navigate
+ * back a page in the same stack. The potential problem is that the async operation
+ * may have been completed before the alert has even finished its transition
+ * out. In this case, it's best to ensure the alert has finished its transition
+ * out first, *then* start the next transition.
+ *
+ * ```ts
+ * let alert = Alert.create({
+ *   title: 'Hello',
+ *   buttons: [{
+ *     text: 'Ok',
+ *     handler: () => {
+ *       // user has clicked the alert button
+ *       // begin the alert's dimiss transition
+ *       let navTransition = alert.dismiss();
+ *
+ *       // start some async method
+ *       someAsyncOperation(() => {
+ *         // once the async operation has completed
+ *         // then run the next nav transition after the
+ *         // first transition has finished animating out
+ *
+ *         navTransition.then(() => {
+ *           this.nav.pop();
+ *         });
+ *       });
+ *       return false;
+ *     }
+ *   }]
+ * });
+ *
+ * this.nav.present(alert);
+ * ```
+ *
+ * It's important to note that the the handler returns `false`. A feature of
+ * button handlers is that they automatically dismiss the alert when their button
+ * was clicked, however, we'll need more control regarding the transition. Because
+ * the handler returns `false`, then the alert does not automatically dismiss
+ * itself. Instead, you now have complete control of when the alert has finished
+ * transitioning, and the ability to wait for the alert to finish transitioning
+ * out before starting a new transition.
+ *
+ *
  * @demo /docs/v2/demos/alert/
  */
 export class Alert extends ViewController {

ionic/components/alert/test/dismiss/index.ts

@@ -1,4 +1,4 @@
-import { Alert, NavController, App, Page } from 'ionic-angular/index';
+import { Alert, Loading, NavController, App, Page } from 'ionic-angular/index';
 import { FORM_DIRECTIVES, FormBuilder, ControlGroup, Validators } from 'angular2/common';
 
 
@@ -51,6 +51,9 @@ export class E2EPage {
       		</button>
     		</div>
 			</form>
+      <p>
+        <button block (click)="doFastPop()">Fast Loading Dismiss, Nav Pop</button>
+      </p>
     </ion-content>
   `
 })
@@ -107,6 +110,46 @@ class AnotherPage {
     this.nav.present(alert);
   }
 
+  doFastPop() {
+    let alert = Alert.create({
+      title: 'Async Nav Transition',
+      message: 'This is an example of dismissing an alert, then quickly starting another transition on the same nav controller.',
+      buttons: [{
+        text: 'Ok',
+        handler: () => {
+          // present a loading indicator
+          let loading = Loading.create({
+            content: 'Loading...'
+          });
+          this.nav.present(loading);
+
+          // start an async operation
+          setTimeout(() => {
+            // the async operation has completed
+            // dismiss the loading indicator
+            loading.dismiss();
+
+            // begin dismissing the alert
+            alert.dismiss().then(() => {
+              // after the alert has been dismissed
+              // then you can do another nav transition
+              this.nav.pop();
+            });
+          }, 100);
+
+          // return false so the alert doesn't automatically
+          // dismissed itself. Instead we're manually
+          // handling the dismiss logic above so that we
+          // can wait for the alert to finish it's dismiss
+          // transition before starting another nav transition
+          // on the same nav controller
+          return false;
+        }
+      }]
+    });
+    this.nav.present(alert);
+  }
+
 }