Widgets Bus API overview
Contents
- 1 Overview
- 2 CXBus Reference
- 3 CXBus Plugin Interface Reference
- 3.1 oMyNewPlugin.registerCommand
- 3.2 oMyNewPlugin.registerEvents
- 3.3 oMyNewPlugin.subscribe
- 3.4 oMyNewPlugin.publish
- 3.5 oMyNewPlugin.republish
- 3.6 oMyNewPlugin.publishDirect
- 3.7 oMyNewPlugin.command
- 3.8 oMyNewPlugin.before
- 3.9 oMyNewPlugin.registry
- 3.10 oMyNewPlugin.subscribers
- 3.11 oMyNewPlugin.namespace
- 3.12 oMyNewPlugin.ready
Learn about the bus that all widgets components are built on.
Overview
Genesys Widgets is built on top of the CXBus messaging bus. CXBus uses the publish-subscribe model to facilitate communication between the Widgets components, all of which are plugins that can both publish events on the bus and subscribe to the events they are interested in.
With the help of the Widgets-Core plugins, CXBus makes it possible to combine the logic implemented by user interface plugins, service plugins, and utility plugins into cohesive products that can provide chat sessions, schedule callbacks, and so on.
Publications and subscriptions are loosely bound so that you can publish and subscribe to any event without that event explicitly being available. This allows for plugins to lazy load into the bus or provide conditional logic in your plugins so they can wait for other plugins to be available.
CXBus events and commands are executed asynchronously using deferred methods and promises. This allows for better performance and standardized Pass/Fail handling for all commands. Command promises are not resolved until the command is finished, including any nested asynchronous commands that command may invoke. This gives you assurance that the command completed successfully and the timing of your follow-up action will occur at the right time. As for permissions, CXBus provides metadata in every command call including which plugin called the command and at what time. This allows for plugins to selectively allow/deny invocation of commands.
You can use three methods to access the Bus:
- Global access
- Genesys Widgets onReady callback
- Extensions
Global access
QuickBus
window._genesys.widgets.bus
For quick access to call commands on the bus, you can access the QuickBus instance after Genesys Widgets loads. QuickBus is a CXBus plugin that is exposed globally for your convenience. Typical use cases for using QuickBus are for debugging or calling a command when a link or button is clicked. Instead of creating your own plugin, you can use QuickBus to add the click handler inline in your HTML.
Example:
<a href="#" onclick="_genesys.widgets.bus.command('WebChat.open');">Open WebChat</a>
Global CXBus
CXBus is available as a global instance named "CXBus" (or window.CXBus). Unlike QuickBus, this is not a plugin but CXBus itself.
CXBus has been updated to include a "command" method that allows you to execute a command directly from the CXBus instance.
Example:
CXBus.command("WebChat.open");
Genesys Widgets onReady callback
Genesys Widgets provides an "onReady" callback function that you can define in your configuration. This will be triggered after Genesys Widgets initializes. QuickBus is provided as an argument in this function, but you may also access CXBus globally in your function.
window._genesys.widgets.onReady = function(QuickBus){
// Use the QuickBus plugin provided here to interface with the bus
// QuickBus is analogous to window._genesys.widgets.bus
};
Extensions
You can define your own plugins/widgets that interface with Genesys Widgets. For more information, please see Extensions.
CXBus Reference
The CXBus instance is exposed globally (window.CXBus) and has several methods available:
- CXBus.command
- CXBus.configure
- CXBus.loadFile
- CXBus.loadPlugin
- CXBus.registerPlugin
CXBus.command
Calls a command on the bus under the namespace "CXBus". Use this to quickly and easily call commands without needing to generate a unique plugin interface object first.
Example
CXBus.command("WebChat.open", {});
Arguments
Name | Type | Description |
---|---|---|
Command name | string | The name of the command you wish to execute. |
Command options | object | Optional: You may pass an object containing properties that the command will accept. Refer to the documentation on each command to see what options are available. |
Returns
Always returns a promise. You can define done(), fail(), or always() callbacks for every command.
CXBus.configure
Allows you to change configuration options for CXBus.
Example
CXBus.configure({debug: true, pluginsPath: "/js/widgets/plugins/"});
Arguments
Name | Type | Description |
---|---|---|
Configuration options | object | An object containing properties, similar to command options. In this object you can change configuration options for CXBus. |
Configuration options
Name | Type | Description |
---|---|---|
debug | boolean | Enable or disable CXBus logging in the javascript console. Set to true to enable; set to false to disable. Default value is false. |
pluginsPath | string | The location of the Genesys Widgets "plugins" folder.
Example: "/js/widgets/plugins/" The default value here is "". This configuration option is used for lazy loading plugin files. Be sure to configure this option when using Genesys Widgets in lazy loading mode. |
pluginMap | object | Used to change the target JS file for each plugin or to add a new plugin.
Example: {sendmessage: "https://www.yoursite.com/plugins/custom-sendmessage.js"} CXBus will automatically lazy load plugins defined in this object when something tries to call a command on that plugin. For instance, if SendMessage.open is called and SendMessage isn't loaded, CXBus will fetch it from the default "plugins/" folder. If you want to load a different SendMessage widget, you can override the default URL of the JS file associated with "sendmessage". You can also prevent a plugin from loading by mapping it to false. Example: {sendmessage: false}Important
|
Returns
This method returns nothing.
CXBus.loadFile
Loads any javascript file.
Example
CXBus.loadFile("/js/widgets/plugins/webchat.min.js");
Arguments
Name | Type | Description |
---|---|---|
File path | string | Loads a javascript file based on the file path specified. |
Returns
Always returns a promise. You can define done(), fail(), or always() callbacks. When the file loads successfully, done() will be triggered. When the file fails to load, fail() will be triggered.
CXBus.loadPlugin
Loads a plugin file from the configured "plugins" folder.
Example
CXBus.loadPlugin("webchat");
Arguments
Name | Type | Description |
---|---|---|
Plugin name | string | Loads a plugin from the "plugins" folder by name (configured by the "pluginsPath" option). Plugin names match their CXBus namespaces but are lowercase. Example: To load WebChat, use "webchat". You can refer to the files inside the "plugins" folder as well. The first part of the file name will be the name you use with this function. Example: Use "webchat" to load "webchat.min.js". |
Returns
Always returns a promise. You can define done(), fail(), or always() callbacks. When the plugin loads successfully, done() will be triggered. When the plugin fails to load, fail() will be triggered.
CXBus.registerPlugin
Registers a new plugin namespace on the bus and returns a plugin interface object. You will use the plugin interface object to publish, subscribe, call commands, and perform other CXBus functions.
Example
var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");
Arguments
Name | Type | Description |
---|---|---|
CXBus plugin namespace | string | The namespace you want to reserve for your plugin. |
Returns
If the namespace is not already taken, it will return a CXBus plugin interface object configured with the selected namespace. If the namespace is already taken, it will return false.
CXBus Plugin Interface Reference
When you register a plugin using CXBus.registerPlugin(), it returns a CXBus Plugin Interface Object. This object contains many methods that allow you to interact with other plugins on the bus.
Let's start with the assumption that we've created the below plugin interface:
var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");
oMyNewPlugin.registerCommand
Allows you to register a new command on the bus for other plugins to use.
Example
oMyNewPlugin.registerCommand("test", function(e){
console.log("'MyNewPlugin.test' command was called", e)
e.deferred.resolve();
});
Arguments
Name | Type | Description |
---|---|---|
Command name | string | The name you want for this command. When other plugins call your command, they must specify the namespace as well. Example: "test" is called on the bus as "MyNewPlugin.test". |
Command function | function | The command function that is executed when the command is called. This function is provided an Event Object that contains metadata and any options passed in. |
Event object
Name | Type | Description |
---|---|---|
time | number (integer time) | The time the command was called. |
commander | string | The name of the plugin that called your command. Example: If your plugin called a command, the value would be "MyNewPlugin". You can use this information to create plugin-specific logic in your command. |
command | string | The name of this command. Example: "MyNewPlugin.test". This can be useful if you are using the same function for multiple commands and need to identify which command was called. |
deferred | deferred promise object | When a command is called, a promise is generated. You must resolve this promise in your command without exception. Either execute e.deferred.resolve() or e.deferred.reject(). You may pass values back through these methods. If you pass a value back inside reject() it will be printed in the console as an error log automatically. |
data | object | This is the object containing command options passed in when the command was called. If no options were passed, this will default to an empty object. |
Returns
Returns true.
oMyNewPlugin.registerEvents
Registering events is a formality that allows CXBus to keep a registry of all possible events. You don't need to register events before publishing them, but it's a best practice to always register events.
Example
oMyNewPlugin.registerEvents(["ready", "testEvent"]);
Arguments
Name | Type | Description |
---|---|---|
Event name array | array | An array of event names. |
Returns
Returns true if at least one value event was included in the array. Returns false if no events are included in the array or no array is passed in.
oMyNewPlugin.subscribe
Subscribes your plugin to an event on the bus with a callback function. When the event is published, the callback function is executed. You can subscribe to any event, even if the event does not exist. This allows for binding events that may come in the future.
Example
oMyNewPlugin.subscribe("WebChat.opened", function(e){
// e = Event Object. Contains metadata and attached data
//
// Example Event Object data:
//
// e.time == 1532017560154
// e.event == "WebChat.opened"
// e.publisher == "WebChat"
});
Arguments
Name | Type | Description |
---|---|---|
Event name | string | The name of the event you want to subscribe to. Must include the plugin's namespace. |
Callback function | function | A function to execute when the event is published. An Event Object is passed into this function that gives you access to metadata and attached data. |
Event object
Name | Type | Description |
---|---|---|
time | number (integer time) | The time the event was published. |
event | string | The name of the event, including namespace. That can be useful if you are using the same function to handle multiple events. |
publisher | string | The namespace of the plugin that published the event. |
Returns
Returns the name of the event back to you if the subscription was successful. Returns false if you did not specify an event and/or a callback function.
oMyNewPlugin.publish
Publishes an event on the bus under your plugin's namespace.
Example
// Publishes the event "MyNewPlugin.testEvent" with attached data {test: "123"}
oMyNewPlugin.publish("testEvent", {test: "123"});
Arguments
Name | Type | Description |
---|---|---|
Event name | string | The name of the event you want to publish. Do not include the plugin namespace. |
Attached data | object | An object of arbitrary properties you can attach to your event. |
Returns
Always returns true.
oMyNewPlugin.republish
A special method of publishing intended for one-off events like "ready". In some cases, an event will fire only once. If a plugin is loaded at a later time that needs to subscribe to this event, it will never get it because it will never be published again. To solve this problem, the "republish" method will automatically republish an event to new subscribers as soon as they subscribe to it.
In Genesys Widgets, every plugin publishes a "ready" event. This event is published using "republish" so that any plugin loaded and/or initialized after can still receive the event.
It is important that you only use "republish" for events that publish once. Using republish multiple times for the same event can cause unwanted behavior.
Genesys Widgets plugins all publish a "ready" event. This is not related to the CXBus plugin interface object's "ready()" method. Calling oMyNewPlugin.ready() will not publish any events.
Example
oMyNewPlugin.republish("ready", {...});
Arguments
Name | Type | Description |
---|---|---|
Event name | string | The name of the event you want to have republished. Do not include the plugin namespace. |
Attached data | object | An object of arbitrary properties you can attach to your event. |
Returns
Always returns true.
oMyNewPlugin.publishDirect
A slight variation on "publish", this method will only publish an event on the bus if it has subscribers. The intention of this method is to avoid spamming the logs with events that no plugins are listening to. In particular, if you have an event that publishes frequently or on an interval, "publishDirect" may be used to minimize its impact on logs in the console.
Example
oMyNewPlugin.publishDirect("poll", {...});
Arguments
Name | Type | Description |
---|---|---|
Event name | string | The name of the event you want to have republished. Do not include the plugin namespace. |
Attached data | object | An object of arbitrary properties you can attach to your event. |
Returns
Always returns true.
oMyNewPlugin.command
Have your plugin call a command on the bus.
Example
oMyNewPlugin.command("WebChat.open", {...}).done(function(e){
// If command succeeds
// e == any returned data
}).fail(function(e){
// If command fails
// e == any returned data
}).always(function(){
// Always executed
});
Arguments
Name | Type | Description |
---|---|---|
Command name | string | Name of the command you wish to call. |
Command options | string | Optional: An object containing properties the command will use in its execution. Refer to plugin references for a list of options available for each command. |
Returns
Always returns a promise. You can define done(), fail(), or always() callbacks for every command.
oMyNewPlugin.before
Allows you to interrupt a registered command on the bus with your own "before" function. You may modify the command options before they're passed to the command, you may trigger some action before the command is executed, or you can cancel the command before it executes.
You may specify more than one "before" function for a command. If you do, they will be executed in a chain where the output of the previous function becomes the input for the next function. You cannot remove "before" functions once they have been added.
Example
oMyNewPlugin.before("WebChat.open", function(oData){
// oData == the options passed into the command call
// e.g. if this command is called: oMyPlugin.command("WebChat.open", {form: {firstname: "Mike"
// then oData will == {form: {firstname: "Mike"
// You must return oData back, or an empty object {} for execution to continue.
// If you return false|undefined|null or don't return anything, execution of the command will be stopped
return oData;
});
Arguments
Name | Type | Description |
---|---|---|
Command name | string | Name of the function you want to interrupt with your "before" function. |
"before" function | function | A function that accepts command options (oData in above example). If you want the command to continue executing, you must return the oData object. If you want to cancel the command, return false or undefined or don't return anything. You may modify the contents of oData before it is sent to the command. This allows you to override command options or add on dynamic options depending on external conditions. |
Returns
Returns true when you pass a properly formatted command name (e.g. "PluginName.commandName"). Returns false when you pass an improperly formatted command name.
oMyNewPlugin.registry
Returns the CXBus Registry lookup table.
Example
oMyNewPlugin.registry();
Arguments
No arguments.
Returns
Returns the internal CXBus registry that tracks all plugins, their commands, and their events.
Registry Structure Example:
{
"Plugin1": {
commands: ["command1", "command2"],
events: ["event1", "event2"]
},
"Plugin2": {
commands: ["command1", "command2"],
events: ["event1", "event2"]
}
}
oMyNewPlugin.subscribers
Returns a list of events and their subscribers.
Example
oMyNewPlugin.subscribers();
Arguments
No arguments.
Returns
Returns an object identifying a list of events being subscribed to, and a list of plugin names subscribed to each event.
Example of WebChatService's subscribers:
// Format {"eventname": ["subscriber1", "subscriber2"]}
{
"WebChatService.agentConnected":["WebChat"],
"WebChatService.agentDisconnected":["WebChat"],
"WebChatService.ready":[],
"WebChatService.started":["WebChat"],
"WebChatService.restored":["WebChat"],
"WebChatService.clientDisconnected":[],
"WebChatService.clientConnected":[],
"WebChatService.messageReceived":["WebChat"],
"WebChatService.error":["WebChat"],
"WebChatService.restoreTimeout":["WebChat"],
"WebChatService.restoreFailed":["WebChat"],
"WebChatService.ended":["WebChat"],
"WebChatService.agentTypingStarted":["WebChat"],
"WebChatService.agentTypingStopped":["WebChat"],
"WebChatService.restoredOffline":["WebChat"],
"WebChatService.chatServerWentOffline":["WebChat"],
"WebChatService.chatServerBackOnline":["WebChat"],
"WebChatService.disconnected":["WebChat"],
"WebChatService.reconnected":["WebChat"]
}
oMyNewPlugin.namespace
Returns your plugin's namespace.
Example
oMyNewPlugin.namespace();
Arguments
No arguments.
Returns
Returns your plugin's namespace. If your plugin's namespace is "MyNewPlugin", it will return "MyNewPlugin".
oMyNewPlugin.ready
Marks your plugin as ready to have its commands called. This method is required to be called for all plugins. You should call this method after all your commands are registered, initialization code is finished, and configuration has completed. Failure to call this method will result in your commands being unexecutable.
Example
oMyNewPlugin.ready();
Arguments
No arguments.
Returns
Returns nothing.