@moesol/widget-launch v2.6.0-SNAPSHOT
widget-launch
Background
The widget-launch
library is an npm library providing a simple wrapper around and replacement for the widget launching functions of OWF. This library is intended to ease the transition away from OWF by providing a replacement for direct calls to OWF that will function inside or outside OWF. It is not intended as a complete replacement for OWF; OWF capabilities unrelated to widget launching are outside the scope of this library.
Usage
Launching Widget/Page
const widgetLauncher = new WidgetLauncher();
widgetLauncher.launch({
universalName: 'openedWidget',
url: 'fakeurl',
guid: 'fake',
title: 'fake',
data: '{}',
launchOnlyIfClosed: false,
}, () => {})
Launched Widget/Page
const widgetLauncher = new WidgetLauncher();
const launchData = await widgetLauncher.getLaunchData();
widgetLauncher.closeWidget();
Methods
The library exposes a single class, WidgetLauncher
. WidgetLauncher
contains the following methods:
isInOwf
: Reports whether the current page is running inOWF
, by checking for the existence ofwindow.OWF
and checkingOWF.Util.isRunningInOWF
. This is used internally to detectOWF
, but also made available to clients of this library.launch
: Launches a widget according to theLaunchOptions
passed. InOWF
, this is a thin wrapper aroundOWF.Launcher.launch
with the same signature. OutsideOWF
, this call may use theozp-iwc
library orbrowser-only
implementation along with callingwindow.open
.Note that outside OWF you must pass the
universalName
and theurl
of the widget inside theLaunchOptions
in order to launch the widget.Note:
ozp-iwc
is the same library that may be used by@moesol/inter-widget-communication
. However,ozp-iwc
is deprecated andBroadcastChannel
(viaprovider: 'broadcast'
) is the new preferred implementation in@moesol/inter-widget-communication
getWidget
: Gets a widget according to the GetWidgetOptions passed. In OWF, this is a thin wrapper aroundOWF.Preferences.getWidget
with the same signature. Outside OWF, this function immediately passes through to theonSuccess
callback - this is here for compatibility withOWF
where you would typically callgetWidget
withlaunch
as theonSuccess
callback.getLaunchData
: Gets the launch data for the widget. In OWF, this is a thin wrapper aroundOWF.Launcher.getLaunchData
with the same signature. Outside OWF, this uses theozp-iwc
library (the same library used by@moesol/inter-widget-communication
).Note that unlike
OWF.Launcher.getLaunchData
, this is an asynchronous function becauseozp-iwc
'sget
is an asynchronous operation.closeWidget
: Closes the current widget. In OWF, this is a thin wrapper aroundOzone.state.WidgetState.getInstance().closeWidget
with the same signature. Outside OWF, this simply callswindow.close
.
Limitations with Using ozp-iwc
(deprecated)
Please note the following requirements and limitations of the library when used outside OWF (Future contributors can address these as needed):
In this mode, IWC is used to check whether there are running instances of the widget before opening, for use with the
launchOnlyIfClosed
option.Usage outside of OWF currently requires the
ozp-iwc
library. This library is not available as a module and so must be included in a<script>
tag on any page wanting to use theWidgetLauncher
outside OWF.If intending to use outside of OWF, the
WidgetLauncher
should be initialized with an instance of theozp-iwc
client passed to it - this can be obtained by callingnew window.ozpIwc.Client({ peerUrl: '...' })
. The first pass involved instantiating the client inside theWidgetLauncher
constructor, but this resulted in a new bus iframe being created every time aWidgetLauncher
was created on the same page.Outside OWF, the
window.name
of opened widgets is used to store the universal name (for checking if open) and a generated id (to get the launch data). If this property is overwritten the widget will no longer be recognized as open and will not be able to retrieve launch data.For a page to be recognized as open for the purposes of the
launch
function, it must initialize aWidgetLauncher
at least once when it loads.Pages navigated to directly by a user will not be able to use
getLaunchData
orcloseWidget
-getLaunchData
will not have any launch data set and thewindow.close
method used bycloseWidget
cannot close pages that were not opened by javascript. Such pages can use the other functions of theWidgetLauncher
as normal.
Limitations when Using browser-only
If neither OWF
or ozp-iwc
are available, this library falls back to using the Browser's window.open
API.
For this mode call
const widgetLauncher = new WidgetLauncher();
with no additional parametersAs with
ozp-iwc
, thewindow.name
of opened widgets is used to store information (including the launch data) If this property is overwritten the widget will no longer be recognized as open and will not be able to retrieve launch data.The option
launchOnlyIfClosed
behaves differently than in OWF orozp-iwc
. Pages launched from different browser sessions that contain the sameuniversalName
will not be detected asopen
. Thus, another window will open in this case.Note: however, if the same session uses
launchOnlyIfClosed
then the already open window is used unless, the launch data is differentPages launched with different launch data will always open a new window.
The function
getWidget
behaves differently as described in MethodsThe browser may limit the size of the
window.name
property, so passing large JSON (> 4K bytes) data should be avoided.In this
browser-only
modeoptions.features
is passed as the last parameter towindow.open
. This allowspopup
or other features to be specified.options.features
is ignored inOWF
or when usingozp-iwc
.
1 year ago