chore(update-plugins): Tue May 24 08:05:48 UTC 2022

Author: nativescript-oss

plugins/ionic-portals.md

@@ -20,7 +20,9 @@ npm install @nativescript/ionic-portals
 
 ## Usage
 
-1. Register and create portals on app boot - [Get a Portal API Key here](https://ionic.io/docs/portals/getting-started/guide):
+### 1. Register portals on app boot
+
+[Get a Portal API Key here](https://ionic.io/docs/portals/getting-started/guide):
 
 ```ts
 import { Application } from '@nativescript/core'
@@ -29,21 +31,24 @@ import { IonicPortalManager } from '@nativescript/ionic-portals'
 Application.on(Application.launchEvent, () => {
   // Register IonicPortals
   IonicPortalManager.register('<portal-api-key>')
-
-  // Create as many Portals as you need to use in your app
-  // By default, the app will look for folders equal to the portal id you use here
-  // For iOS: App_Resources/iOS/webPortal
-  // For Android: App_Resources/Android/src/main/asssets/webPortal
-  IonicPortalManager.create('webPortal')
 })
 
 // boot app here, for example:
 Application.run({ moduleName: 'app-root' })
 ```
 
-2. Use in your views
+Create as many Portals as you need to use in your app.
+
+The app will look for folders within it's resources where the folder name is equal to the portal `id` you use to define each portal.
+
+Given the following examples, ensure your web portal is built into the following folders:
+
+- For iOS: `App_Resources/iOS/webPortal`
+- For Android: `App_Resources/Android/src/main/asssets/webPortal`
 
-### Vanilla/Plain/Core
+### 2. Use in your views
+
+#### Vanilla/Plain/Core
 
 ```xml
 <Page xmlns="http://schemas.nativescript.org/tns.xsd"
@@ -55,7 +60,7 @@ Application.run({ moduleName: 'app-root' })
 </Page>
 ```
 
-### Angular
+#### Angular
 
 ```ts
 import { registerElement } from '@nativescript/angular'
@@ -66,17 +71,74 @@ registerElement('IonicPortal', () => IonicPortal)
 ;<IonicPortal id="webPortal"></IonicPortal>
 ```
 
-### API
+## Communication
+
+- Send events from NativeScript to any web portal:
+
+```
+IonicPortalManager.publishTopic('hello', { name: 'data from NativeScript' });
+```
+
+- Subscribe to events sent from any web portal:
+
+```
+const subscriptionId = IonicPortalManager.subscribeToTopic('useful-web-event', result => {
+  console.log('received web portal useful-web-event with data:', result.data);
+});
+```
+
+- Unsubscribe from events sent from any web portal:
 
-- `IonicPortalManager.register(apiKey: string)`: Register Portals when your app boots
+```
+IonicPortalManager.unsubscribeFromTopic('useful-web-event', subscriptionId);
+```
+
+## API
 
-  - https://ionic.io/docs/portals/getting-started/guide#configure
+Interact and configure portals via `IonicPortalManager` which provides the following APIs:
 
-- `IonicPortalManager.create(portalId: string, startDir?: string)`: Create a Portal
-  - `portalId`: The portal id to register
-  - `startDir`: Set the web applications directory. By default it will look for a folder named the same as the portalId as the location of the web assets. Use this optional 2nd arg if you would like the folder name to be different that the portalId.
+```ts
+class IonicPortalManager {
+  /**
+   * Register Portals when your app boots
+   * https://ionic.io/docs/portals/getting-started/guide#configure
+   * @param apiKey your portal api key
+   */
+  static register(apiKey: string): void
+  /**
+   * Used to set the initial context of any portal id before the portal is shown
+   * @param id portal id
+   * @param initialContext data provided as the initial context to the portal
+   */
+  static setInitialContext(id: string, initialContext: any): void
+  /**
+   * Define usage of non-official Capacitor Plugins via Android package names
+   * @param plugins list of non-official Capacitor package names
+   */
+  static setAndroidPlugins(plugins: Array<string>): void
+  /**
+   * Send a message to any web portal via publishing a topic (aka. event)
+   * @param topic name of topic/event
+   * @param data payload to send
+   */
+  static publishTopic(topic: string, data?: any): void
+  /**
+   * Listen to any message sent from any web portal via subscribing to the topic (aka. event)
+   * @param topic name of topic/event
+   * @param callback method which is invoked everytime a message is sent via the topic
+   * @returns subscription id used to unsubscribe later
+   */
+  static subscribeToTopic(topic: string, callback: (data?: any) => void): number
+  /**
+   * Unsubscribe from any topic (aka. event)
+   * @param topic name of topic/event
+   * @param subscriptionId subscription id
+   */
+  static unsubscribeFromTopic(topic: string, subscriptionId: number): void
+}
+```
 
-### Use Capacitor Plugins
+## Use Capacitor Plugins
 
 Refer [to this blog post](https://blog.nativescript.org/ionic-portals-with-capacitor-plugins).