feat(platform): add a readySource as ready resolved value

Author: adamdbradley

ionic/components/modal/test/basic/index.ts

@@ -25,8 +25,8 @@ class E2EPage {
     console.log('android', platform.is('android'));
     console.log('windows phone', platform.is('windows'));
 
-    platform.ready().then(() => {
-      console.log('platform.ready');
+    platform.ready().then((readySource) => {
+      console.log('platform.ready, readySource:', readySource);
     });
 
     this.platforms = platform.platforms();

ionic/platform/platform.ts

@@ -175,48 +175,59 @@ export class Platform {
    * 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.
+   * 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 {Platform} from 'ionic-angular';
+   * import {App, Platform} from 'ionic-angular';
    *
-   * @Page({...})
-   * export MyPage {
+   * @App({...})
+   * export MyApp {
    *   constructor(platform: Platform) {
-   *     platform.ready().then(() => {
-   *       console.log('Platform ready');
-   *       // The platform is now ready, execute any native code you want
+   *     platform.ready().then((readySource) => {
+   *       console.log('Platform ready from', readySource);
+   *       // Platform now ready, execute any required native code
    *     });
    *   }
    * }
    * ```
    * @returns {promise}
    */
-  ready(): Promise<any> {
-    // this is the default if it's not replaced by the engine
-    // if there was no custom ready method from the engine
-    // then use the default DOM ready
+  ready(): Promise<string> {
     return this._readyPromise;
   }
 
   /**
    * @private
+   * This should be triggered by the engine when the platform is
+   * ready. If there was no custom prepareReady method from the engine,
+   * such as Cordova or Electron, then it uses the default DOM ready.
    */
-  triggerReady() {
+  triggerReady(readySource: string) {
     this._zone.run(() => {
-      this._readyResolve();
+      this._readyResolve(readySource);
     });
   }
 
   /**
    * @private
+   * This is the default prepareReady if it's not replaced by an engine,
+   * such as Cordova or Electron. If there was no custom prepareReady
+   * method from an engine then it uses the method below, which triggers
+   * the platform ready on the DOM ready event, and the default resolved
+   * value is `dom`.
    */
   prepareReady() {
-    // this is the default prepareReady if it's not replaced by the engine
-    // if there was no custom ready method from the engine
-    // then use the default DOM ready
-    ready(this.triggerReady.bind(this));
+    ready(() => {
+      this.triggerReady('dom');
+    });
   }
 
   /**

ionic/platform/registry.ts

@@ -192,7 +192,7 @@ Platform.register({
           };
 
           // cordova has fully loaded and we've added listeners
-          p.triggerReady();
+          p.triggerReady('cordova');
         });
       });
     };