Jump to: navigation, search
(Update with the copy of version: draft)
Line 5: Line 5:
 
==Audience==
 
==Audience==
  
This document is for website developers who are in charge of the website code. You should have knowledge of HTML, JavaScript, and CSS.
+
This document is for website developers who are in charge of website code. You must have knowledge of HTML, JavaScript, and CSS.
  
==How Do I Deploy Genesys Widgets?==
+
==How can I deploy Genesys Widgets?==
  
# Embed Genesys Widgets into your website
+
We support two deployment methods:
# [[GWCConfig|Configure your Genesys Widgets]]
 
# [[GWCInternat|Setup Localization Options and Languages]]
 
# [[GWCCustomize|Styling Genesys Widgets]]
 
  
{{AnchorDiv|GWCDeploySteps}}
+
*[[GWCDeployment#lazy|Lazy-Loading]]—Lazy-Loading breaks the JavaScript bundle apart into individual plugin files and loads them into the page only as you need them. This is the preferred method of deploying Genesys Widgets.
  
== How to embed the Genesys Widgets into your website==
+
*[[GWCDeployment#all|All-In-One]]—The All-In-One method is the "classic" method of deploying Genesys Widgets. In this method, you have one JavaScript file and one CSS file that contain all plugins and resources.
  
Unzip the Genesys Widgets package to your web server, and then locate the path to your copy of the '''widgets.min.js''' file.
+
{{AnchorDiv|lazy}}
  
you can choose from the following methods to include the Genesys Widgets package on your webpage:
+
==Deploying Genesys Widgets (Lazy-Loading)==
  
===Inline Javascript Include===
+
===Files Used===
  
Add a script tag to include the Genesys Widgets package file (widgets.min.js)
+
* '''widgets/cxbus.min.js'''
 +
* '''widgets/plugins/widgets-core.min.js'''
 +
* '''widgets/plugins/*.*'''
 +
 
 +
A good starting point is the following script:
  
 
<source lang="javascript">
 
<source lang="javascript">
  
<script id="genesys-widgets-script" src="http://www.yourhost.com/path/to/widgets.min.js"></script>
+
<script src="widgets/cxbus.min.js" onload="javascript:CXBus.configure({debug:true,pluginsPath:'build/plugins/'});CXBus.loadFile('path/to/widgets.config.js').done(function(){CXBus.loadPlugin('widgets-core')});"></script>
  
 
</source>
 
</source>
  
===Inline Stylesheet/CSS Include===
+
This script does the following:
Add a link tag to include the Genesys Widgets stylesheet package file (widgets.min.css)
+
 
 +
# Loads '''cxbus.min.js'''. This makes the global CXBus instance available.
 +
# Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
 +
# Load your configuration file, '''widgets.config.js'''. (This is an imaginary file. You must create it).
 +
# Loads '''widgets-core''', the core Genesys Widgets library.
 +
 
 +
Use this script as a starting point and customize it as needed.
 +
 
 +
Remember that your configuration can be defined inline on the page or loaded in as a separate file (as shown in this script).
 +
 
 +
{{NoteFormat|Whichever method you choose, you must ensure your configuration is in the page before you load '''widgets-core'''. Otherwise, '''widgets-core''' cannot read the configuration.}}
 +
 
 +
{{NoteFormat|Refer to this article for help [[GWCConfig|configuring Genesys Widgets]].}}
 +
 
 +
===On-Demand Lazy-Loading===
 +
 
 +
Genesys Widgets is designed to load plugins into the page on-demand as you use the product. For example, if you call the command '''WebChat.open''', CXBus fetches the '''webchat.min.js''' plugin from the '''plugins/''' folder and loads it into the page. Any WebChat command triggers it to load. Likewise, WebChat calls WebChatService commands, thus CXBus loads '''webchatservice.min.js''' into the page as well.
 +
 
 +
===Preloading Plugins===
 +
 
 +
In some cases, you might not want to load plugins on-demand, or the demand is to load them at startup. A good example is SideBar. You probably want this plugin to appear on the screen immediately so the customer can use it. To make this possible, you can specify which plugins you want to preload at startup in your configuration.
  
 
<source lang="javascript">
 
<source lang="javascript">
<link id="genesys-widgets-styles" href="http://www.yourhost.com/path/to/widgets.min.css" type="text/css" rel="stylesheet"/>
+
   
 +
    _genesys.widgets.main.preload = [
 +
 
 +
        "sidebar"
 +
    ];
 +
 
 
</source>
 
</source>
  
===Dynamically Generate the Javascript Include===
+
You may specify as many plugins as you want in the preload list. The plugins load in order after you load Widgets Core.
  
The following code snippet will generate a script and link include tag automatically and provides you the option of loading the files immediately or delay loading the files until after the parent page has finished loading its content
+
All plugin names are lower-case. Please refer to the file names in the '''plugins/''' folder. For example, to preload '''webchat.min.js''', specify <tt>webchat</tt>, the first part of the file name.
  
<source lang="javascript">
+
You may find other plugins or features of plugins that necessitate preloading.
 +
 
 +
{{AnchorDiv|all}}
 +
==Deploying Genesys Widgets (All-in-One)==
  
// Widgets Instrumentation Script
+
===Files Used===
<script>
 
    (function(o){var f = function(){var d = o.location;o.aTags = o.aTags || [];
 
    for(var i=0;i<o.aTags.length;i++){var oTag = o.aTags[i];var fs = d.getElementsByTagName(oTag.type)[0], e;
 
    if(d.getElementById(oTag.id)) return; e = d.createElement(oTag.type); e.id = oTag.id;if(oTag.type == "script"){e.src = oTag.path;}
 
    else{e.type = 'text/css';e.rel = 'stylesheet';e.href = oTag.path;}if(fs){fs.parentNode.insertBefore(e, fs);}else{d.head.appendChild(e);}
 
    }},ol = window.onload;if(o.onload){typeof window.onload != "function"?window.onload=f:window.onload=function(){ol();f();}}else f();})({
 
  
    location: document,
+
* '''widgets/widgets.min.css'''
    onload: false,
+
* '''widgets/widgets.min.js'''
    aTags: [
 
 
        {
 
            type:"script",
 
            id:"genesys-widgets-script",
 
            path:"http://www.host.com/path/to/widgets.min.js"
 
        },
 
        {
 
            type:"link",
 
            id:"genesys-widgets-styles",
 
            path:"http://www.host.com/path/to/widgets.min.css"
 
        }
 
    ]
 
});
 
</script>
 
  
</source>
+
A good starting point is the following script:
  
This script will dynamically generate a Javascript include <script> tag+, CSS include <link> tag+ and place it into the page. By default the ID for the generated script and link tags are "genesys-widgets-script" and "genesys-widgets-styles". You may modify these ID's in the above script.
+
<source lang="javascript">
  
The following object is passed in with additional options:
+
<script src-"widgets/widgets.config.js"></script>
 +
<script src="widgets/widgets.min.js"></script>
 +
<link id="genesys-widgets-styles" href="http://www.yourhost.com/path/to/widgets.min.css" type="text/css" rel="stylesheet"/>
  
<source lang="javascript">
 
{
 
    location: document,
 
    onload: false,
 
    aTags: [
 
        {
 
            type:"script",
 
            id:"genesys-widgets-script",
 
            path:"http://www.yourhost.com/path/to/widgets.min.js"
 
        },
 
        {
 
            type:"link",
 
            id:"genesys-widgets-styles",
 
            path:"http://www.yourhost.com/path/to/widgets.min.css"
 
        }
 
    ]
 
}
 
 
</source>
 
</source>
  
====location====
+
First, you must define your configuration for Genesys Widgets. You can do this inline on the page by using a ''script'' tag, or you can store it in a separate file and load it in before '''widgets.min.js'''. In the script example above, we assume your configuration is stored in another file. You must create the '''widgets.config.js''' file for this script to function properly.  
location is your page document scope that can be used to inject widgets script and link tags.
 
 
 
====onload====
 
onload is an optional flag that, when set to true, will delay loading the Widgets files until after the webpage has fully loaded (window.onload). By default this value is false and the Widgets files are loaded immediately.
 
  
====path====
+
{{NoteFormat|Whichever method you choose, you must ensure your configuration is in the page before you load '''widgets.min.js'''. Otherwise, '''widgets.min.js''' cannot read the configuration.}}
path is the URL or path to the location of the Genesys Widgets Javascript and CSS files that Genesys provides. You can host these files on your own web servers or on a Content Delivery Network (CDN).
 
  
====type====
+
{{NoteFormat|Refer to this article for help [[GWCConfig|configuring Genesys Widgets]].}}
type is the html tag type that will be added in to the page i.e. 'script' tag for Javascript file and 'link' tag for CSS file.
 
  
Now you can [[GWCConfig|configure the Genesys Widgets]] and the products and services associated with it.
 
{{Cargo_Popular|Title={{PONYDOCSTITLE}}}}
 
 
[[Category:V:PSAAS:Public]]
 
[[Category:V:PSAAS:Public]]

Revision as of 17:11, July 27, 2018

Genesys Widgets Deployment Guide

This guide provides the steps required to instrument your website with Genesys Widgets.

Audience

This document is for website developers who are in charge of website code. You must have knowledge of HTML, JavaScript, and CSS.

How can I deploy Genesys Widgets?

We support two deployment methods:

  • Lazy-Loading—Lazy-Loading breaks the JavaScript bundle apart into individual plugin files and loads them into the page only as you need them. This is the preferred method of deploying Genesys Widgets.
  • All-In-One—The All-In-One method is the "classic" method of deploying Genesys Widgets. In this method, you have one JavaScript file and one CSS file that contain all plugins and resources.

Deploying Genesys Widgets (Lazy-Loading)

Files Used

  • widgets/cxbus.min.js
  • widgets/plugins/widgets-core.min.js
  • widgets/plugins/*.*

A good starting point is the following script:

<script src="widgets/cxbus.min.js" onload="javascript:CXBus.configure({debug:true,pluginsPath:'build/plugins/'});CXBus.loadFile('path/to/widgets.config.js').done(function(){CXBus.loadPlugin('widgets-core')});"></script>

This script does the following:

  1. Loads cxbus.min.js. This makes the global CXBus instance available.
  2. Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
  3. Load your configuration file, widgets.config.js. (This is an imaginary file. You must create it).
  4. Loads widgets-core, the core Genesys Widgets library.

Use this script as a starting point and customize it as needed.

Remember that your configuration can be defined inline on the page or loaded in as a separate file (as shown in this script).

Important
Whichever method you choose, you must ensure your configuration is in the page before you load widgets-core. Otherwise, widgets-core cannot read the configuration.
Important
Refer to this article for help configuring Genesys Widgets.

On-Demand Lazy-Loading

Genesys Widgets is designed to load plugins into the page on-demand as you use the product. For example, if you call the command WebChat.open, CXBus fetches the webchat.min.js plugin from the plugins/ folder and loads it into the page. Any WebChat command triggers it to load. Likewise, WebChat calls WebChatService commands, thus CXBus loads webchatservice.min.js into the page as well.

Preloading Plugins

In some cases, you might not want to load plugins on-demand, or the demand is to load them at startup. A good example is SideBar. You probably want this plugin to appear on the screen immediately so the customer can use it. To make this possible, you can specify which plugins you want to preload at startup in your configuration.

    
    _genesys.widgets.main.preload = [

        "sidebar"
    ];

You may specify as many plugins as you want in the preload list. The plugins load in order after you load Widgets Core.

All plugin names are lower-case. Please refer to the file names in the plugins/ folder. For example, to preload webchat.min.js, specify webchat, the first part of the file name.

You may find other plugins or features of plugins that necessitate preloading.

Deploying Genesys Widgets (All-in-One)

Files Used

  • widgets/widgets.min.css
  • widgets/widgets.min.js

A good starting point is the following script:

<script src-"widgets/widgets.config.js"></script>
<script src="widgets/widgets.min.js"></script>
<link id="genesys-widgets-styles" href="http://www.yourhost.com/path/to/widgets.min.css" type="text/css" rel="stylesheet"/>

First, you must define your configuration for Genesys Widgets. You can do this inline on the page by using a script tag, or you can store it in a separate file and load it in before widgets.min.js. In the script example above, we assume your configuration is stored in another file. You must create the widgets.config.js file for this script to function properly.

Important
Whichever method you choose, you must ensure your configuration is in the page before you load widgets.min.js. Otherwise, widgets.min.js cannot read the configuration.
Important
Refer to this article for help configuring Genesys Widgets.
Comments or questions about this documentation? Contact us for support!