Widgets

SideBar

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Widgets API Reference for version Current of Widgets.
Feature coming soon

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

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.

The image on the left shows Sidebar when it is initially loaded, while the one on the right shows what it looks like when it's expanded.

Sidebar-Desktop-Dark.pngSidebar-Desktop-Dark-Expanded.png

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 fullscreen 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

Configuration

SideBar shares the _genesys.widgets.sidebar configuration namespace. SideBar has UI options to handle the position of sidebar on the screen, disable expand feature sidebar, hide sidebar and add new channels on the fly. The display of channels order 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: 'Offers', 
			displayName: '@i18n:sidebar.OffersName', 
			displayTitle: '@i18n:sidebar.OffersName' 
		}, 

		{
			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. right false
expandOnHover boolean Enables the expand (slide-out) or contract (slide-in) behaviour 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:.. 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:.. 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 the Localization Guide

Strings

{
	"SidebarTitle": "Need help?",
	"ChannelSelectorName": "Live Assistance",
	"ChannelSelectorTitle": "Get assistance from one of our agents right away",
	"SearchName": "Search",
	"SearchTitle": "Search",
	"OffersName": "Offers",
	"OffersTitle": "Offers",
	"CallUsName": "Call Us",
	"CallUsTitle": "Call Us details",
	"CallbackName": "Callback",
	"CallbackTitle": "Receive a Call",
	"SendMessageName": "Send Message",
	"SendMessageTitle": "Send Message",
	"WebChatName": "Live Chat",
	"WebChatTitle": "Live Chat",
        "ClickToCallName": "Click To Call",
	"ClickToCallTitle": "Click to Call"
}

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 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:..
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:..
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.


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

|advanced=No |Status=No }}

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 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

}}

Retrieved from "https://all.docs.genesys.com/WID/Current/SDK/SideBar-combined (2019-11-13 05:45:21)"