5 Convergence UI Customization Examples

This chapter provides several examples for customizing the UI in Oracle Communications Convergence.

Customization Requirements

To perform any Convergence customization, you should have expert knowledge in dojo and knowledge of UI customization. For more information on general Convergence customization, see "Technical Overview".

Nearly all customization examples require the same setup and preparation.

You start by verifying that the c11n_Home directory exists. If it does not exist, create it.

See "Customization Directory Structure" for more information.
Next, you verify that customization is enabled in Convergence. If customization is disabled, enable it.

See "Enabling Customization in the Convergence Server" for more information.
When you have completed your customization, you must restart the GlassFish server for Convergence.

See Convergence System Administrator’s Guide for more information.

Modifying a Specific Theme

To modify a specific theme in your customization, you change a specific theme file as opposed to modifying theme_basic, which changes all themes:

In this example, a different logo is added to theme_blue.

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables theme customization (themeEnabled: true), i18n customization (i18nEnabled: true), and Javascript customization (jsEnabled: true) across all domains (module: "allDomain").

The following example shows a config.js.

dojo.provide("c11n.config");
c11n.config = {

        // allDomain configuration
        allDomain: {
                module: "allDomain", // module name
                themeEnabled: true, // true if theme is customized
                i18nEnabled: true, // true if i18n is customized
                jsEnabled: true // true if js is customized

                // the last entry must not end with comma
        },
}

In c11n_Home/allDomain/themes, create or modify customize.js to include the following code:
```
iwc.api.modifyThemeValues("theme_blue", "../c11n/allDomain/themes/blue/theme.json");
```

In c11n_Home/allDomain/themes/blue, edit theme.json with the location of the logo, the logo's width, and height:

{
logoBackground: 'transparent url("../c11n/allDomain/themes/blue/images/logo.png") no-repeat center center',
logoWidth: "180px"
mastheadHeight: "40px"
}

In /themes/blue/images/, add a new logo.png file with black background
Restart the GlassFish server and clear the browser cache to see the changes.

The blue theme now contains a logo with a black background.

Hiding a Single Theme

To hide the blue theme, edit the /themes/customize.js file to include the following code:

iwc.api.hideTheme("theme_blue");

When you remove the blue theme, the theme selector displays all the included themes except for the blue theme:

Creating a New Theme

The Convergence UI banner uses the iwc.api.addTheme to add themes to the theme selector. You can add themes to the theme selector.

The following example adds a purple theme to the theme selector:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/nls/
/c11n_Home/allDomain/themes/purple/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

The following example shows a config.js.

dojo.provide("c11n.config");
c11n.config = {

        // allDomain configuration
        allDomain: {
                module: "allDomain", // module name
                themeEnabled: true, // true if theme is customized
                i18nEnabled: true, // true if i18n is customized
                jsEnabled: true // true if js is customized

                // the last entry must not end with comma
        },
}

In c11n_Home/allDomain/themes, create or modify customize.js to include the following code:

// Adding a new theme
iwc.api.addTheme({
  name: 'theme_purple', // name must be unique
  parentTheme: "theme_basic", // must use a theme_basic theme
  configPath: "../c11n/allDomain/themes/purple/theme.json",
  thumbnailColor: "#C290D6"
  visible: true
});

You can also add a background image, you do so by adding a link to that image in the thumbnailColor parameter. For example:

// Adding a new theme
iwc.api.addTheme({
  name: 'theme_purple',  // name must be unique
  parentTheme: "theme_basic", // must use a theme_basic theme
  configPath: "../c11n/allDomain/themes/purple/theme.json",
  thumbnailColor: '#C290D6 url("../c11n/allDomain/themes/purple/images/logo.png")'
  visible: true
});

In c11n_Home/allDomain/nls, add the code for the customized theme to resources.js above last: "".
```
{
    ...
    theme_purple : "Purple",
    last: ""
}
```
Restart the GlassFish server and clear the browser cache to see the changes.

The new Purple theme appears as the last theme in the theme selector.

Making a Newly Created Theme the Default

This example assumes you have already created a new theme called Purple. See "Creating a New Theme" for more information.

To make the Purple them the default theme in Convergence:

Use the iwcadmin command to set the Purple theme (theme_purple) as the default:
```
iwcadmin -o user.common.theme -v theme_purple
```
For more information about the user preferences or the Convergence command-line utility, see Convergence System Administrator’s Guide.
Restart GlassFish server and clear the browser cache to see the change.

The default theme appears by default for all users who have not selected a specific theme.

Adding a Logo to All Themes

The most common theme customization scenario is adding a logo to all existing themes. In the following example, you can add your own logo.png to the set of themes found in the c11n_sample/ directory.

To add a logo to all themes in your customization:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/themes/basic/images/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

The following example shows a config.js.

dojo.provide("c11n.config");
c11n.config = {

        // allDomain configuration
        allDomain: {
                module: "allDomain", // module name
                themeEnabled: true, // true if theme is customized
                i18nEnabled: true, // true if i18n is customized
                jsEnabled: true // true if js is customized

                // the last entry must not end with comma
        },
}

In c11n_Home/allDomain/themes, create or modify customize.js where the user must enable modifications for a specific theme using iwc.api.modifyThemeValues. In this scenario, it is the parent theme for the provided themes.
```
iwc.api.modifyThemeValues("theme_basic", "../c11n/allDomain/themes/basic/theme.json");
```

In c11n_Home/allDomain/themes/basic, edit theme.json with the location of the logo, the logo's width, and height:

{
logoBackground: 'transparent url("../c11n/allDomain/themes/basic/images/logo.png") no-repeat center center',
logoWidth: "180px",
mastheadHeight: "40px"
}

Replace the logo.png file in the /themes/basic/images/ directory with your logo.
Restart the GlassFish server and clear the browser cache to see the changes.

Adding a Logo to the Right Side of the Banner

This example explains how to add a logo to the right side of the banner for all domains in the deployment.

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/widget/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization file) to include the following code:

dojo.provide("c11n.allDomain.js.customize");
 
//Enable the Banner.js to add the logo to the right of the banner.
dojo.require("c11n.allDomain.js.widget.Banner");

In c11n_Home/allDomain/js/widget, create Banner.js (the file that adds the logo to the right side of the banner). In Banner.js, do the following:

The float:right parameter aligns the dom node to the right side of the banner.
Change the style "height" from "40px" to the height of the logo space.
change the style "width" from "138px" to the width of the logo space.
change the style "background" URL from 'url("../c11n/allDomain/layout/images/logo.gif")', to the logo location of the logo you want to add to the banner. The URL should be relative to main.html.

dojo.provide("c11n.allDomain.js.widget.Banner");
dojo.require("iwc.widget.Banner");
 
dojo.declare("iwc.widget.Banner", iwc.widget.Banner,
  {
  // Overwriting iwc.widget.Banner postCreate
  // Purpose: Add additional Dom Node for logo on the right 
  // How to Style: Modify newLogoProperties to provide inline styles
  postCreate: function(){
    //console.debug(this.id+"::postCreate");
    this.inherited(arguments);
 
    // new Logo dom node properties
    var newLogoProperties = {
    "style": {
        "float": 'right',
        "height": '40px',
        "width": '138px',
        "background": 'transparent url("../c11n/allDomain/layout/images/smallOracleLogo.gif") no-repeat center center'
     }
      };
 
    // Create new Dom Node before everything else
    var newLogoDomNode = dojo.create("div", newLogoProperties, this.domNode,"first");
  }
});

Restart the GlassFish server and clear the browser cache to see the change.

Figure 5-1 shows the logo on the right side of an example banner.

Figure 5-1 Customized Banner with Logo on Right Side

Making the Banner Logo a Clickable Link

This example assumes you have already added a logo to all themes. See "Adding a Logo to All Themes" for more information.

This example explains how to make a logo in the banner a clickable link in all domains in the deployment.

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/widget/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:

dojo.provide("c11n.allDomain.js.customize");

//Enable the Banner.js to make the logo in a clickable link in the banner .
dojo.require("c11n.allDomain.js.widget.Banner");

In c11n_Home/allDomain/js/widget, create the JavaScript file (Banner.js) to make the logo in a clickable link in the banner. Using either of the following postCreate functions, and optionally, either of the following logoOnClick functions:

The first postCreate function makes the logo clickable in the banner.
The second postCreate function (which is commented out in the example) makes the mouse pointer clickable when it hovers over the logos. Uncomment the function to make the mouse pointer clickable when it hovers over logos. Comment out the first postCreate function.
The first logoOnClick function creates an alert when the logo has been clicked.

The second logoOnClick function (which is commented out in the example) links the logo to a URL. Uncomment the function to link the logo to a URL. Comment out the first logoOnClick function.

dojo.provide("c11n.allDomain.js.widget.Banner");
dojo.require("iwc.widget.Banner");

dojo.declare("iwc.widget.Banner", iwc.widget.Banner, {
       //postCreate #1: makes logo clickable
       postCreate: function() {
               this.inherited(arguments);

               // find the logo element
               var elem = dojo.query(".Banner-Logo", this.domNode);
               if (elem.length == 1) {
                       this.connect(elem[0], "onclick", "logoOnClick");
               }
       },

       //postCreate #2: makes the mouse pointer clickable when hovering over links. Comment out the postCreate #1 function and uncomment the following function:
       //postCreate: function() {
       //         this.inherited(arguments);
       //       
       //         var elem = dojo.query(".Banner-Logo", this.domNode);  // find the logo element
       //         if (elem.length == 1) {
       //                 elem[0].style.cursor = "pointer";    // change the cursor to pointer
       //                 this.connect(elem[0], "onclick", "logoOnClick");
       //         }
       // },

       // logoOnClick #1: creates a clickable logo
       logoOnClick: function() {
               alert("your logo is clicked!");
       },

       // logoOnClick #2: links the logo to a URL. Comment out the logoOnClick #1 function and uncomment the following function, where http://www.example.com is the URL to which the logo is linked:
       // logoOnClick: function() {
       //        window.open("http://www.example.com");
       // },

       last: ""

});

Restart the GlassFish server and clear the browser cache to see the change.

Handling Large Logos in Gradient Themes

When adding a logo to a theme, the logo's height typically does not exceed 40px in height. If you choose to add a logo that is larger than 40px, the banner might not display properly in a gradient image theme. Themes with gradient images include:

theme_yellow
theme_dark_blue
theme_light_blue
theme_green
theme_grey

Themes that use solid color (for example, theme_blue, theme_orange) do not need to be modified for larger logos since the color will fill the entire height of the banner. However, themes with gradient images require adding a different image to fill the entire height of the banner when a larger logo is inserted. The theme needs to be customized to use the larger background image for the banner.

Figure 5-2 shows an 80px logo on top of a 40px gradient theme.

Figure 5-2 Large Logo on a Gradient Theme Not Displaying Properly

Re-Sized Gradient Banner Samples

Use the following banner samples when manipulating large logos (>40px) in gradient themes. The banner image files are available with the Convergence software on the Oracle software delivery site.

Yellow theme sample (yellow_masthead.png)
Dark blue theme sample (dark_blue_masthead.png)
Light blue theme sample (light_bue_masthead.png)
Green theme sample (green_masthead.png)
Grey them sample (grey_masthead.png)

Figure 5-3 Large Gradient Theme Samples

Customizing the Dark Blue Theme

To handle large logos in gradient themes, you must create a different image to be used for the mastheadBackground which fits the desired height for each affected theme. This method ensures a properly fitted image for the larger icon. To add the resized background image to the gradient theme:

Copy masthead.png into the c11n_Home/allDomain/themes/dark_blue/images/ directory.
Follow the example in the section "Modifying a Specific Theme".
Set the mastheadBackground property to use the new image in the dark blue theme configuration (theme.json) file in the c11n_Home/allDomain/themes/dark_blue/ directory:
```
mastheadBackground: "#7291B0 url('../c11n/allDomain/themes/dark_blue/images/masthead.png') repeat-x center center"
```
Refresh your web browser.
If necessary, refine the image so to create the right look and feel.

Adding and Removing Fonts from the Editor Menu

To add and remove fonts from the editor menu:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
```
dojo.provide("c11n.allDomain.js.customize");
 
dojo.require("c11n.allDomain.js.editor.plugins.FontChoice");
```

In c11n_Home/allDomain/js/editor/plugins, create the file (FontChoice.js) that adds the new font to the editor menu.

In the following example, the new font is a Japanese font named Ms_pgothic:

dojo.provide("c11n.allDomain.js.editor.plugins.FontChoice");
 
   dojo.require("iwc.editor.plugins.FontChoice");
 
   dojo.declare("iwc.editor.plugins.FontChoice",
    iwc.editor.plugins.FontChoice,
      {
           custom: {
                    fontName: [
                              "Ms pgothic",           // sans-serif
                              "Arial",                // sans-serif
                              "Comic Sans MS",        // cursive
                              "Courier",              // monospace
                              "Courier New",          // monospace
                              "Georgia",              // transitional-serif
                              "Helvetica",            // sans-serif
                              "Lucida Console",       // sans-serif
                              "Tahoma",               //sans-serif
                              "Times",                // serif
                              "Times New Roman",      // serif
                              "Trebuchet MS",         // sans-serif
                              "Verdana"               // sans-serif
                               ],
                     fontSize: [1,2,3,4,5,6,7] // sizes according to the old HTML FONT SIZE
                     },
          last: ""
  });

To translate the font name "ms pgothic" in the editor font choice menu, see: Translating the Font Name "ms pgothic" in the Editor Font Choice menu.

Restart the GlassFish server and clear the browser cache to see the change.

Changing an Icon in the Service Selector

This example describes how to change the Mail, Address Book, Instant Messaging, or Options icon in the service selector for all domains in your deployment.

Figure 5-4 shows the appearance of the default icon sprite above the default service selector icons.

Figure 5-4 Original Icon Sprite and Service Selector Icons

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/
/c11n_Home/allDomain/layout/css
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:

dojo.provide("c11n.allDomain.js.customize");
 
// Load Customized CSS File Helper
var loadCustomizedCssFile = function(url, id) {
        if (!id){
                id = url.replace(/\.\./gm, "").replace(/\//gm, "_").replace(/\./gm, "_");
        }
        var link = window.document.getElementById(id);
        if (! link) {
                link = window.document.createElement("link");
                link.setAttribute("id", id);
                link.setAttribute("type", "text/css");
                link.setAttribute("rel", "stylesheet");
                var head = window.document.getElementsByTagName("head")[0];
                head.appendChild(link);
        }
 
        link.setAttribute("href", url + "?" + djConfig.cacheBust);
}
 
// Load customized css file c11n_icons
loadCustomizedCssFile("../c11n/allDomain/layout/css/c11n_icons.css");

In c11n_Home/allDomain/layout/images, add new icons or icon sprite (a single image that contains multiple icons).

In c11n_Home/allDomain/layout/css, create clln_icons.css to point to the new images.

In the following example, the referenced image sprite is called new_services_icons_sprite.png:

/* Service Icons */
/* Mail Service Icon */
 .mail .serviceIcon {
  background-image: url("../images/new_services_icons_sprite.png");
  background-repeat: no-repeat;
  background-position: 0px center;
  background-color: transparent;
}
 
/* Calendar Service Icon */
 .calendar .serviceIcon {
  background-image: url("../images/new_services_icons_sprite.png");
  background-repeat: no-repeat;
  background-position: -60px center;
  background-color: transparent;
}
 
/* Address Book Service Icon */
 .abs .serviceIcon {
  background-image: url("../images/new_services_icons_sprite.png");
  background-repeat: no-repeat;
  background-position: -30px center;
  background-color: transparent;
}
 
/* Options Service Icon */
 .options .serviceIcon {
  background-image: url("../images/new_services_icons_sprite.png");
  background-repeat: no-repeat;
  background-position: -88px center;
  background-color: transparent;
}

To change just the Mail service selector icon, you can still use an icon sprite, only modifying the Mail service in the c11n_icons.css file:

/* Service Icons */
/* Mail Service Icon */
 .mail .serviceIcon {
  background-image: url("../images/new_services_icons_sprite.png");
  background-repeat: no-repeat;
  background-position: 0px center;
  background-color: transparent;
}

To use an individual image instead of an image sprite, point the background-image to the icon image of the individual service. For example, in the Mail service:

/* Service Icons */
/* Mail Service Icon */
 .mail .serviceIcon {
  background-image: url("../images/new_mail_service_icon.png");
  background-repeat: no-repeat;
  background-position: 0px center;
  background-color: transparent;
}

Restart the GlassFish server and clear the browser cache to see the change.

Figure 5-5 shows a new icon sprite and new service selector icons.

Figure 5-5 Example Updated Icon Sprite and Service Selector Icons

Displaying and Printing the Japanese Yen Symbol

Since Default.css is part of the Convergence-based codes as opposed to the c11n directory, any upgrade updates Default.css and overrides your customization. Therefore, you must re-apply these customization changes after each Convergence upgrade.

To display the Yen symbol in an email subject, calendar title, and calendar description:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/
/c11n_Home/allDomain/layout/css
```
In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
```
loadCustomizedCssFile("../c11n/allDomain/layout/css/c11n.css");
```

In c11n_Home/allDomain/js, modify customize.js and add or uncomment the following code:

var loadCustomizedCssFile = function(url, id) {
        if (!id){
                id = url.replace(/\.\./gm, "").replace(/\//gm, "_").replace(/\./gm, "_");
        }
        var link = window.document.getElementById(id);
        if (! link) {
                link = window.document.createElement("link");
                link.setAttribute("id", id);
                link.setAttribute("type", "text/css");
                link.setAttribute("rel", "stylesheet");
                var head = window.document.getElementsByTagName("head")[0];
                head.appendChild(link);
        }
 
        link.setAttribute("href", url + "?" + djConfig.cacheBust);
}
loadCustomizedCssFile("../c11n/allDomain/layout/css/c11n.css")

In c11n_Home/allDomain/layout/css, edit c11n.css and remove or comment the following code:

body {
           font-family: "ms pgothic", arial, helvetica, sans-serif;
        }
 
    .dj_ie body * {
           font-family: "ms pgothic", arial, helvetica, sans-serif;
        }
 
    .dj_ie .FormSimpleTextarea .FormSimpleTextarea-inputText {
           font-family: "ms pgothic", arial, helvetica, sans-serif !important;
        }

Restart the GlassFish server and clear the browser cache to see the change.

To display the Yen symbol in the email preview pane:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.

In c11n_Home, verify that the following directories exist. If they do not exist, create them.

c11n_Home/allDomain/js/editor
c11n_Home/allDomain/js/widget/mail
c11n_Home/allDomain/layout/css/editor

In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js/widget/mail, create IframeMessagePane.js and add the following code:

dojo.provide("c11n.allDomain.js.widget.mail.IframeMessagePane");
 
     dojo.require("c11n.allDomain.js.widget.mail.IframeMessagePane");
 
     iwc.widget.mail.IframeMessagePane.prototype.customCssUrl =
        "/iwc_static/c11n/allDomain/layout/css/MessagePane.css";

In c11n_Home/allDomain/layout/css, create or modify MessagePane.css and add the following style:

.MailMessagePane body {
          font-family: "ms pgothic", arial, helvetica, sans-serif;
    }

In c11n_Home/allDomain/js/editor, create Editor.js and add the following code:

dojo.provide("c11n.allDomain.js.editor.Editor");
 
     dojo.require("iwc.editor.Editor");
 
     iwc.editor.Editor.prototype.customCssUrl =
        "/iwc_static/c11n/allDomain/layout/css/Editor.css";

In c11n_Home/allDomain/layout/css/Editor, create Editor.css and add the following style:
```
body {
         font-family: "ms pgothic", arial, helvetica, sans-serif;
   }
```

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:

dojo.require("c11n.allDomain.js.editor.Editor");
   dojo.require("c11n.allDomain.js.editor.plugins.FontChoice");
   dojo.require("c11n.allDomain.js.widget.mail.IframeMessagePane");

Restart the GlassFish server and clear the browser cache to see the change.

To add a new font to the editor font menu:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/editor/editor/plugins
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
```
dojo.provide("c11n.allDomain.js.customize");
 
dojo.require("c11n.allDomain.js.editor.plugins.FontChoice");
```

In c11n_Home/allDomain/js/editor/plugins, create or modify FontChoice.js with the following sample:

dojo.provide("c11n.allDomain.js.editor.plugins.FontChoice");
 
   dojo.require("iwc.editor.plugins.FontChoice");
 
   dojo.declare("iwc.editor.plugins.FontChoice",
    iwc.editor.plugins.FontChoice,
      {
           custom: {
                    fontName: [
                              "Ms pgothic",           // sans-serif
                              "Arial",                // sans-serif
                              "Comic Sans MS",        // cursive
                              "Courier",              // monospace
                              "Courier New",          // monospace
                              "Georgia",              // transitional-serif
                              "Helvetica",            // sans-serif
                              "Lucida Console",       // sans-serif
                              "Tahoma",               //sans-serif
                              "Times",                // serif
                              "Times New Roman",      // serif
                              "Trebuchet MS",         // sans-serif
                              "Verdana"               // sans-serif
                               ],
                     fontSize: [1,2,3,4,5,6,7] // sizes according to the old HTML FONT SIZE
                     },
          last: ""
  });

Restart the GlassFish server and clear the browser cache to see the change.

To translate the ms pgothic font name in the editor font menu:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/nls/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables i18n customization (i18nEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {

        // allDomain configuration
        allDomain: {
                module: "allDomain", // module name
                themeEnabled: false, // true if theme is customized
                i18nEnabled: true, // true if i18n is customized
                jsEnabled: false // true if js is customized

                // the last entry must not end with comma
        },
}

In c11n_Home/allDomain/nls, edit resources.js and add the following code:
```
{
       "ms pgothic": "localized_font_name",
        last: ""
   }
```
Where localized_font_name is the name you give the font.
Restart the GlassFish server and clear the browser cache to see the change.

To print the Yen Symbol:

In Convergence_Domain/docroot/iwc_static/layout/css, edit Default.css by adding the following lines at the end of the file:

body {
     font-family: "ms pgothic", arial, helvetica, sans-serif;
   }
 
   .dj_ie body * {
     font-family: "ms pgothic", arial, helvetica, sans-serif;
   }
 
   .dj_ie .FormSimpleTextarea .FormSimpleTextarea-inputText {
     font-family: "ms pgothic", arial, helvetica, sans-serif !important;
   }

Modifying the Document Title and the Convergence Text in the Banner

This example provides an easy method to modify the Convergence text in the document title and on the banner in the main.html page.

You can only do this type of customization on a per domain basis. In other words, doing such modifications will impact the single domain you're modifying, not all of your domains.

To customize the theme and banner for all domains, or to do extensive theme and banner customization (such as adding new themes, new colors, or logos), see "Working with the Convergence UI".

Figure 5-6 shows the document title and the Convergence text in the banner before the customization being applied.

Figure 5-6 Document Title and Convergence Text Before Customization

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/mydomain_org/js/widget/
/c11n_Home/mydomain_org/nls/
```
In this example, mydomain_org is the single domain that's being modified.
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables i18n customization (i18nEnabled: true) for the mydomain_org domain (module: "mydomain_org").

dojo.provide("c11n.config");
c11n.config = {

        // allDomain configuration
        allDomain: {
            ...
        },

        // mydomain_org configuration
        mydomain_org: {
                module: "mydomain_org", // module name
                themeEnabled: false, // true if theme is customized
                i18nEnabled: true, // true if i18n is customized
                jsEnabled: false // true if js is customized

                // the last entry must not end with comma

        }
}

In c11n_Home/mydomain_org/nls, create resources.js that specifies the document title text:
```
{
       login_product_name: "mydomain.org",
       last: ""
}
```
Restart the GlassFish server and clear the browser cache to see the change.

Figure 5-7 shows the document title and the Convergence text in the banner after the customization is applied.

Figure 5-7 Document Title and Convergence Text After Customization

Changing Names and Labels in the Convergence UI

You can change the labels for icons, tabs, menus, and other elements in the Convergence UI. You create your own names for these UI widgets by changing their definitions in the resources.js file.

Moreover, the label or name can be customized in a particular domain or can be applied to all domains. Use the allDomain directory to apply to all domains in your deployment.

The following steps outline how to customize the Convergence UI to display a new label or name for a widget:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/nls/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables i18n customization (i18nEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: true, // true if i18n is customized
               jsEnabled: false // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/nls, create a default resource file named resources.js.

This customized resources file extends the default label values with the new, custom values.
In resources.js, add a text string that identifies the UI widget for which you want a customized label, and add the new label in double quotes. For example:
```
{
  compose_tab: "New Mail Message",
  prius_green_theme: "Prius Green"
}
```
In this example, the text New Mail Message replaces the default text [No Subject] when the user composes a new email.

Add a new text line for each widget which will have a custom label.

At run time, the default resources.js file in the default directory is loaded first, followed by the customized resources.js file. Thus, Convergence first loads the standard values (including UI widget labels) in the default resources file; it then overrides those values with any customizations in this resources file.
To change a label in a specific language supported by Convergence, edit the resources.js file in the directory for that language.

For example, to provide a customized label in French, add the new text in the resources.js file in the subdirectory containing the French version:
```
c11n_Home/Domain/nls/fr/resources.js
```

Removing or Changing the Product Name on the Mail HTML Page

This example outlines how to remove or change the product name from Convergence in the Banner. As with other Convergence elements, you can customize the product name in a particular domain, or it can be applied to all domains. The following example uses the allDomain directory to apply the product name change to all domains in the deployment.

Figure 5-8 shows the default product name in the banner.

Figure 5-8 Default Product Name in Banner

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/nls/
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables i18n customization (i18nEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: true, // true if i18n is customized
               jsEnabled: false // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/nls, create or modify resources.js and add the following code:
```
{
...
 login_product_name: "Customized Convergence",
 
 last: ""
}
```
Figure 5-9 shows the updated product name.

Figure 5-9 Customized Product Name in Banner and Web Browser

You can remove the product name from the banner completely if you leave an empty string for the login_product_name attribute in resources.js.
```
{
 ...
 login_product_name: "",
 
 last: ""
}
```
However, without a product name, your web browser may display the host name or IP address in the address bar, as shown in Figure 5-10.

Figure 5-10 Product Name Removed from Banner
Restart the GlassFish server and clear the browser cache to see the change.

Displaying a Password Policy in the Convergence UI

When changing the Convergence UI password, a user might need information on your site's password policy (the rules designed to enhance security by employing strong passwords).

To display your password policy in Convergence:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/option
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
```
dojo.provide("c11n.allDomain.js.customize");

dojo.require("c11n.allDomain.js.widget.option.Password");
```

In c11n_Home/allDomain/js/option, create or modify Password.js in which you add the password policy information on the Change Password page:

dojo.provide("c11n.allDomain.js.widget.option.Password");
dojo.require("iwc.widget.option.Password");
dojo.declare("iwc.widget.option.Password",
        iwc.widget.option.Password,
        {
                postCreate: function() {
                        this.inherited(arguments);
                        dojo.place("<h2>Password Policy:</h2><ul><li>Password must at least be 8 characters</li><li>Password must not be the same as the previous passwords</li></ul>", this.form.containerNode, "last");

                },

                last: ""
        }
);

Restart the GlassFish server and clear the browser cache to see the change.

Hiding the Quick Actions Menu

To hide the Quick Action menu in the Convergence UI from all domains:

Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
```
/c11n_Home/allDomain/js/widget
/c11n_Home/allDomain/layout/css
```
In c11n_Home, verify that config.js exists. If it does not exist, create it.

Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").

dojo.provide("c11n.config");
c11n.config = {
      
        // allDomain configuration
        allDomain: {
               module: "allDomain", // module name
               themeEnabled: false, // true if theme is customized
               i18nEnabled: false, // true if i18n is customized
               jsEnabled: true // true if js is customized
      
               // the last entry must not end with comma
      
        }
}

In c11n_Home/allDomain/js, create or modify customize.js and uncomment the following code:

var loadCustomizedCssFile = function(url, id) {
        if (!id){
                id = url.replace(/\.\./gm, "").replace(/\//gm, "_").replace(/\./gm, "_");
        }
        var link = window.document.getElementById(id);
        if (! link) {
                link = window.document.createElement("link");
                link.setAttribute("id", id);
                link.setAttribute("type", "text/css");
                link.setAttribute("rel", "stylesheet");
                var head = window.document.getElementsByTagName("head")[0];
                head.appendChild(link);
        }
 
        link.setAttribute("href", url + "?" + djConfig.cacheBust);
}
loadCustomizedCssFile("../c11n/allDomain/layout/css/c11n.css")

In c11n_Home/allDomain/layout/css, create or modify c11n.css to include the following code:
```
.QuickActions {
        display: none;
}
```
Restart the GlassFish server and clear the browser cache to see the change.