@radar/widget-embed v0.1.1

@radar/widget-embed

Embed a widget inside a responsive iframe and enable cross-domain communication

Installation

npm

npm install @radar/widget-embed

yarn

yarn add @radar/widget-embed

Basic Usage

At a minimum, the embedding website must call configureWidget with the widget url. This will load the widget in modal mode.

import { configureWidget } from '@radar/widget-embed';

configureWidget({
  url: 'https://my-cool-widget.com',
});

Configuration Options

The above function accepts several optional properties that can be used to control how the widget looks, where and how it is embedded, and how you communicate with it.

/**
 * Configuration values used to populate, augment and communicate with the widget
 */
export type WidgetConfig<C extends {} = {}> = C & {
  /** The URL of the application to embed */
  url: string;
  /** Values used to style the user interface of the wrapper. See defaults in `UserInterface` */
  ui?: UserInterface;
  /** Control how the widget is embedded into the webpage Default: modal */
  embedMode?: EmbedMode;
  /** The id of the container that the widget will be attached to if using direct-embed mode. Default: body */
  containerId?: string;
  /** Additional methods that can be called by the widget */
  methods?: { [key: string]: Function };
};

/**
 * Whether the widget should appear as a modal or directly embedded in the webpage
 */
export enum EmbedMode {
  DIRECT_EMBED = 'direct-embed',
  MODAL = 'modal',
}

/**
 * Values used to style the user interface of the wrapper
 */
export interface UserInterface {
  /** The color of the background visible to the user while the widget is loading. Default #ffffff */
  backgroundColor?: string;
  /** The image that wil be displayed to the user while the widget is loading. Default: None */
  loadingImage?: string;
  /** The widget iframe dimensions prior to resizing. Default: 400px x 500px */
  dimensions?: Dimensions;
}

/**
 * The widget iframe dimensions prior to resizing
 */
export interface Dimensions {
  width: string;
  height: string;
}

Embed Modes

Modal

This mode is likely preferable because it does not disrupt the existing UI in any way. The below methods can be used to control the visibility of the widget.

Extended Window API

/**
 * Open the widget
 */
widget.open()

/**
 * Close the widget
 */
widget.close() 

/**
 * Toggle the widget
 */
widget.toggle()

Example

<button onclick="widget.open()">Open Widget</button>

Direct Embed

This mode will directly embed the widget into the consuming website. By default, the widget will be attached to the body of the website. If a containerId is passed in the widget options then the widget will be rendered inside that container.