WID/Current/SDK/SideBar-combined

• Developer

Learn about the Sidebar widget, which customers use to launch other widgets with a single click.

Related documentation:

• How Widgets works

Overview

Use the Sidebar to launch other widgets with a single click. By default, Sidebar is displayed on the right side of the screen, and you can configure any launchable widgets onto Sidebar, including your custom extension widgets. The Sidebar UI expands when you hover your cursor over it, and contracts when you move the cursor away. Other features include configurable positioning and mobile support. You can also add new configurations on the fly, which automatically re-renders the sidebar.

Usage

Use the following methods to launch SideBar manually:

• Call the SideBar.open command
• Configure Sidebar to show and launch custom widgets.

Dependency

You must configure at least one customer-facing UI widget in order to use the Sidebar Widget.

Customization

You can customize and localize all of the text shown in the Sidebar Widget by adding entries to your configuration and localization options.

Sidebar supports themes. You can create and register your own themes for Genesys Widgets.

Namespace

The Sidebar plugin has the following namespaces tied up with each of the following types:

Type	Namespace
Configuration	sidebar
i18n—Localization	sidebar
CXBus—API commands & API events	SideBar
CSS	.cx-sidebar

Mobile support

Sidebar supports both desktop and mobile devices. In mobile mode, the sidebar launcher button is displayed to the bottom of the screen. When triggered, it expands to the full screen of mobile and shows all channels configured with scrollbar when necessary. Like all Genesys Widgets, there are two main modes: Desktop & Mobile. Desktop is employed for monitors, laptops, and tablets. Mobile is employed for smartphones. When a smartphone is detected, Sidebar switches to special full-screen templates that are optimized for both portrait and landscape orientations.

Switching between desktop and mobile mode is done automatically by default. You may configure Genesys Widgets to switch between Desktop and Mobile mode manually if necessary.

Screenshots

Dark theme

Light theme

Configuration

SideBar shares the _genesys.widgets.sidebar configuration namespace. SideBar has UI options to handle its position on the screen, disable expand feature sidebar, hide sidebar, and add new channels on the fly. The display order of channels is based on the order defined in channels configuration array.

Example

window._genesys.widgets.sidebar = {

	showOnStartup: true,

	position: 'left',

	expandOnHover: true,

	channels: [{

			name: 'ChannelSelector', 
			clickCommand: 'ChannelSelector.open', 
			clickOptions: {}, 

			 //use your own static string or i18n query string for the below two display properties
			displayName: 'Live Assist', 
			displayTitle: 'Get live help',

			icon: 'agent'
		}, 

		{
			name: 'WebChat' 
		}
	]
};

Options

Name	Type	Description	Default	Required
showOnStartup	boolean	Shows the sidebar on the screen when Widgets is launched.	true	false
position	string	Defines the position of sidebar on the screen. Acceptable values are left or right.	right	false
expandOnHover	boolean	Enables the expand (slide-out) or contract (slide-in) behavior of sidebar.	true	false
channels[index].name	string	Name of the channel. It can be found in the namespace section documentation of each Widget. Used to identify official channels vs custom channels. If a reserved name is used here, Sidebar will apply default values for that channel. A plugin name defined in the new custom plugin can also be given here. To override the default values or when defining a new custom channel/plugin, use the below following properties.	n/a	true
channels[index].clickCommand	string	Change the default command that is triggered when clicked.	n/a	false
channels[index].clickOptions	object	Pass valid command options that are used in above click command execution.	n/a	n/a
channels[index].readyEvent	string	Subscribes to this ready event published by a plugin.	n/a	false
channels[index].displayName	string or i18n query string	Change the default display name for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<plugin namespace>.<display key>	n/a	false
channels[index].displayTitle	string or i18n query string	Change the default tooltip content for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<plugin namespace>.<display key>	n/a	false
channels[index].icon	string	Change the default icon for this channel. For the list of icon names see Customize icons in Customize appearance.	n/a	false
channels[index].onClick	function	Define a custom onclick function, this overrides clickCommand and clickOptions.	n/a	false

Localization

For your custom plugins, you can define string key names and values for Name and Title (tooltip) to display on sidebar. The key format requires the plugin name, followed by "Title" or "Name". For example, a plugin named "MyPlugin" will have keys called "MyPluginName" and "MyPluginTitle".

Important

For information on how to set up localization, refer to Localize widgets and services.

Strings

{
	"SidebarTitle": "Need help?",
	"ChannelSelectorName": "Live Assistance",
	"ChannelSelectorTitle": "Get assistance from one of our agents right away",
	"CallUsName": "Call Us",
	"CallUsTitle": "Call Us details",
	"CallbackName": "Callback",
	"CallbackTitle": "Receive a Call",
	"WebChatName": "Live Chat",
	"WebChatTitle": "Live Chat",
	"AriaClose": "Close the menu Need help"
}

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('SideBar.open');

configure

Internal use only. The main App plugin shares configuration settings to widgets using each widget’s configure command. Sidebar widget has to be configured at least with one channel. The configure command can also be called at runtime with new configuration, this will override the existing configuration showing new channels on the screens.

Example

oMyPlugin.command('SideBar.configure', {

	showOnStartup: false,
	position: 'left',
	expandOnHover: false,
	channels: [
		{
			name: 'ChannelSelector',
			clickCommand: 'ChannelSelector.open',
			clickOptions: {},

			 //use your own static string or i18n query string for the below two display properties. 
Example for i18n query string: '@i18n:sidebar.ChannelSelectorName' where 'sidebar' refers to plugin namespace and
ChannelSelectorName' name refers to the property key containing the actual text.

			displayName: '@i18n:sidebar.ChannelSelectorName', 
			displayTitle: 'Get assistance from one of our agents right away', // Your own static string
			readyEvent: 'ChannelSelector.ready',
			icon: 'agent',
			onClick: function($, CXBus, Common) {
				_genesys.widgets.bus.command('MyPlugin.open');
			}
		}
		...
	]

}).done(function(e){

	// Sidebar configured successfully

}).fail(function(e){

	// Sidebar failed to configure properly
});

Options

Option	Type	Description
showOnStartup	boolean	Shows the sidebar on the screen when Widgets is launched.
position	string	Defines the position of sidebar on the screen.
expandOnHover	boolean	Enables the expand or contract behavior of sidebar.
channels	array	Array containing each channel configuration object. The order of channels are displayed based on the order defined here.
channels[index].name	string	Name of the channel. It can be found in the namespace section documentation of each Widget. Used to identify official channels vs custom channels. If a reserved name is used here, Sidebar will apply default values for that channel. To override the default values or when defining a new custom channel, use the below following properties.
channels[index].clickCommand	string	Change the default command that is triggered when clicked.
channels[index].clickOptions	object	Pass valid command options that are used in above click command execution.
channels[index].displayName	string or i18n query string	Change the default display name for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<plugin namespace>.<display key>.
channels[index].displayTitle	string or i18n query string	Change the default tooltip content for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<plugin namespace>.<display key>.
channels[index].readyEvent	string	Subscribes to this ready event published by a plugin.
channels[index].icon	string	Change the default Icon for this channel. For the list of Icon names see Customize icons in Customize appearance.
channels[index].onClick	function	Define a custom onclick function, this overrides clickCommand and clickOptions.

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('SideBar.ready', function(e){ /* sample code */ });

Name	Description	Data
ready	Sidebar is initialized and ready to accept commands.	n/a
opened	Sidebar widget has appeared on screen. For desktop it is displayed on the sides of the screen and in mobiles at the bottom corner as a button.	n/a
closed	Sidebar widget has been removed from the screen.	n/a
expanded	Sidebar widget has expanded, showing channel icon and name.	n/a
contracted	Sidebar widget has contracted back, showing channel icons only.	n/a

Resolutions

Status	When	Returns
resolved	When configuration options are provided and set	n/a
rejected	When no configuration options are provided	'Invalid configuration. Please ensure at least one channel is configured.'

open

Opens the Sidebar UI. In Desktop mode, it opens as an actual SideBar and shows the configured channels where as in mobile it opens as a button at the bottom to start.

Example

oMyPlugin.command('SideBar.open');

Resolutions

Status	When	Returns
resolved	When sidebar is successfully opened	n/a
rejected	When sidebar is already opened	'Already opened'

close

Closes the Sidebar UI.

Example

oMyPlugin.command('SideBar.close');

Resolutions

Status	When	Returns
resolved	When sidebar is successfully closed	n/a
rejected	When sidebar is already closed	'already closed'

expand

To show more details about the channels, Sidebar slides out from the sides of the screen on desktop machines but expands to full screen in mobile devices.

Example

oMyPlugin.command('SideBar.expand');

Resolutions

Status	When	Returns
resolved	When sidebar is successfully expanded	n/a
rejected	When sidebar is already expanded	'sidebar already expanded'

contract

Retracts the expanded version of Sidebar, showing only the channel buttons on desktop machines and the sidebar launcher button on mobile devices.

Example

oMyPlugin.command('SideBar.contract');

Resolutions

Status	When	Returns
resolved	When sidebar is successfully contracted	n/a
rejected	When sidebar is already contracted	sidebar already contracted