WID/Current/GCDeveloper/Branding - Revision history

WikiSysop at 06:00, June 23, 2022

2022-06-23T06:00:44Z

WikiSysop at 04:15, June 23, 2022

2022-06-23T04:15:37Z

Xavier: Published

2022-06-17T10:32:57Z

Published

WikiSysop at 07:30, June 17, 2022

2022-06-17T07:30:55Z

Chrissy.forrest@genesys.com: Published

2021-02-03T20:49:15Z

Published

New page

{{Article
|Standalone=No
|DisplayName=Customize appearance
|TocName=Customize appearance
|Context=Use ''themes'' to change the appearance of Genesys Widgets. Themes allow you to apply colors and fonts to all of your widgets in a single operation.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|alignment=Vertical
|structuredtext=Genesys Widgets includes two built-in themes: '''dark''' and '''light'''. The dark theme is active by default.

'''Dark theme'''

[[File:Darktheme.png|500x500px]]

'''Light theme'''

[[File:Lighttheme.png|500x500px]]
|Status=No
}}{{Section
|sectionHeading=Set the active theme
|anchor=sat
|alignment=Vertical
|structuredtext=There are two ways to set the active theme:

'''Configuration'''

<source lang="javascript">
window._genesys.widgets.main.theme = "light"; // or "dark"
</source>

'''Widget bus command'''

<source lang="javascript">
window._genesys.widgets.bus.command("App.setTheme", {theme: "light"}); // or "dark"
</source>
|Status=No
}}{{Section
|sectionHeading=Create a custom theme
|anchor=cct
|alignment=Vertical
|structuredtext====Theme templates===
Genesys Widgets uses special LESS files called ''theme templates'' to define themes. Use a theme template to create a new color palette and add custom styles. Everything is laid out clearly in the template file.

LESS syntax defines local variables that allow you to create a clear color palette consisting of no less than 28 separate color variables, which are grouped by their usage:

*Background Colors
*Text Colors
*Icon Colors
*Border Colors
*Outline Colors

At a bare minimum, you can create a new style by simply changing the color values in the color palette. You can also add or remove colors from this palette as you see fit.

'''Color palette example'''
<source lang="css">
/* Color Palette */

@bg_color_1: #33383D; // Main Background Color
@bg_color_2: #444A52; // Form Inputs
@bg_color_3: #222529; // Button default
@bg_color_4: #5081E1; // Button primary gradient 1
@bg_color_5: #4375D6; // Button primary gradient 2
@bg_color_6: #CCCCCC; // Button disabled / scrollbar color
@bg_color_7: #212529; // Native scrollbar track color
@bg_color_8: #A3A8AE; // Scrollbar color

@txt_color_1: #FDFDFD; // Main text color
@txt_color_2: #98A7B8; // footer text
@txt_color_3: #FDFDFD; // Button default & primary / autocomplete text hover color
@txt_color_4: #FDFDFD; // Hyperlink color
@txt_color_5: #C5CCD6; // Placeholder color
@txt_color_6: #F53131; // Alert/error color

@icon_color_1: #FDFDFD; // Base icon color
@icon_color_2: #8C8C8C; // Secondary icon color (multitone only)
@icon_color_3: #000000; // Icon shadow color (multitone only)
@icon_color_4: #000000; // Icon secondary shadow color (multitone only)
@icon_color_5: #98A7B8; // Window control icon color
@icon_color_6: #98A7B8; // Form input icon overlay color (e.g. "clear" icon)
@icon_color_7: #5081E1; // Interactive icon color 1 (attach files, delete file, etc)
@icon_color_8: #4AC764; // Positive Color (confirmation, availability, usually green)
@icon_color_9: #F53131; // Negative Color (error, exception, usually red)
@icon_color_10: #F8A740; // Warning Color (warning, pending, offline, usually yellow or orange)
@icon_color_11: #FDFDFD; // Icon color for primary buttons

@border_color_1: #222529; // Main border color
@border_color_2: #2E69DB; // Button primary
@border_color_3: transparent; // Button default
@border_color_4: transparent; // Button disabled
@border_color_5: #F53131; // Alert/error color
@border_color_6: #758384; // Form controls default state

@outline_color_1: #75A8FF; // Form input focus outline / autocomplete hover background color
@outline_color_2: #DAE6FC; // Outline color for primary buttons
</source>

====Sample theme template files====
'''Note''': Click the following links to automatically download the sample template files to your computer.

{{Repository|theme-template-dark.less|bc0a2c34-c723-477e-9c48-f651490970d9|theme-template-dark.less}}<br />
{{Repository|theme-template-light.less|600aaa4a-386d-474b-be57-0692cc26a800|theme-template-light.less}}

Theme templates are LESS files, which must be converted to CSS before being used on a website. Use a website or tool to convert them when you're ready to test and implement them on your site.

By default, theme templates override the styles of all of your Genesys Widgets—but you can also make changes that only affect a specific widget, as described below.

===Name a theme===
In the "dark" theme template file, the first class selector is defined as:

'''.cx-widget.cx-theme-dark'''

'''.cx-widget''' is the base class for the entire Genesys Widget UI. The outermost container of every widget or standalone UI element has this class and is used to identify UI elements that belong to Genesys Widgets.

'''.cx-theme-dark''' is the class name created for the "dark" theme. Themes are applied by searching for all elements with the '''.cx-widget''' class and appending the theme's classname to it. Thus, the combined class selector indicates styles that will be applied only when your custom theme is active in the configuration object.

You can name your theme classname anything you wish. There are no restrictions or limitations.

In a later step, you will register this theme classname in your configuration.

===Customization guidelines===
When you create your own themes, you can only use the following CSS properties:

*color
*background
*font-family
*font-style
*border-color
*border-style
*and other non-structural properties

{{NoteFormat|Widgets primarily relies on class names for CSS selectors, rather than fixed node path selectors. Using class names allows for the HTML structure to be changed without breaking selectors. For example, the selector ".cx-webchat .cx-message" is all that's needed to target message bubbles inside WebChat. Using a fixed node path equivalent, like "div.cx-webchat > div.cx-body > div.cx-transcript > div.cx-message-group > div.cx-message" creates a dependency on the HTML node type and structure. If any changes are made to WebChat's HTML structure, this CSS selector will break. Use the smallest necessary specificity in your selectors and try to use class names only. <br/><br/>
Be careful not to modify the structure and functionality of the CSS when you make your changes. Otherwise, it won't work right.<br/><br/>
In particular, you must avoid setting the following CSS properties: height, width, thickness, size, and visibility; or any other properties that change the structure of widgets. These properties are not supported. Changing them can break widget stability and usability.|3}}{{NoteFormat|By default, the Widgets CSS uses the Roboto font, available at https://fonts.google.com/}}
|Status=No
}}{{Section
|sectionHeading=Register a theme with Genesys Widgets
|anchor=regtheme
|alignment=Vertical
|structuredtext=The following example shows how to register themes in the Genesys Widgets configuration.
<source lang="javascript">window._genesys.widgets.main.themes = {
"blue": "cx-theme-blue"
};
</source>
The name:value pair used here consists of a key ("blue") and the theme's CSS classname ("cx-theme-blue"). You can add as many themes to this list as you need.

Use a theme's key to make it the active theme:
<source lang="javascript">window._genesys.widgets.main.theme = "blue";
// OR
window._genesys.widgets.bus.command("App.setTheme", {theme: "blue"});
</source>
|Status=No
}}{{Section
|sectionHeading=Change the appearance of a specific widget
|anchor=changeappear
|alignment=Vertical
|structuredtext=You can specify specific widgets—and even specific elements within a widget—by appending the widget's CSS classname to the theme classname.

The following example shows how to extend the '''cx-theme-blue''' class with a widget-specific entry that makes the WebChat widget's background color a darker shade.

<source lang="css">
.cx-widget.cx-theme-blue, .cx-widget .cx-container{

color: #FDFDFD;
background: #1e5799;
}

.cx-widget.cx-theme-blue *{

border-color: #7DB9E8;
}

.cx-widget.cx-theme-blue.cx-webchat, .cx-widget.cx-theme-blue .cx-webchat{

background: #225897;
}
</source>

[[File:GWCCustomize SpecificTheme01.png|500x500px]]

{{NoteFormat|Notice the dual CSS selector used when specifying the widget. This is required to make sure your styles always apply properly.}}

'''Widget-Specific and Element-Specific'''

The next example shows how to extend the "cx-theme-blue" class with a widget- and element-specific entry that changes the background color of the input fields within the WebChat widget to a light shade of blue.

<source lang="css">
.cx-widget.cx-theme-blue, .cx-widget .cx-container{

color: #FDFDFD;
background: #1e5799;
}

.cx-widget.cx-theme-blue *{

border-color: #7DB9E8;
}

.cx-widget.cx-theme-blue.cx-webchat, .cx-widget.cx-theme-blue .cx-webchat{

background: #225897; // Darker Shade
}

.cx-widget.cx-theme-blue.cx-webchat .form input, .cx-widget.cx-theme-blue .cx-webchat .form input{

background: #DCF5FF; // Lighter Shade
}

</source>
[[File:GWCCustomize SpecificTheme02.png|500x500px]]
|Status=No
}}{{Section
|sectionHeading=Change the layout and structure of a widget
|anchor=changelayout
|alignment=Vertical
|structuredtext=You can only use themes to customize a limited set of styles for your version of Genesys Widgets. To create an alternate layout of your own design, disable the widget you want to customize and use the provided service plugins to build your own replacement.

'''Choosing Which Plugins to Load'''

Refer to the '''plugins''' configuration option here: {{Link-SomewhereInThisVersion|manual=SDK|topic=App-combined|anchor=config|display text=app configuration}}

'''Service Plugins'''

Service plugins provide a high-level API for quickly integrating a UI with backend services. Each widget is matched with a corresponding service plugin. This separation allows for advanced integrations.

*{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|display text=WebChatService}}
*{{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|display text=CallbackService}}

{{NoteFormat|Genesys does not support changes to the layout of the official Genesys Widgets, as your changes can be overwritten when you upgrade to a newer version of Genesys Widgets.|3}}
|Status=No
}}{{Section
|sectionHeading=Change fonts
|anchor=changefont
|alignment=Vertical
|structuredtext=By default, Genesys Widgets downloads and uses Google's Roboto font. Use the following CSS to specify a different font:

<source lang="javascript">.cx-widget{ font-family: name-of-font-here; }</source>

The font you choose here will be applied to all of the Genesys Widgets.
===Disable Roboto font download===
To prevent Google's Roboto font file from being downloaded at startup, set the '''main.downloadGoogleFont''' configuration option to '''false''':

<source lang="javascript">_genesys.widgets.main.downloadGoogleFont = false;</source>

If this option is set to '''true''', Google's Roboto font will be downloaded. The default value is ''true''.

{{NoteFormat|Use this configuration option if you have security concerns about including fonts from third-party sources, to optimize your page load time, or if you already include Roboto on your website.}}

===Change font size===
By default, the font size in Genesys Widgets content is in ''em'' units. This is to support accessibility guidelines allowing font size to scale as needed when zoomed in or out based on the screen size. For normal text, the font size value is '''0.75em''' and can vary for other text contents.{{NoteFormat|Since these are relative units, the actual value is derived from the font size of the parent page body. A base font size can be defined on the .cx-widget class in em units to change font size, which allows Widgets to calculate internal font size using this value.|}}<br />
|Status=No
}}{{Section
|sectionHeading=Icons
|anchor=icons
|alignment=Vertical
|structuredtext=Genesys Widgets are provided in SVG format, which means you can apply color fills and other SVG CSS properties when you use them. SVG also supports the highest possible rendering quality on all devices, regardless of the zoom level or resolution. You can scale the icons to fit any container; use them either inline or as blocks; and animate their orientation, colors, and other styling.

You can also use the Genesys icons in your own custom extensions, which allows them to match the look and feel of the default Genesys widgets. Here are some of the things you can do with them:

*Create a custom launcher button for chat, using the chat icon
*Create a custom widget with your choice of icon in the title bar
*Mix icons right in with your text, so you can refer to your widgets graphically

Genesys Widgets includes two sets of icons:

*The Multi-tone icon set uses several layers and colors per icon
*The Outline icon set takes a minimalist approach to both design and color

You can use these icons in any way that works for you, but please note that you can't customize or replace the icons.

===How to use icons===
====Automatic HTML injection====
Specify which icons you want and where you want them by applying the CSS '''cx-icon''' class and '''data-icon''' attribute to the appropriate elements:
<nowiki><div id="your-element" data-origid="your-element" class="cx-icon" data-icon="chat"></nowiki>
...SVG icon will be inserted here
<nowiki></div></nowiki>
When you pass the element into the '''CXCommon.populateAllPlaceholders( $("#your-element") )''' function—as a jQuery-wrapped set or an HTML string—Genesys Widgets inserts the appropriate SVG icons and returns the HTML to you.

====Fetching SVG icon markup====
You can also fetch the markup for each SVG icon manually:
<source lang="html4strict">
$("#your-element").append( CXCommon.Generate.Icon("chat") );
</source>
===Multi-tone icon set===
[[File:Multi-icon-set1.png|600px]][[File:Multi-icon-set2.png|600px]][[File:Multi-icon-set3.png|600px]]
===Outline icon set===
[[File:Outline-icon-set1.png|600px]][[File:Outline-icon-set2.png|600px]][[File:Outline-icon-set3.png|600px]]
|Status=No
}}
}}

@@ Line 235: / Line 235: @@
 |anchor=changefont
 |alignment=Vertical
-|structuredtext=By default, Genesys Widgets downloads and uses Google's Roboto font hosted in Genesys Infrastructure. Please choose the nearest or appropriate region URL specified [[Draft:WID/Current/Developer/GWCDeployment#GenesysWebFonts|here]] or any other URL to download the roboto.css according to your preference and configure it through the [[Draft:WID/Current/SDK/App-combined#config|googleFontUrl option]].
+|structuredtext=By default, Genesys Widgets downloads and uses Google's Roboto font hosted in Genesys Infrastructure. Please choose the nearest or appropriate region URL specified {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCDeployment|anchor=GenesysWebFonts|display text=here}} or any other URL to download the roboto.css according to your preference and configure it through the {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=App-combined|display text=googleFontUrl option}}.
 <source lang="javascript">window._genesys = {
@@ Line 287: / Line 287: @@
 ====Automatic HTML injection====
 Specify which icons you want and where you want them by applying the CSS '''cx-icon''' class and '''data-icon''' attribute to the appropriate elements:
-  <nowiki><div id="your-element" data-origID="your-element"  data-origID="your-element"  data-origID="your-element"  data-origid="your-element" class="cx-icon" data-icon="chat"></nowiki>
+  <nowiki><div id="your-element" data-origID="your-element"  data-origID="your-element"  data-origID="your-element"  data-origID="your-element"  data-origid="your-element" class="cx-icon" data-icon="chat"></nowiki>
    ...SVG icon will be inserted here
    <nowiki></div></nowiki>

@@ Line 235: / Line 235: @@
 |anchor=changefont
 |alignment=Vertical
-|structuredtext=By default, Genesys Widgets downloads and uses Google's Roboto font. Use the following CSS to specify a different font:
+|structuredtext=By default, Genesys Widgets downloads and uses Google's Roboto font hosted in Genesys Infrastructure. Please choose the nearest or appropriate region URL specified [[Draft:WID/Current/Developer/GWCDeployment#GenesysWebFonts|here]] or any other URL to download the roboto.css according to your preference and configure it through the [[Draft:WID/Current/SDK/App-combined#config|googleFontUrl option]].
 <source lang="javascript">.cx-widget{ font-family: name-of-font-here; }</source>
@@ Line 241: / Line 254: @@
 The font you choose here will be applied to all of the Genesys Widgets.
 ===Disable Roboto font download===
-To prevent Google's Roboto font file from being downloaded at startup, set the '''main.downloadGoogleFont''' configuration option to '''false''':
+To prevent Google's Roboto font file from being downloaded at startup from Genesys Infrastructure, set the '''main.downloadGoogleFont''' configuration option to '''false''':
 <source lang="javascript">_genesys.widgets.main.downloadGoogleFont = false;</source>
-If this option is set to '''true''', Google's Roboto font will be downloaded. The default value is ''true''.
+If this option is set to '''true''', Google's Roboto font will be downloaded from Genesys Infrastructure. The default value is ''true''.
 {{NoteFormat|Use this configuration option if you have security concerns about including fonts from third-party sources, to optimize your page load time, or if you already include Roboto on your website.}}
@@ Line 274: / Line 287: @@
 ====Automatic HTML injection====
 Specify which icons you want and where you want them by applying the CSS '''cx-icon''' class and '''data-icon''' attribute to the appropriate elements:
-  <nowiki><div id="your-element" data-origID="your-element"  data-origid="your-element" class="cx-icon" data-icon="chat"></nowiki>
+  <nowiki><div id="your-element" data-origID="your-element"  data-origID="your-element"  data-origID="your-element"  data-origid="your-element" class="cx-icon" data-icon="chat"></nowiki>
    ...SVG icon will be inserted here
    <nowiki></div></nowiki>