Skip to content

Commit 7a88624

Browse files
NathanWalkerNathanWalker
committed
fix: ionic portals
1 parent 1b24216 commit 7a88624

File tree

1 file changed

+337
-3
lines changed

1 file changed

+337
-3
lines changed

‎plugins/ionic-portals.md

Lines changed: 337 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,345 @@
11
---
22
title: 'Ionic Portals'
3-
link: https://raw.githubusercontent.com/NativeScript/plugins/main/packages/ionic-portals/README.md
3+
link: https://raw.githubusercontent.com/NativeScript/ui-kit/main/packages/ionic-portals/README.md
44
---
55

66
<div style="width: 100%; padding: 1.2em 0em">
77
<img alt="github logo" src="../assets/images/github/GitHub-Mark-32px.png" style="display: inline; margin: 1em 0.5em 1em 0em">
8-
<a href="https://github.com/NativeScript/plugins/tree/main/packages/ionic-portals" target="_blank" noopener>Ionic Portals</a>
8+
<a href="https://github.com/NativeScript/ui-kit/tree/main/packages/ionic-portals" target="_blank" noopener>Ionic Portals</a>
99
</div>
1010

11-
404: Not Found
11+
# @nativescript/imagepicker
12+
13+
## Contents
14+
15+
- [@nativescript/imagepicker](#nativescriptimagepicker)
16+
- [Contents](#contents)
17+
- [Intro](#intro)
18+
- [Installation](#installation)
19+
- [Enable Ionic portals in your app](#enable-ionic-portals-in-your-app)
20+
- [1. Get a Portal API Key](#1-get-a-portal-api-key)
21+
- [2. Register portals](#2-register-portals)
22+
- [3. Add portals view to markup](#3-add-portals-view-to-markup)
23+
- [Core](#core)
24+
- [Angular](#angular)
25+
- [Vue](#vue)
26+
- [Svelte](#svelte)
27+
- [Send events from NativeScript to any web portal](#send-events-from-nativescript-to-any-web-portal)
28+
- [Subscribe to events sent from web portals](#subscribe-to-events-sent-from-web-portals)
29+
- [Unsubscribe from events sent from web portals](#unsubscribe-from-events-sent-from-web-portals)
30+
- [IonicPortalManager API](#ionicportalmanager-api)
31+
- [register()](#register)
32+
- [setInitialContext()](#setinitialcontext)
33+
- [setAndroidPlugins()](#setandroidplugins)
34+
- [publishTopic()](#publishtopic)
35+
- [subscribeToTopic()](#subscribetotopic)
36+
- [unsubscribeFromTopic()](#unsubscribefromtopic)
37+
- [configureLiveUpdates()](#configureliveupdates)
38+
- [syncNow()](#syncnow)
39+
- [getLastSync()](#getlastsync)
40+
- [Using Capacitor Plugins with Ionic Portals](#using-capacitor-plugins-with-ionic-portals)
41+
- [Notes](#notes)
42+
- [Additional Resources](#additional-resources)
43+
- [License](#license)
44+
45+
## Intro
46+
47+
A plugin that allows you to use [Ionic Portals](https://ionic.io/docs/portals) in NativeScript.
48+
49+
> Ionic Portals are supercharged native WebView components for iOS and Android that let you add web-based experiences to native mobile apps.
50+
51+
![Ionic Portal View](/packages/ionic-portals/images/ionic-portal-ios.png)
52+
53+
## Installation
54+
55+
To install the plugin, run the following command from the root of your project:
56+
57+
```cli
58+
npm install @nativescript/ionic-portals
59+
```
60+
61+
## Enable Ionic portals in your app
62+
63+
Below are the steps to enable Ionic Portal in your app.
64+
65+
### 1. Get a Portal API Key
66+
67+
[Get a Portal API Key here](https://ionic.io/docs/portals/getting-started/guide).
68+
69+
### 2. Register portals
70+
71+
Register your Ionic Portals, by calling the [IonicPortalManager] class's [register()](#register) method with the [Portal API key](#1-get-a-portal-api-key).
72+
73+
```ts
74+
import { Application } from '@nativescript/core'
75+
76+
import { IonicPortalManager } from '@nativescript/ionic-portals'
77+
78+
Application.on(Application.launchEvent, () => {
79+
// Register IonicPortals
80+
IonicPortalManager.register('<portal-api-key>')
81+
})
82+
83+
// boot app here, for example:
84+
Application.run({ moduleName: 'app-root' })
85+
```
86+
87+
Create as many Portals as you need to use in your app.
88+
89+
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.
90+
91+
Given the following examples, ensure your web portal is built into the following folders:
92+
93+
- For iOS: `App_Resources/iOS/webPortal`
94+
- For Android: `App_Resources/Android/src/main/asssets/webPortal`
95+
96+
### 3. Add portals view to markup
97+
98+
#### Core
99+
100+
1. Register the plugin namespace with Page's `xmlns` attribute providing your prefix( `ionic`, for example).
101+
102+
```xml
103+
<Page xmlns:ionic="@nativescript/ionic-portals">
104+
```
105+
106+
2. Access the `IonicPortal` view through the prefix and add it to markup.
107+
108+
```xml
109+
<ionic:IonicPortal id="webPortal" />
110+
```
111+
112+
**Full code**
113+
114+
```xml
115+
<Page
116+
xmlns="http://schemas.nativescript.org/tns.xsd"
117+
xmlns:ionic="@nativescript/ionic-portals"
118+
>
119+
<StackLayout class="p-20">
120+
<ionic:IonicPortal id="webPortal" />
121+
</StackLayout>
122+
</Page>
123+
```
124+
125+
#### Angular
126+
127+
1. To add the `IonicPortal` view to the markup of any component, register it by adding the following code to the `main.ts` file:
128+
129+
```ts
130+
import { registerElement } from '@nativescript/angular'
131+
import { IonicPortal } from '@nativescript/ionic-portals'
132+
registerElement('IonicPortal', () => IonicPortal)
133+
```
134+
135+
2. Add `IonicPortal` to markup.
136+
137+
```html
138+
<IonicPortal id="webPortal"></IonicPortal>;
139+
```
140+
141+
#### Vue
142+
143+
1. To add the `IonicPortal` view in the markup of any component, register it by adding the following code to the `app.ts` file:
144+
145+
```ts
146+
import { IonicPortal } from '@nativescript/ionic-portals'
147+
148+
registerElement('IonicPortal', () => IonicPortal)
149+
```
150+
151+
2. Add `IonicPortal` to markup.
152+
153+
```xml
154+
<GridLayout height="300" class="mt-3 p-3">
155+
<IonicPortal id="webPortal" />
156+
</GridLayout>
157+
```
158+
159+
#### Svelte
160+
161+
1. To use the `IonicPortal` view in the markup of any component, register it by adding the following code to the `app.ts` file:
162+
163+
```ts
164+
import { IonicPortal } from '@nativescript/ionic-portals'
165+
166+
import { registerNativeViewElement } from 'svelte-native/dom'
167+
registerNativeViewElement('ionicPortal', () => IonicPortal)
168+
```
169+
170+
2. Add `IonicPortal` to markup.
171+
172+
```xml
173+
<gridLayout height="300" class="mt-3 p-3">
174+
<ionicPortal id="webPortal" />
175+
</gridLayout>
176+
```
177+
178+
### Send events from NativeScript to any web portal
179+
180+
To send events from NativeScript to any web portal, use the [publishTopic()](#publishtopic) method:
181+
182+
```ts
183+
IonicPortalManager.publishTopic('hello', { name: 'data from NativeScript' })
184+
```
185+
186+
#### Subscribe to events sent from web portals
187+
188+
To subscribe to events sent from any web portal, call the [subscribeToTopic](#subscribetotopic) method with the event name as the first argument and the event handler as the second argument.
189+
190+
```ts
191+
const subscriptionId = IonicPortalManager.subscribeToTopic('useful-web-event', result => {
192+
console.log('received web portal useful-web-event with data:', result.data)
193+
})
194+
```
195+
196+
#### Unsubscribe from events sent from web portals
197+
198+
To unsubscribe from events sent from any web portal, call the [unsubscribeFromTopic()](#unsubscribefromtopic) method with the event name as the first argument and the subscription id as the second argument.
199+
200+
```ts
201+
IonicPortalManager.unsubscribeFromTopic('useful-web-event', subscriptionId)
202+
```
203+
204+
## IonicPortalManager API
205+
206+
Allows you to interact with and configure portals via the following APIs.
207+
208+
### register()
209+
210+
```ts
211+
IonicPortalManager.register(apiKey)
212+
```
213+
214+
Registers portals. Call it in the `main.ts` file, before the app boots, in the handler of the `Application.launchEvent` event.
215+
216+
| Parameter | Type | Description |
217+
| :-------- | :------- | :------------------ |
218+
| `apiKey` | `string` | Your portal API key |
219+
220+
### setInitialContext()
221+
222+
```ts
223+
IonicPortalManager.setInitialContext(id, initialContext)
224+
```
225+
226+
Used to set the initial context of any portal id before the portal is shown.
227+
228+
| Parameter | Type | Description |
229+
| :--------------- | :------- | :-------------------------------------------------- |
230+
| `id` | `string` | The portal id. |
231+
| `initialContext` | `string` | Data provided as the initial context to the portal. |
232+
233+
---
234+
235+
### setAndroidPlugins()
236+
237+
```ts
238+
IonicPortalManager.setAndroidPlugins(plugins)
239+
```
240+
241+
Defines the usage of non-official Capacitor Plugins via Android package names
242+
243+
| Parameter | Type | Description |
244+
| :-------- | :--------------- | :---------------------------------------------- |
245+
| `plugins` | ` Array<string>` | A list of non-official Capacitor package names. |
246+
247+
### publishTopic()
248+
249+
```ts
250+
IonicPortalManager.publishTopic(topic, data)
251+
```
252+
253+
Sends a message to any web portal by publishing a topic (aka. event)
254+
255+
| Parameter | Type | Description |
256+
| :-------- | :-------- | :---------------------------------------------- |
257+
| `topic` | ` string` | The name of the topic/event |
258+
| `data` | ` any` | _Optional_: The payload to send with the topic. |
259+
260+
### subscribeToTopic()
261+
262+
```ts
263+
subscriptionId: number = IonicPortalManager.subscribeToTopic(topic, (data?: any) => void))
264+
```
265+
266+
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`.
267+
268+
| Parameter | Type | Description |
269+
| :--------- | :--------- | :------------------------------------------------------------------------------------------------- |
270+
| `topic` | ` string` | The name of the topic/event to subscribe to. |
271+
| `callback` | `function` | The function invoked every time a message is sent via the topic with an optional `data` parameter. |
272+
273+
---
274+
275+
### unsubscribeFromTopic()
276+
277+
```ts
278+
IonicPortalManager.unsubscribeFromTopic(topic, subscriptionId)
279+
```
280+
281+
| Parameter | Type | Description |
282+
| :--------------- | :-------- | :----------------------------------------------------------------------- |
283+
| `topic` | ` string` | The name of the topic/event to unsubscribe from. |
284+
| `subscriptionId` | `number` | The subscription id returned by [subscribeToTopic()](#subscribetotopic). |
285+
286+
### configureLiveUpdates()
287+
288+
Note: configure before displaying the portal.
289+
290+
```ts
291+
IonicPortalManager.configureLiveUpdates('webPortal', {
292+
appId: 'e2abc12',
293+
channel: 'production',
294+
syncOnAdd: true
295+
})
296+
```
297+
298+
| Parameter | Type | Description |
299+
| :--------- | :---------------------------- | :------------------------- |
300+
| `portalId` | ` string` | The portal id. |
301+
| `config` | `IonicPortalLiveUpdateConfig` | Live update configuration. |
302+
303+
### syncNow()
304+
305+
```ts
306+
IonicPortalManager.syncNow(['e2abc12'], false, status => {
307+
console.log('sync complete:', status)
308+
})
309+
```
310+
311+
| Parameter | Type | Description |
312+
| :----------- | :------------------------- | :---------------------------------- |
313+
| `appIds` | `Array<string>` | Portal app ids to sync. |
314+
| `isParallel` | `boolean` | Whether to sync in parallel or not. |
315+
| `complete` | `(status: string) => void` | Complete callback. |
316+
317+
### getLastSync()
318+
319+
```ts
320+
const lastSync = IonicPortalManager.getLastSync('e2abc12')
321+
```
322+
323+
| Parameter | Type | Description |
324+
| :-------- | :------- | :-------------------------------- |
325+
| `appId` | `string` | Portal app id to check last sync. |
326+
327+
## Using Capacitor Plugins with Ionic Portals
328+
329+
Refer to [this blog post](https://blog.nativescript.org/ionic-portals-with-capacitor-plugins).
330+
331+
## Notes
332+
333+
> For iOS:
334+
> You may need to add `IPHONEOS_DEPLOYMENT_TARGET = 12.0` to your `App_Resources/iOS/build.xcconfig` file.
335+
> If your project contains `App_Resources/iOS/Podfile`, you may need to remove any post install handling which removes deployment targets, for example:
336+
> Remove anything like this: `config.build_settings.delete 'IPHONEOS_DEPLOYMENT_TARGET'`
337+
338+
## Additional Resources
339+
340+
- You can learn more about Ionic Portals at [Opening Doors with Portals](https://www.youtube.com/watch?v=lGeeUjIMjTQ&t=609s)
341+
- Find the video's repo [here](https://github.com/NathanWalker/ioniconf2022)
342+
343+
## License
344+
345+
Apache License Version 2.0

0 commit comments

Comments
 (0)