README.md

@nativescript/ionic-portals

Contents

• @nativescript/ionic-portals
  • Contents
  • Intro
  • Installation
  • Enable Ionic portals in your app
    • 1. Get a Portal API Key
    • 2. Register portals
    • 3. Add portals view to markup
      • Core
      • Angular
      • Vue
      • Svelte
    • Send events from NativeScript to any web portal
      • Subscribe to events sent from web portals
      • Unsubscribe from events sent from web portals
  • IonicPortalManager API
    • register()
    • setInitialContext()
    • setAndroidPlugins()
    • publishTopic()
    • subscribeToTopic()
    • unsubscribeFromTopic()
    • configureLiveUpdates()
    • syncNow()
    • getLastSync()
  • Using Capacitor Plugins with Ionic Portals
  • Notes
  • Additional Resources
  • License

Intro

A plugin that allows you to use Ionic Portals in NativeScript.

Ionic Portals are supercharged native WebView components for iOS and Android that let you add web-based experiences to native mobile apps.

Installation

To install the plugin, run the following command from the root of your project:

npm install @nativescript/ionic-portals

Enable Ionic portals in your app

Below are the steps to enable Ionic Portal in your app.

1. Get a Portal API Key

Get a Portal API Key here.

2. Register portals

Register your Ionic Portals, by calling the [IonicPortalManager] class's register() method with the Portal API key.

import { Application } from '@nativescript/core';

import { IonicPortalManager } from '@nativescript/ionic-portals';

Application.on(Application.launchEvent, () => {
	// Register IonicPortals
	IonicPortalManager.register('<portal-api-key>');
});

// boot app here, for example:
Application.run({ moduleName: 'app-root' });

Create as many Portals as you need to use in your app.

The app will look for folders within its resources where the folder name is equal to the portal id you used 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

3. Add portals view to markup

Core

1. Register the plugin namespace with Page's xmlns attribute providing your prefix( ionic, for example).

<Page xmlns:ionic="@nativescript/ionic-portals">

2. Access the IonicPortal view through the prefix and add it to markup.

<ionic:IonicPortal id="webPortal">
    </ionic:IonicPortal>

Full code

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:ionic="@nativescript/ionic-portals">
  <StackLayout class="p-20">
    <ionic:IonicPortal id="webPortal">
    </ionic:IonicPortal>
  </StackLayout>
</Page>

Angular

1. To add the IonicPortal view to the markup of any component, register it by adding the following code to the main.ts file:

import { registerElement } from '@nativescript/angular';
import { IonicPortal } from '@nativescript/ionic-portals';
registerElement('IonicPortal', () => IonicPortal);

2. Add IonicPortal to markup.

<IonicPortal id="webPortal"></IonicPortal>;

Vue

1. To add the IonicPortal view in the markup of any component, register it by adding the following code to the app.ts file:

import { IonicPortal } from '@nativescript/ionic-portals';

registerElement("IonicPortal", ()=> IonicPortal)

2. Add IonicPortal to markup.

 <GridLayout height="300" class="mt-3 p-3">
    <IonicPortal id="webPortal"/>
</GridLayout>

Svelte

1. To use the IonicPortal view in the markup of any component, register it by adding the following code to the app.ts file:

import { IonicPortal } from '@nativescript/ionic-portals';

import {registerNativeViewElement} from "svelte-native/dom"
registerNativeViewElement("ionicPortal", ()=> IonicPortal)

2. Add IonicPortal to markup.

<gridLayout height="300" class="mt-3 p-3">
    <ionicPortal id="webPortal"/>
</gridLayout>

Send events from NativeScript to any web portal

To send events from NativeScript to any web portal, use the publishTopic() method:

IonicPortalManager.publishTopic('hello', { name: 'data from NativeScript' });

Subscribe to events sent from web portals

To subscribe to events sent from any web portal, call the subscribeToTopic method with the event name as the first argument and the event handler as the second argument.

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 web portals

To unsubscribe from events sent from any web portal, call the unsubscribeFromTopic() method with the event name as the first argument and the subscription id as the second argument.

IonicPortalManager.unsubscribeFromTopic('useful-web-event', subscriptionId);

IonicPortalManager API

Allows you to interact with and configure portals via the following APIs.

register()

IonicPortalManager.register(apiKey)

Registers portals. Call it in the main.ts file, before the app boots, in the handler of the Application.launchEvent event.

Parameter	Type	Description
apiKey	string	Your portal API key

setInitialContext()

IonicPortalManager.setInitialContext(id,initialContext)

Used to set the initial context of any portal id before the portal is shown.

Parameter	Type	Description
id	string	The portal id.
initialContext	string	Data provided as the initial context to the portal.

---

setAndroidPlugins()

IonicPortalManager.setAndroidPlugins(plugins)

Defines the usage of non-official Capacitor Plugins via Android package names

Parameter	Type	Description
plugins	Array<string>	A list of non-official Capacitor package names.

publishTopic()

IonicPortalManager.publishTopic(topic, data)

Sends a message to any web portal by publishing a topic (aka. event)

Parameter	Type	Description
topic	string	The name of the topic/event
data	any	Optional: The payload to send with the topic.

subscribeToTopic()

subscriptionId: number = IonicPortalManager.subscribeToTopic(topic, (data?: any) => void))

Listens to any message sent from any web portal by subscribing to the specified topic. It returns a subscription id used to later unsubscribe from the topic.

Parameter	Type	Description
topic	string	The name of the topic/event to subscribe to.
callback	function	The function invoked every time a message is sent via the topic with an optional data parameter.

---

unsubscribeFromTopic()

IonicPortalManager.unsubscribeFromTopic(topic, subscriptionId)

Parameter	Type	Description
topic	string	The name of the topic/event to unsubscribe from.
subscriptionId	number	The subscription id returned by subscribeToTopic().

configureLiveUpdates()

Note: configure before displaying the portal.

IonicPortalManager.configureLiveUpdates('webPortal', {
	appId: 'e2abc12',
	channel: 'production',
	syncOnAdd: true
})

Parameter	Type	Description
portalId	string	The portal id.
config	IonicPortalLiveUpdateConfig	Live update configuration.

syncNow()

IonicPortalManager.syncNow(['e2abc12'], false, status => {
	console.log('sync complete:', status)
})

Parameter	Type	Description
appIds	Array<string>	Portal app ids to sync.
isParallel	boolean	Whether to sync in parallel or not.
complete	(status: string) => void	Complete callback.

getLastSync()

const lastSync = IonicPortalManager.getLastSync('e2abc12')

Parameter	Type	Description
appId	string	Portal app id to check last sync.

Using Capacitor Plugins with Ionic Portals

Refer to this blog post.

Notes

For iOS: You may need to add IPHONEOS_DEPLOYMENT_TARGET = 12.0 to your App_Resources/iOS/build.xcconfig file. If your project contains App_Resources/iOS/Podfile, you may need to remove any post install handling which removes deployment targets, for example: Remove anything like this: config.build_settings.delete 'IPHONEOS_DEPLOYMENT_TARGET'

Additional Resources

• You can learn more about Ionic Portals at Opening Doors with Portals
  • Find the video's repo here

License

Apache License Version 2.0