Overlay

• Developer

Learn how to use an overlay window control that widgets can inject their UI into.

Related documentation:

• How Widgets works

Overview

The Overlay plugin provides an overlay window control that widgets can inject their UI into, accepting the HTML UI, placing it inside an overlay control, and displaying the UI onscreen in a uniform overlay window fashion. This prevents individual widgets from managing the overlay themselves. It also means that each widget's UI can be moved between different container types.

Overlay provides these benefits:

• Shows the UI in the center of the window.
• Open and close transition animations.
• No overlapping overlays. Only one at a time. Automatically managed by the Overlay plugin.
• Auto-recenter as the browser window size is changed.
• Automatic application of mobile styles when running in mobile mode.

Usage

Overlay is easy to use; you simply open and close it. When you call Overlay.open, you pass in the HTML content you want to show. If you call Overlay.open again while an overlay is already open, it will automatically close the previous overlay before showing yours (unless the previous overlay has reserved the overlay to prevent new overlays).

Important

By default, the overlay has no visible styles or content. You must pass in the HTML you want to show inside the Overlay area. Typically you should create an overlay-type container using Common.Generate.Container, put your content inside that, then send the whole thing into Overlay.open.

Customization

Overlay does not have customization options.

Mobile support

Overlay automatically applies mobile CSS styles to its outer container to affect the content within the overlay view. It is up to the content inside the overlay view to dynamically change when the Genesys Widgets .cx-mobile CSS classname is applied to an outer container.

Configuration

Overlay does not have configuration options.

Localization

Overlay does not have localization options.

API commands

Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

Important

The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see Genesys Widgets Extensions for more information about extending Genesys Widgets.

var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('Overlay.close');

open

Opens the provided HTML in an Overlay View. When successful, it returns back the HTML and a custom close event for you to subscribe to. This alerts you when your overlay instance has been closed. You can also make your overlay immutable so that new overlay instances don't close yours. Only your widget can close its overlay when immutable is set to true.

Example

oMyPlugin.command('Overlay.open', {

	html: '<div>Template</div>',
	immutable: false,
	group: false

}).done(function(e){

	// Overlay opens successfully

}).fail(function(e){

	// Overlay failed to open
});

Options

Option	Type	Description
html	string	HTML string template for overlay window.
immutable	boolean	When set to true, overlay cannot be closed by other plugins.
group	string	The name of the overlay window group you want to add a new overlay view into.

Resolutions

Status	When	Returns
resolved	Overlay is successfully opened.	{html: <template>, events: <Object>, group: <String>}
rejected	No html template is passed.	No HTML content was provided. Overlay has ignored your command.
rejected	Overlay is already opened.	Overlay view is currently reserved.

close

Closes the Overlay UI. Publishes the appropriate custom close event for current overlay being closed.

Example

oMyPlugin.command('Overlay.close').done(function(e){

	// Overlay closed successfully

}).fail(function(e){

	// Overlay failed to close
});

Resolutions

Status	When	Returns
resolved	Overlay is successfully closed.	n/a
rejected	Overlay is already closed.	Overlay view is already closed.
rejected	Overlay view is immutable.	Overlay view is currently reserved.

API events

Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

Important

The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see Genesys Widgets Extensions for more information about extending Genesys Widgets.

var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('Overlay.ready', function(e){});

Name	Description	Data
ready	The Overlay plugin is initialized and ready to accept commands	n/a