Documentation:PSAAS:Administrator:Common:Public

Common

Common is a utility object available for import into Plugins/Widgets and Extensions. It is also accessible directly from the path window._genesys.widgets.common.

Common provides utility functions and dynamically generates common HTML Containers used throughout Genesys Widgets.

For all examples below, assume that _genesys.widgets.common has been stored in a local variable named "Common".

var Common = _genesys.widgets.common;

Methods

Common.Generate.Container({options})

Dynamically generates a new HTML Container in matching the style of Genesys Widgets with the selected components you request in your options object. Returns the generated container HTML as a jQuery wrapped set.

Argument	Type	Description
options	object	An object containing options to apply to the generated container.
options.type	string	"generic" or "overlay". Overlay containers have special CSS properties for appearing inside the Overlay widget. Default is "generic".
options.title	string	Title to apply to the container's titlebar area.
options.body	string or jQuery wrapped set	The HTML body you want the container to wrap.
options.icon	string	CSS Classname of icon to use
options.controls	string	Select from a set of window control buttons to show at the top right. "close" = Show only the close button. "minimize" = Show only the minimize button. "all" = Show both close and minimize buttons.
options.buttons	object	Options for displaying action buttons at the bottom of the container, such as OK and Cancel buttons.
options.buttons.type	string	Currently "binary" is the only supported button set at this time. Additional sets and arrangements will be available in a later release. Please pass "binary" as the type here if you wish to show typical "accept" and "dismiss" buttons.
options.buttons.primary	string	Display name on the primary button. (for example 'OK', 'Yes', 'Accept', 'Continue', etc)
options.buttons.secondary	string	Display name on the secondary button. (for example 'Cancel', 'No', 'Dismiss', 'Reject', etc)

Example

"Generate an Overlay Container"

var ndContainer = Common.Generate.Container({
    
    type: "overlay",
    title: "My Overlay",
    body: "Some HTML here as a string or jQuery wrapped set",
    icon: "call-outgoing",
    controls: "close",
    buttons: false
}),

"Generate a Toast Container"

var ndContainer = Common.Generate.Container({

    type: "generic",
    title: "My Toast",
    body: "Some HTML here as a string or jQuery wrapped set",
    icon: "chat",
    controls: "",
    buttons: {

        type: "binary",
        primary: "OK",
        secondary: "Cancel"
    }
}),

Common.Generate.Buttons({options})

Dynamically generates a new HTML Binary Button set in matching the style of Genesys Widgets with the selected options in your options object. Returns the buttons as a jQuery wrapped set.

Argument	Type	Description
options	object	Options for generating buttons, such as OK and Cancel buttons.
options.type	string	Currently "binary" is the only supported button set at this time. Additional sets and arrangements will be available in a later release. Please pass "binary" as the type here if you wish to show typical "accept" and "dismiss" buttons.
options.primary	string	Display name on the primary button. (for example 'OK', 'Yes', 'Accept', 'Continue', etc)
options.secondary	string	Display name on the secondary button. (for example 'Cancel', 'No', 'Dismiss', 'Reject', etc)

Example

"Generate Binary Buttons"

var ndButtons = Common.Generate.Buttons( {

    type: "binary",
    primary: "OK",
    secondary: "Cancel"
}),

Common.Generate.Icon(name)

Dynamically generates an icon from the included icon set. Icons are in SVG format.

Argument	Type	Description
name	string	Select the icon you want to generate by name. See the icon reference page for icon names.

Example

"Generate Chat Icon"

var ndChatIcon = Common.Generate.Icon("chat");

"Insert Chat Icon"

$("#your_icon_container").append(Common.Generate.Icon("chat"));

Common.config(object)

Configure some debug options for Common at runtime.

Argument	Type	Description
object	object	Supported options are "debug" and "debugTimestamps". Setting debug to true will enable debug messages created by Common.log(). Setting debugTimestamps to true will add timestamps to the front of each debug message created by Common.log(). Default value for both is false.

Example

"Enable full debug logging"

 
Common.configure({debug: true, debugTimestamps: true});

Common.checkPath(object, path)

Check for the existence of a sub-property of an object at any depth. Returns the value of that property if found otherwise it returns false. Useful for checking configuration object paths without having to check each sub-property level individually.

Argument	Type	Description
object	object	An Object you want checked for a particular sub property at any depth
path	string	The object path in dot notation you wish to search for.

Example

"Check for window._genesys.main"

var oMainConfig = false;

if(oMainConfig = Common.checkPath(window, "_genesys.main")){
        
    //... Utilize oMainConfig
}

Common.createPath(object, path, value)

Related to checkPath, createPath lets you specify a target object and path string but lets you create the path and set a value for it. This saves you the pain of defining each node in the path individually. All nodes in your path will be created as objects. Your final node, the property you are trying to create, will be whatever value you assign it.

Argument	Type	Description
object	object	An Object you want to add your new path to.
path	string	The object path in dot notation you wish to create.
value	any	The value you want to assign to the final node (property) in your path

Example

"Create window._genesys.main"

var oMainConfig = false;

if(oMainConfig = Common.createPath(window, "_genesys.main", {debug:true})){
        
    //... Utilize oMainConfig
}

Common.linkify(string, options)

Search for and convert URLs within a string into HTML links. Returns transformed string.

Argument	Type	Description
string	string	Any string you want to check for URLs and have them converted.
options	object	A list of options to apply to the linkify operation.
options.target	string	Choose the HTML TARGET attribute to apply to the generated links. Default is "_blank". Set this option to "self" to apply the target "_self" to the generated links.

Example

"Check for window._genesys.main"

var sString = "Please visit www.genesys.com";

sString = Common.linkify(sString, {target: 'self'});

// sString == "Please visit <a href='www.genesys.com' target='_self'>www.genesys.com</a>"

Common.log(mixed, type)

Log something to the browser's console. When using Common.log, _genesys.main.debug must be set to true to see your logs. This allows you to add debug logging to your code without worrying about unwanted debug messages in production. If timestamps are enabled, they will be prefixed to all messages printed through Common.log.

Argument	Type	Description
mixed	Any	Any value or message you'd like to log
type	string	You can specify the log type, such as "log", "debug" and "error". Default type is "log". Note, if your browser doesn't support the "debug" or "error" log type, use "log" instead.

Example

"Check the contents of window._genesys.main"

var Common = _genesys.widgets.common;

Common.log(window._genesys.main);

if(!window._genesys.main){

    Common.log("window._genesys.main is not defined", "error");
}

Common.sanitizeHTML(string)

Search for and escape < and > characters within a string. Returns transformed string. Useful for escaping HTML.

Argument	Type	Description
string	string	Any string you want to be transformed.

Example

"Check for window._genesys.main"

var sString = "Please visit <a href='www.genesys.com' target='_self'>www.genesys.com</a>";

sString = Common.sanitizeHTML(sString);

// sString == "Please visit &lt;a href='www.genesys.com' target='_self'&gt;www.genesys.com&lt;/a&gt;'"

Common.updateTemplateI18n(element, object)

Searches through an element's contents for i18n string elements to update with new strings. Used when updating the language in real-time. Works by searching for elements with the CSS classname "i18n" and reading the custom attribute "data-message" to match the string name in the language object. See example below.

Argument	Type	Description
element	jQuery wrapped set	Element you want to search within to replace i18n strings.
object	Object of i18n Strings	The list of languages strings you want to update your UI with. This object comes from the App.i18n event or you can define your own custom object inline or using some other system. Object format is a simple name:value pair format. the "data-message" attribute on your HTML element must match one of these property names to be updated.

Example

"Check for window._genesys.main"

var ndContainer = $("<div><button class="i18n" data-message="CustomButton001"></button></div>");

Common.updateTemplateI18n(ndContainer, {CustomButton001: "Accept"});

// ndContainer == <div><button class="i18n" data-message="CustomButton001">Accept</button></div>