iframe-coordinator-cli 6.5.0 → 6.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/assets/{index-DkVijnku.js → index-DejhDHus.js} +3 -3
- package/dist/ifc-docs/assets/hierarchy.js +1 -1
- package/dist/ifc-docs/assets/highlight.css +130 -91
- package/dist/ifc-docs/assets/icons.js +20 -17
- package/dist/ifc-docs/assets/icons.svg +1 -1
- package/dist/ifc-docs/assets/main.js +2535 -5
- package/dist/ifc-docs/assets/navigation.js +2 -1
- package/dist/ifc-docs/assets/search.js +2 -1
- package/dist/ifc-docs/assets/style.css +1571 -1581
- package/dist/ifc-docs/classes/client.Client.html +2388 -98
- package/dist/ifc-docs/classes/client.WorkerClient.html +2161 -92
- package/dist/ifc-docs/classes/host.FrameRouterElement.html +850 -24
- package/dist/ifc-docs/classes/host.WorkerPool.html +879 -29
- package/dist/ifc-docs/documents/client-setup.html +579 -75
- package/dist/ifc-docs/functions/host.registerCustomElements.html +218 -3
- package/dist/ifc-docs/hierarchy.html +168 -1
- package/dist/ifc-docs/index.html +432 -31
- package/dist/ifc-docs/interfaces/client.ClientConfigOptions.html +331 -4
- package/dist/ifc-docs/interfaces/client.EventEmitter.html +752 -14
- package/dist/ifc-docs/interfaces/host.ClientConfig.html +399 -7
- package/dist/ifc-docs/interfaces/host.ClientRegistration.html +580 -24
- package/dist/ifc-docs/interfaces/host.RoutingMap.html +211 -4
- package/dist/ifc-docs/interfaces/host.WorkerAppData.html +388 -6
- package/dist/ifc-docs/interfaces/host.WorkerConfig.html +398 -7
- package/dist/ifc-docs/interfaces/host.WorkerItem.html +401 -6
- package/dist/ifc-docs/interfaces/host.WorkerRegistry.html +210 -2
- package/dist/ifc-docs/interfaces/messages.Breadcrumb.html +373 -6
- package/dist/ifc-docs/interfaces/messages.EnvData.html +510 -11
- package/dist/ifc-docs/interfaces/messages.KeyData.html +540 -12
- package/dist/ifc-docs/interfaces/messages.ModalRequest.html +381 -6
- package/dist/ifc-docs/interfaces/messages.NavRequest.html +390 -9
- package/dist/ifc-docs/interfaces/messages.Notification.html +435 -9
- package/dist/ifc-docs/interfaces/messages.PageMetadata.html +438 -8
- package/dist/ifc-docs/interfaces/messages.PromptOnLeave.html +390 -9
- package/dist/ifc-docs/interfaces/messages.Publication.html +443 -11
- package/dist/ifc-docs/modules/client.html +742 -2
- package/dist/ifc-docs/modules/host.html +647 -1
- package/dist/ifc-docs/modules/messages.html +462 -1
- package/dist/ifc-docs/modules.html +359 -1
- package/dist/ifc-docs/types/client.EnvDataHandler.html +239 -1
- package/dist/ifc-docs/types/client.EventHandler.html +247 -2
- package/dist/index.html +1 -1
- package/package.json +3 -3
|
@@ -1,94 +1,598 @@
|
|
|
1
|
-
<!
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
<
|
|
5
|
-
|
|
6
|
-
<
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
<
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
<
|
|
13
|
-
<
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html class="default" lang="en" data-base="../">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta http-equiv="x-ua-compatible" content="IE=edge" />
|
|
6
|
+
<title>client-setup | iframe-coordinator - v6.5.1</title>
|
|
7
|
+
<meta name="description" content="Documentation for iframe-coordinator" />
|
|
8
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
9
|
+
<link rel="stylesheet" href="../assets/style.css" />
|
|
10
|
+
<link rel="stylesheet" href="../assets/highlight.css" />
|
|
11
|
+
<script defer src="../assets/main.js"></script>
|
|
12
|
+
<script async src="../assets/icons.js" id="tsd-icons-script"></script>
|
|
13
|
+
<script async src="../assets/search.js" id="tsd-search-script"></script>
|
|
14
|
+
<script async src="../assets/navigation.js" id="tsd-nav-script"></script>
|
|
15
|
+
</head>
|
|
16
|
+
<body>
|
|
17
|
+
<script>
|
|
18
|
+
document.documentElement.dataset.theme =
|
|
19
|
+
localStorage.getItem("tsd-theme") || "os";
|
|
20
|
+
document.body.style.display = "none";
|
|
21
|
+
setTimeout(
|
|
22
|
+
() =>
|
|
23
|
+
window.app
|
|
24
|
+
? app.showPage()
|
|
25
|
+
: document.body.style.removeProperty("display"),
|
|
26
|
+
500,
|
|
27
|
+
);
|
|
28
|
+
</script>
|
|
29
|
+
<header class="tsd-page-toolbar">
|
|
30
|
+
<div class="tsd-toolbar-contents container">
|
|
31
|
+
<a href="../index.html" class="title">iframe-coordinator - v6.5.1</a>
|
|
32
|
+
<div id="tsd-toolbar-links"></div>
|
|
33
|
+
<button id="tsd-search-trigger" class="tsd-widget" aria-label="Search">
|
|
34
|
+
<svg
|
|
35
|
+
width="16"
|
|
36
|
+
height="16"
|
|
37
|
+
viewBox="0 0 16 16"
|
|
38
|
+
fill="none"
|
|
39
|
+
aria-hidden="true"
|
|
40
|
+
>
|
|
41
|
+
<use href="../assets/icons.svg#icon-search"></use>
|
|
42
|
+
</svg>
|
|
43
|
+
</button>
|
|
44
|
+
<dialog id="tsd-search" aria-label="Search">
|
|
45
|
+
<input
|
|
46
|
+
role="combobox"
|
|
47
|
+
id="tsd-search-input"
|
|
48
|
+
aria-controls="tsd-search-results"
|
|
49
|
+
aria-autocomplete="list"
|
|
50
|
+
aria-expanded="true"
|
|
51
|
+
autocapitalize="off"
|
|
52
|
+
autocomplete="off"
|
|
53
|
+
placeholder="Search the docs"
|
|
54
|
+
maxlength="100"
|
|
55
|
+
/>
|
|
56
|
+
<ul role="listbox" id="tsd-search-results"></ul>
|
|
57
|
+
<div id="tsd-search-status" aria-live="polite" aria-atomic="true">
|
|
58
|
+
<div>Preparing search index...</div>
|
|
59
|
+
</div>
|
|
60
|
+
</dialog>
|
|
61
|
+
<a
|
|
62
|
+
href="#"
|
|
63
|
+
class="tsd-widget menu"
|
|
64
|
+
id="tsd-toolbar-menu-trigger"
|
|
65
|
+
data-toggle="menu"
|
|
66
|
+
aria-label="Menu"
|
|
67
|
+
><svg
|
|
68
|
+
width="16"
|
|
69
|
+
height="16"
|
|
70
|
+
viewBox="0 0 16 16"
|
|
71
|
+
fill="none"
|
|
72
|
+
aria-hidden="true"
|
|
73
|
+
>
|
|
74
|
+
<use href="../assets/icons.svg#icon-menu"></use></svg
|
|
75
|
+
></a>
|
|
76
|
+
</div>
|
|
77
|
+
</header>
|
|
78
|
+
<div class="container container-main">
|
|
79
|
+
<div class="col-content">
|
|
80
|
+
<div class="tsd-page-title">
|
|
81
|
+
<ul class="tsd-breadcrumb" aria-label="Breadcrumb">
|
|
82
|
+
<li><a href="" aria-current="page">client-setup</a></li>
|
|
83
|
+
</ul>
|
|
84
|
+
</div>
|
|
85
|
+
<div class="tsd-panel tsd-typography">
|
|
86
|
+
<h1 id="client-application-setup" class="tsd-anchor-link">
|
|
87
|
+
Client Application Setup<a
|
|
88
|
+
href="#client-application-setup"
|
|
89
|
+
aria-label="Permalink"
|
|
90
|
+
class="tsd-anchor-icon"
|
|
91
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
92
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
93
|
+
></a>
|
|
94
|
+
</h1>
|
|
95
|
+
<p>
|
|
96
|
+
To seamlessly integrate a client application with a host, you will
|
|
97
|
+
need to alter the client application's default behavior in a few
|
|
98
|
+
ways. Detailed instructions are below.
|
|
99
|
+
<em
|
|
100
|
+
>Navigation is the trickiest item to get correct. Be sure to read
|
|
101
|
+
that section carefully.</em
|
|
102
|
+
>
|
|
103
|
+
</p>
|
|
104
|
+
<h2 id="application-bootstrap" class="tsd-anchor-link">
|
|
105
|
+
Application Bootstrap<a
|
|
106
|
+
href="#application-bootstrap"
|
|
107
|
+
aria-label="Permalink"
|
|
108
|
+
class="tsd-anchor-icon"
|
|
109
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
110
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
111
|
+
></a>
|
|
112
|
+
</h2>
|
|
113
|
+
<p>
|
|
114
|
+
Early in the application bootstrap process, you will need to create
|
|
115
|
+
a
|
|
116
|
+
<a href="../classes/client.Client.html" class="tsd-kind-class">
|
|
117
|
+
client.Client</a
|
|
118
|
+
>
|
|
119
|
+
instance, add an event listener for environment data passed from the
|
|
120
|
+
host application, and start the client.
|
|
121
|
+
</p>
|
|
122
|
+
<p>
|
|
123
|
+
<a
|
|
124
|
+
href="../interfaces/messages.EnvData.html"
|
|
125
|
+
class="tsd-kind-interface"
|
|
126
|
+
>Environment data</a
|
|
127
|
+
>
|
|
128
|
+
is data set in the host application that is static over time, but
|
|
129
|
+
that clients will need to function, such as the user-selected
|
|
130
|
+
locale. It supports both pre-defined common/required options and
|
|
131
|
+
custom data.
|
|
132
|
+
</p>
|
|
133
|
+
<p>
|
|
134
|
+
Calling
|
|
135
|
+
<a
|
|
136
|
+
href="../classes/client.Client.html#start"
|
|
137
|
+
class="tsd-kind-method"
|
|
138
|
+
>
|
|
139
|
+
client.Client.start</a
|
|
140
|
+
>
|
|
141
|
+
on the client sets up messaging listeners, and sends a signal to the
|
|
142
|
+
host application to inform it that your application is ready to
|
|
143
|
+
start receiving messages.
|
|
144
|
+
</p>
|
|
145
|
+
<p>
|
|
146
|
+
The iframe-coordinator phase of a typical client bootstrap might
|
|
147
|
+
look like this:
|
|
148
|
+
</p>
|
|
149
|
+
<pre><code class="typescript"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-4">Client</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-3">"iframe-coordinator/client"</span><span class="hl-2">;</span><br/><br/><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">ifcClient</span><span class="hl-2"> = </span><span class="hl-6">new</span><span class="hl-2"> </span><span class="hl-5">Client</span><span class="hl-2">();</span><br/><br/><span class="hl-0">// envDataHandler can be used to store the data in a service module or</span><br/><span class="hl-0">// somewhere else useful for future reference</span><br/><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">addListener</span><span class="hl-2">(</span><span class="hl-3">"environmentalData"</span><span class="hl-2">, </span><span class="hl-4">envDataHandler</span><span class="hl-2">);</span><br/><br/><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">start</span><span class="hl-2">();</span>
|
|
14
150
|
</code><button type="button">Copy</button></pre>
|
|
15
151
|
|
|
16
|
-
<h2 id="navigation" class="tsd-anchor-link">
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
<
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
152
|
+
<h2 id="navigation" class="tsd-anchor-link">
|
|
153
|
+
Navigation<a
|
|
154
|
+
href="#navigation"
|
|
155
|
+
aria-label="Permalink"
|
|
156
|
+
class="tsd-anchor-icon"
|
|
157
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
158
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
159
|
+
></a>
|
|
160
|
+
</h2>
|
|
161
|
+
<p>
|
|
162
|
+
Creating a seamless navigation experience for users is the most
|
|
163
|
+
challenging part of iframe-embedded applications. We need to
|
|
164
|
+
preserve all of these experiences:
|
|
165
|
+
</p>
|
|
166
|
+
<ul>
|
|
167
|
+
<li>
|
|
168
|
+
Browser history navigation must work correctly, even if the iframe
|
|
169
|
+
is removed from the page or navigates to a blank page when
|
|
170
|
+
inactive
|
|
171
|
+
</li>
|
|
172
|
+
<li>
|
|
173
|
+
Requests to open a link rendered in a client application in a new
|
|
174
|
+
tab must open the whole application in the new tab, not just the
|
|
175
|
+
client application
|
|
176
|
+
</li>
|
|
177
|
+
<li>
|
|
178
|
+
Copying the link URL in a client application and sharing it with
|
|
179
|
+
others out of band should result in them seeing the whole
|
|
180
|
+
application, not just the embedded client
|
|
181
|
+
</li>
|
|
182
|
+
</ul>
|
|
183
|
+
<h3 id="preserving-browser-history" class="tsd-anchor-link">
|
|
184
|
+
Preserving Browser History<a
|
|
185
|
+
href="#preserving-browser-history"
|
|
186
|
+
aria-label="Permalink"
|
|
187
|
+
class="tsd-anchor-icon"
|
|
188
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
189
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
190
|
+
></a>
|
|
191
|
+
</h3>
|
|
192
|
+
<p>
|
|
193
|
+
To preserve browser history, the client application should never
|
|
194
|
+
navigate directly to a new page. Instead, it should always request
|
|
195
|
+
that the host application change its url. This is done with a
|
|
196
|
+
<a
|
|
197
|
+
href="../classes/client.Client.html#requestnavigation"
|
|
198
|
+
class="tsd-kind-method"
|
|
199
|
+
>
|
|
200
|
+
client.Client.requestNavigation</a
|
|
201
|
+
>
|
|
202
|
+
call or by using links with
|
|
203
|
+
<code>target="_top"</code> set.
|
|
204
|
+
</p>
|
|
205
|
+
<h3
|
|
206
|
+
id="ensuring-link-urls-reference-the-host-application"
|
|
207
|
+
class="tsd-anchor-link"
|
|
208
|
+
>
|
|
209
|
+
Ensuring Link URLs Reference the Host Application<a
|
|
210
|
+
href="#ensuring-link-urls-reference-the-host-application"
|
|
211
|
+
aria-label="Permalink"
|
|
212
|
+
class="tsd-anchor-icon"
|
|
213
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
214
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
215
|
+
></a>
|
|
216
|
+
</h3>
|
|
217
|
+
<p>
|
|
218
|
+
Links rendered by the client application should have the
|
|
219
|
+
<code>href</code> attribute set to the full host application URL
|
|
220
|
+
rather than a relative path within the client. To make this easier,
|
|
221
|
+
the client provides the <code>urlFromClientPath</code> method that
|
|
222
|
+
can translate client application routes to the corresponding host
|
|
223
|
+
application URL. The client application also provides the
|
|
224
|
+
<code>urlFromHostPath</code> method that can translate a host
|
|
225
|
+
application relative path to the full URL used in the host
|
|
226
|
+
application.
|
|
227
|
+
</p>
|
|
228
|
+
<h3
|
|
229
|
+
id="using-custom-elements-to-create-links"
|
|
230
|
+
class="tsd-anchor-link"
|
|
231
|
+
>
|
|
232
|
+
Using Custom Elements to Create Links<a
|
|
233
|
+
href="#using-custom-elements-to-create-links"
|
|
234
|
+
aria-label="Permalink"
|
|
235
|
+
class="tsd-anchor-icon"
|
|
236
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
237
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
238
|
+
></a>
|
|
239
|
+
</h3>
|
|
240
|
+
<p>
|
|
241
|
+
To further simplify the generation of these links, there are custom
|
|
242
|
+
elements that can be used to create links. These elements are
|
|
243
|
+
<code>ifc-client-link</code> and <code>ifc-host-link</code>. These
|
|
244
|
+
custom elements are registered and provided by the client. These
|
|
245
|
+
custom elements require a <code>path</code> attribute with the
|
|
246
|
+
relative path (either client or host) that will be used to create
|
|
247
|
+
the full URL. The <code>ifc-client-link</code> custom element uses
|
|
248
|
+
the <code>urlFromClientPath</code> method to translate a client
|
|
249
|
+
application route provided in the <code>path</code> attribute to a
|
|
250
|
+
full URL. The <code>ifc-host-link</code> custom element uses the
|
|
251
|
+
<code>urlFromHostPath</code> method to translate a host application
|
|
252
|
+
route provided in the <code>path</code> attribute to a full URL.
|
|
253
|
+
</p>
|
|
254
|
+
<h3 id="examples" class="tsd-anchor-link">
|
|
255
|
+
Examples<a
|
|
256
|
+
href="#examples"
|
|
257
|
+
aria-label="Permalink"
|
|
258
|
+
class="tsd-anchor-icon"
|
|
259
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
260
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
261
|
+
></a>
|
|
262
|
+
</h3>
|
|
263
|
+
<p>
|
|
264
|
+
Here are some basic examples of how you might generate links or
|
|
265
|
+
request navigation in your application. If you are using an
|
|
266
|
+
application framework such as Vue, Angular, etc, you may need to
|
|
267
|
+
wrap, extend, or avoid built-in navigation and link generation
|
|
268
|
+
utilities.
|
|
269
|
+
</p>
|
|
270
|
+
<p><strong>Programmatically Navigating</strong></p>
|
|
271
|
+
<pre><code class="typescript"><span class="hl-0">// Navigate to a new route in the client app: /foo/bar</span><br/><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">requestNavigation</span><span class="hl-2">({ </span><span class="hl-4">url:</span><span class="hl-2"> </span><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">urlFromClientPath</span><span class="hl-2">(</span><span class="hl-3">"/foo/bar"</span><span class="hl-2">) });</span><br/><br/><span class="hl-0">// Navigate to a host application route</span><br/><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">requestNavigation</span><span class="hl-2">({ </span><span class="hl-4">url:</span><span class="hl-2"> </span><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">urlFromHostPath</span><span class="hl-2">(</span><span class="hl-3">"/path"</span><span class="hl-2">) });</span><br/><br/><span class="hl-0">// Navigate to a 3rd party url</span><br/><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">requestNavigation</span><span class="hl-2">({ </span><span class="hl-4">url:</span><span class="hl-2"> </span><span class="hl-3">"https://external-site.com/external/path"</span><span class="hl-2"> });</span>
|
|
40
272
|
</code><button type="button">Copy</button></pre>
|
|
41
273
|
|
|
42
|
-
<p><strong>Generating Links</strong></p>
|
|
43
|
-
<pre><code class="typescript"><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">internalLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="</span><span class="hl-6">${</span><span class="hl-4">ifcClient</span><span class="hl-15">.</span><span class="hl-5">urlFromClientPath</span><span class="hl-15">(</span><br/><span class="hl-15"> </span><span class="hl-3">"foo/bar"</span><span class="hl-15">,</span><br/><span class="hl-15">)</span><span class="hl-6">}</span><span class="hl-3">" target="_top">Internal Link</a>`</span><span class="hl-2">;</span><br/><br/><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">hostLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="</span><span class="hl-6">${</span><span class="hl-4">ifcClient</span><span class="hl-15">.</span><span class="hl-5">urlFromHostPath</span><span class="hl-15">(</span><br/><span class="hl-15"> </span><span class="hl-3">"/path"</span><span class="hl-15">,</span><br/><span class="hl-15">)</span><span class="hl-6">}</span><span class="hl-3">" target="_top">Internal Link</a>`</span><span class="hl-2">;</span><br/><br/><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">externalLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="https://external-site.com/external/path" target="_top">Internal Link</a>`</span><span class="hl-2">;</span>
|
|
274
|
+
<p><strong>Generating Links</strong></p>
|
|
275
|
+
<pre><code class="typescript"><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">internalLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="</span><span class="hl-6">${</span><span class="hl-4">ifcClient</span><span class="hl-15">.</span><span class="hl-5">urlFromClientPath</span><span class="hl-15">(</span><br/><span class="hl-15"> </span><span class="hl-3">"foo/bar"</span><span class="hl-15">,</span><br/><span class="hl-15">)</span><span class="hl-6">}</span><span class="hl-3">" target="_top">Internal Link</a>`</span><span class="hl-2">;</span><br/><br/><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">hostLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="</span><span class="hl-6">${</span><span class="hl-4">ifcClient</span><span class="hl-15">.</span><span class="hl-5">urlFromHostPath</span><span class="hl-15">(</span><br/><span class="hl-15"> </span><span class="hl-3">"/path"</span><span class="hl-15">,</span><br/><span class="hl-15">)</span><span class="hl-6">}</span><span class="hl-3">" target="_top">Internal Link</a>`</span><span class="hl-2">;</span><br/><br/><span class="hl-6">let</span><span class="hl-2"> </span><span class="hl-4">externalLink</span><span class="hl-2"> = </span><span class="hl-3">`<a href="https://external-site.com/external/path" target="_top">Internal Link</a>`</span><span class="hl-2">;</span>
|
|
44
276
|
</code><button type="button">Copy</button></pre>
|
|
45
277
|
|
|
46
|
-
<p><strong>Generating Links Using Custom Elements</strong></p>
|
|
47
|
-
<pre><code class="html"><span class="hl-0"><!-- Creates a link to a new route in the client app: /foo/bar --></span><br/><span class="hl-7"><</span><span class="hl-8">ifc-client-link</span><span class="hl-2"> </span><span class="hl-9">path</span><span class="hl-2">=</span><span class="hl-10">"/foo/bar"</span><span class="hl-7">></span><span class="hl-2">Internal Link</span><span class="hl-7"></</span><span class="hl-8">ifc-client-link</span><span class="hl-7">></span><br/><br/><span class="hl-0"><!-- Creates a link to a host application route: /path --></span><br/><span class="hl-7"><</span><span class="hl-8">ifc-host-link</span><span class="hl-2"> </span><span class="hl-9">path</span><span class="hl-2">=</span><span class="hl-10">"/path"</span><span class="hl-7">></span><span class="hl-2">Internal Link</span><span class="hl-7"></</span><span class="hl-8">ifc-host-link</span><span class="hl-7">></span>
|
|
278
|
+
<p><strong>Generating Links Using Custom Elements</strong></p>
|
|
279
|
+
<pre><code class="html"><span class="hl-0"><!-- Creates a link to a new route in the client app: /foo/bar --></span><br/><span class="hl-7"><</span><span class="hl-8">ifc-client-link</span><span class="hl-2"> </span><span class="hl-9">path</span><span class="hl-2">=</span><span class="hl-10">"/foo/bar"</span><span class="hl-7">></span><span class="hl-2">Internal Link</span><span class="hl-7"></</span><span class="hl-8">ifc-client-link</span><span class="hl-7">></span><br/><br/><span class="hl-0"><!-- Creates a link to a host application route: /path --></span><br/><span class="hl-7"><</span><span class="hl-8">ifc-host-link</span><span class="hl-2"> </span><span class="hl-9">path</span><span class="hl-2">=</span><span class="hl-10">"/path"</span><span class="hl-7">></span><span class="hl-2">Internal Link</span><span class="hl-7"></</span><span class="hl-8">ifc-host-link</span><span class="hl-7">></span>
|
|
48
280
|
</code><button type="button">Copy</button></pre>
|
|
49
281
|
|
|
50
|
-
<h2 id="providing-page-metadata" class="tsd-anchor-link">
|
|
51
|
-
|
|
52
|
-
|
|
282
|
+
<h2 id="providing-page-metadata" class="tsd-anchor-link">
|
|
283
|
+
Providing Page Metadata<a
|
|
284
|
+
href="#providing-page-metadata"
|
|
285
|
+
aria-label="Permalink"
|
|
286
|
+
class="tsd-anchor-icon"
|
|
287
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
288
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
289
|
+
></a>
|
|
290
|
+
</h2>
|
|
291
|
+
<p>
|
|
292
|
+
When your application loads a page, you may want to provide metadata
|
|
293
|
+
to the host application to improve the user experience. This is done
|
|
294
|
+
with a
|
|
295
|
+
<a
|
|
296
|
+
href="../classes/client.Client.html#sendpagemetadata"
|
|
297
|
+
class="tsd-kind-method"
|
|
298
|
+
>
|
|
299
|
+
client.Client.sendPageMetadata</a
|
|
300
|
+
>
|
|
301
|
+
call.
|
|
302
|
+
</p>
|
|
303
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">sendPageMetadata</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-0">// The localized title for your page</span><br/><span class="hl-2"> </span><span class="hl-4">title:</span><span class="hl-2"> </span><span class="hl-3">"My Cool Feature"</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-0">// An array of breadcrumbs to be displayed</span><br/><span class="hl-2"> </span><span class="hl-4">breadcrumbs:</span><span class="hl-2"> [{ </span><span class="hl-4">text:</span><span class="hl-2"> </span><span class="hl-3">"Home"</span><span class="hl-2">, </span><span class="hl-4">href:</span><span class="hl-2"> </span><span class="hl-3">"/home"</span><span class="hl-2"> }],</span><br/><span class="hl-2"> </span><span class="hl-0">// Optionally, any additional data that your host expects</span><br/><span class="hl-2"> </span><span class="hl-4">custom:</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-4">foo:</span><span class="hl-2"> </span><span class="hl-3">"bar"</span><span class="hl-2">,</span><br/><span class="hl-2"> },</span><br/><span class="hl-2">});</span>
|
|
53
304
|
</code><button type="button">Copy</button></pre>
|
|
54
305
|
|
|
55
|
-
<p>
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
<
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
<
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
<
|
|
306
|
+
<p>
|
|
307
|
+
The frame-router element will emit a custom event of 'pageMetadata'
|
|
308
|
+
with the PageMetaData object in the detail property.
|
|
309
|
+
</p>
|
|
310
|
+
<h2 id="requesting-host-actions" class="tsd-anchor-link">
|
|
311
|
+
Requesting Host Actions<a
|
|
312
|
+
href="#requesting-host-actions"
|
|
313
|
+
aria-label="Permalink"
|
|
314
|
+
class="tsd-anchor-icon"
|
|
315
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
316
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
317
|
+
></a>
|
|
318
|
+
</h2>
|
|
319
|
+
<p>
|
|
320
|
+
There are common requests a client application will want to make of
|
|
321
|
+
a host application and we strive to provide nice default APIs for
|
|
322
|
+
these.
|
|
323
|
+
</p>
|
|
324
|
+
<p>Currently there are four implemented:</p>
|
|
325
|
+
<p>
|
|
326
|
+
<a
|
|
327
|
+
href="../classes/client.Client.html#requestnotification"
|
|
328
|
+
class="tsd-kind-method"
|
|
329
|
+
>
|
|
330
|
+
client.Client.requestNotification</a
|
|
331
|
+
>, which asks the host app to send a notification message to the
|
|
332
|
+
user.
|
|
333
|
+
</p>
|
|
334
|
+
<p>
|
|
335
|
+
<a
|
|
336
|
+
href="../classes/client.Client.html#requestmodal"
|
|
337
|
+
class="tsd-kind-method"
|
|
338
|
+
>
|
|
339
|
+
client.Client.requestModal</a
|
|
340
|
+
>, which asks the host app to launch a modal identified by a given
|
|
341
|
+
ID, also accepts initial setup data specific to that modal.
|
|
342
|
+
</p>
|
|
343
|
+
<p>
|
|
344
|
+
<a
|
|
345
|
+
href="../classes/client.Client.html#requestpromptonleave"
|
|
346
|
+
class="tsd-kind-method"
|
|
347
|
+
>
|
|
348
|
+
client.Client.requestPromptOnLeave</a
|
|
349
|
+
>, which asks the host app to display a prompt on leave dialog to
|
|
350
|
+
the user before navigating.
|
|
351
|
+
</p>
|
|
352
|
+
<p>
|
|
353
|
+
<a
|
|
354
|
+
href="../classes/client.Client.html#clearpromptonleave"
|
|
355
|
+
class="tsd-kind-method"
|
|
356
|
+
>
|
|
357
|
+
client.Client.clearPromptOnLeave</a
|
|
358
|
+
>, which asks the host app to clear the prompt on leave dialog
|
|
359
|
+
before navigating.
|
|
360
|
+
</p>
|
|
361
|
+
<p>A client application may request a modal on the host like so:</p>
|
|
362
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">requestModal</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-4">modalType:</span><span class="hl-2"> </span><span class="hl-3">'idOfTheModalToDisplay'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-4">modalData:</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-4">id:</span><span class="hl-2"> </span><span class="hl-3">'1234567890'</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-4">userList :</span><span class="hl-2"> [{</span><span class="hl-4">id:</span><span class="hl-2"> </span><span class="hl-3">'2345678901'</span><span class="hl-2">, </span><span class="hl-4">name:</span><span class="hl-2"> </span><span class="hl-3">'User1'</span><span class="hl-2">}]</span><br/><span class="hl-2">});</span>
|
|
69
363
|
</code><button type="button">Copy</button></pre>
|
|
70
364
|
|
|
71
|
-
<p>
|
|
72
|
-
|
|
73
|
-
|
|
365
|
+
<p>
|
|
366
|
+
The frame-router element will emit a custom event of 'modalRequest'
|
|
367
|
+
with the ModalRequest object in the detail property.
|
|
368
|
+
</p>
|
|
369
|
+
<p>
|
|
370
|
+
A client application may request a prompt on leave dialog on the
|
|
371
|
+
host like so:
|
|
372
|
+
</p>
|
|
373
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">requestPromptOnLeave</span><span class="hl-2">();</span>
|
|
74
374
|
</code><button type="button">Copy</button></pre>
|
|
75
375
|
|
|
76
|
-
<p>
|
|
77
|
-
|
|
78
|
-
|
|
376
|
+
<p>
|
|
377
|
+
The frame-router element will emit a custom event of 'promptOnLeave'
|
|
378
|
+
with the PromptOnLeave object in the detail property.
|
|
379
|
+
</p>
|
|
380
|
+
<p>
|
|
381
|
+
A client application may request to clear the prompt on leave dialog
|
|
382
|
+
on the host like so:
|
|
383
|
+
</p>
|
|
384
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">clearPromptOnLeave</span><span class="hl-2">();</span>
|
|
79
385
|
</code><button type="button">Copy</button></pre>
|
|
80
386
|
|
|
81
|
-
<p>
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
387
|
+
<p>
|
|
388
|
+
The frame-router element will emit a custom event 'promptOnLeave'
|
|
389
|
+
with the PromptOnLeave object in the detail property.
|
|
390
|
+
</p>
|
|
391
|
+
<h2 id="custom-clienthost-messaging" class="tsd-anchor-link">
|
|
392
|
+
Custom Client/Host Messaging<a
|
|
393
|
+
href="#custom-clienthost-messaging"
|
|
394
|
+
aria-label="Permalink"
|
|
395
|
+
class="tsd-anchor-icon"
|
|
396
|
+
><svg viewBox="0 0 24 24" aria-hidden="true">
|
|
397
|
+
<use href="../assets/icons.svg#icon-anchor"></use></svg
|
|
398
|
+
></a>
|
|
399
|
+
</h2>
|
|
400
|
+
<p>
|
|
401
|
+
Client and Host applications may also need to communicate about
|
|
402
|
+
topics specific to their use case. iframe-coordinator provides a
|
|
403
|
+
lightweight pub-sub wrapper around the
|
|
404
|
+
<a
|
|
405
|
+
href="https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage"
|
|
406
|
+
>postmessage api</a
|
|
407
|
+
>
|
|
408
|
+
to meet that need with a consistent message interface.
|
|
409
|
+
</p>
|
|
410
|
+
<p>
|
|
411
|
+
You can publish messages to the host application via the
|
|
412
|
+
<a
|
|
413
|
+
href="../classes/client.Client.html#publish"
|
|
414
|
+
class="tsd-kind-method"
|
|
415
|
+
>
|
|
416
|
+
client.Client.publish</a
|
|
417
|
+
>
|
|
418
|
+
method.
|
|
419
|
+
</p>
|
|
420
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-5">publish</span><span class="hl-2">({</span><br/><span class="hl-2"> </span><span class="hl-4">topic:</span><span class="hl-2"> </span><span class="hl-3">"please.do.the.thing"</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-4">payload:</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-4">foo:</span><span class="hl-2"> </span><span class="hl-3">"bar"</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-4">baz:</span><span class="hl-2"> </span><span class="hl-3">"qux"</span><span class="hl-2">,</span><br/><span class="hl-2"> },</span><br/><span class="hl-2">});</span>
|
|
88
421
|
</code><button type="button">Copy</button></pre>
|
|
89
422
|
|
|
90
|
-
<p>
|
|
91
|
-
|
|
423
|
+
<p>
|
|
424
|
+
You can listen for messages from the host on a topic via the
|
|
425
|
+
<a
|
|
426
|
+
href="../interfaces/client.EventEmitter.html"
|
|
427
|
+
class="tsd-kind-interface"
|
|
428
|
+
>messaging API</a
|
|
429
|
+
>
|
|
430
|
+
</p>
|
|
431
|
+
<pre><code class="typescript"><span class="hl-4">ifcClient</span><span class="hl-2">.</span><span class="hl-4">messaging</span><span class="hl-2">.</span><span class="hl-5">addEventListener</span><span class="hl-2">(</span><span class="hl-3">"topic.from.host"</span><span class="hl-2">, </span><span class="hl-4">payloadHandler</span><span class="hl-2">);</span>
|
|
92
432
|
</code><button type="button">Copy</button></pre>
|
|
93
|
-
|
|
94
|
-
</div
|
|
433
|
+
</div>
|
|
434
|
+
</div>
|
|
435
|
+
<div class="col-sidebar">
|
|
436
|
+
<div class="page-menu">
|
|
437
|
+
<div class="tsd-navigation settings">
|
|
438
|
+
<details class="tsd-accordion">
|
|
439
|
+
<summary class="tsd-accordion-summary">
|
|
440
|
+
<svg
|
|
441
|
+
width="20"
|
|
442
|
+
height="20"
|
|
443
|
+
viewBox="0 0 24 24"
|
|
444
|
+
fill="none"
|
|
445
|
+
aria-hidden="true"
|
|
446
|
+
>
|
|
447
|
+
<use href="../assets/icons.svg#icon-chevronDown"></use>
|
|
448
|
+
</svg>
|
|
449
|
+
<h3>Settings</h3>
|
|
450
|
+
</summary>
|
|
451
|
+
<div class="tsd-accordion-details">
|
|
452
|
+
<div class="tsd-filter-visibility">
|
|
453
|
+
<span class="settings-label">Member Visibility</span>
|
|
454
|
+
<ul id="tsd-filter-options">
|
|
455
|
+
<li class="tsd-filter-item">
|
|
456
|
+
<label class="tsd-filter-input"
|
|
457
|
+
><input
|
|
458
|
+
type="checkbox"
|
|
459
|
+
id="tsd-filter-inherited"
|
|
460
|
+
name="inherited"
|
|
461
|
+
checked
|
|
462
|
+
/><svg
|
|
463
|
+
width="32"
|
|
464
|
+
height="32"
|
|
465
|
+
viewBox="0 0 32 32"
|
|
466
|
+
aria-hidden="true"
|
|
467
|
+
>
|
|
468
|
+
<rect
|
|
469
|
+
class="tsd-checkbox-background"
|
|
470
|
+
width="30"
|
|
471
|
+
height="30"
|
|
472
|
+
x="1"
|
|
473
|
+
y="1"
|
|
474
|
+
rx="6"
|
|
475
|
+
fill="none"
|
|
476
|
+
></rect>
|
|
477
|
+
<path
|
|
478
|
+
class="tsd-checkbox-checkmark"
|
|
479
|
+
d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25"
|
|
480
|
+
stroke="none"
|
|
481
|
+
stroke-width="3.5"
|
|
482
|
+
stroke-linejoin="round"
|
|
483
|
+
fill="none"
|
|
484
|
+
></path></svg
|
|
485
|
+
><span>Inherited</span></label
|
|
486
|
+
>
|
|
487
|
+
</li>
|
|
488
|
+
</ul>
|
|
489
|
+
</div>
|
|
490
|
+
<div class="tsd-theme-toggle">
|
|
491
|
+
<label class="settings-label" for="tsd-theme">Theme</label
|
|
492
|
+
><select id="tsd-theme">
|
|
493
|
+
<option value="os">OS</option>
|
|
494
|
+
<option value="light">Light</option>
|
|
495
|
+
<option value="dark">Dark</option>
|
|
496
|
+
</select>
|
|
497
|
+
</div>
|
|
498
|
+
</div>
|
|
499
|
+
</details>
|
|
500
|
+
</div>
|
|
501
|
+
<details open class="tsd-accordion tsd-page-navigation">
|
|
502
|
+
<summary class="tsd-accordion-summary">
|
|
503
|
+
<svg
|
|
504
|
+
width="20"
|
|
505
|
+
height="20"
|
|
506
|
+
viewBox="0 0 24 24"
|
|
507
|
+
fill="none"
|
|
508
|
+
aria-hidden="true"
|
|
509
|
+
>
|
|
510
|
+
<use href="../assets/icons.svg#icon-chevronDown"></use>
|
|
511
|
+
</svg>
|
|
512
|
+
<h3>On This Page</h3>
|
|
513
|
+
</summary>
|
|
514
|
+
<div class="tsd-accordion-details">
|
|
515
|
+
<a href="#client-application-setup"
|
|
516
|
+
><span>Client <wbr />Application <wbr />Setup</span></a
|
|
517
|
+
>
|
|
518
|
+
<ul>
|
|
519
|
+
<li>
|
|
520
|
+
<a href="#application-bootstrap"
|
|
521
|
+
><span>Application <wbr />Bootstrap</span></a
|
|
522
|
+
>
|
|
523
|
+
</li>
|
|
524
|
+
<li>
|
|
525
|
+
<a href="#navigation"><span>Navigation</span></a>
|
|
526
|
+
</li>
|
|
527
|
+
<li>
|
|
528
|
+
<ul>
|
|
529
|
+
<li>
|
|
530
|
+
<a href="#preserving-browser-history"
|
|
531
|
+
><span
|
|
532
|
+
>Preserving <wbr />Browser <wbr />History</span
|
|
533
|
+
></a
|
|
534
|
+
>
|
|
535
|
+
</li>
|
|
536
|
+
<li>
|
|
537
|
+
<a
|
|
538
|
+
href="#ensuring-link-urls-reference-the-host-application"
|
|
539
|
+
><span
|
|
540
|
+
>Ensuring <wbr />Link <wbr />UR<wbr />Ls
|
|
541
|
+
<wbr />Reference the <wbr />Host
|
|
542
|
+
<wbr />Application</span
|
|
543
|
+
></a
|
|
544
|
+
>
|
|
545
|
+
</li>
|
|
546
|
+
<li>
|
|
547
|
+
<a href="#using-custom-elements-to-create-links"
|
|
548
|
+
><span
|
|
549
|
+
>Using <wbr />Custom <wbr />Elements to <wbr />Create
|
|
550
|
+
<wbr />Links</span
|
|
551
|
+
></a
|
|
552
|
+
>
|
|
553
|
+
</li>
|
|
554
|
+
<li>
|
|
555
|
+
<a href="#examples"><span>Examples</span></a>
|
|
556
|
+
</li>
|
|
557
|
+
</ul>
|
|
558
|
+
</li>
|
|
559
|
+
<li>
|
|
560
|
+
<a href="#providing-page-metadata"
|
|
561
|
+
><span>Providing <wbr />Page <wbr />Metadata</span></a
|
|
562
|
+
>
|
|
563
|
+
</li>
|
|
564
|
+
<li>
|
|
565
|
+
<a href="#requesting-host-actions"
|
|
566
|
+
><span>Requesting <wbr />Host <wbr />Actions</span></a
|
|
567
|
+
>
|
|
568
|
+
</li>
|
|
569
|
+
<li>
|
|
570
|
+
<a href="#custom-clienthost-messaging"
|
|
571
|
+
><span
|
|
572
|
+
>Custom <wbr />Client/<wbr />Host <wbr />Messaging</span
|
|
573
|
+
></a
|
|
574
|
+
>
|
|
575
|
+
</li>
|
|
576
|
+
</ul>
|
|
577
|
+
</div>
|
|
578
|
+
</details>
|
|
579
|
+
</div>
|
|
580
|
+
<div class="site-menu">
|
|
581
|
+
<nav class="tsd-navigation">
|
|
582
|
+
<a href="../modules.html">iframe-coordinator - v6.5.1</a>
|
|
583
|
+
<ul class="tsd-small-nested-navigation" id="tsd-nav-container">
|
|
584
|
+
<li>Loading...</li>
|
|
585
|
+
</ul>
|
|
586
|
+
</nav>
|
|
587
|
+
</div>
|
|
588
|
+
</div>
|
|
589
|
+
</div>
|
|
590
|
+
<footer>
|
|
591
|
+
<p class="tsd-generator">
|
|
592
|
+
Generated using
|
|
593
|
+
<a href="https://typedoc.org/" target="_blank">TypeDoc</a>
|
|
594
|
+
</p>
|
|
595
|
+
</footer>
|
|
596
|
+
<div class="overlay"></div>
|
|
597
|
+
</body>
|
|
598
|
+
</html>
|