This guide explains how to customize the look and feel of Convergence. Although the product architecture permits an almost unlimited customization, this guide focuses on concepts, reference, examples, and explanations on how to perform the most commonly used customizations.
You can customize the Convergence UI, giving you the power to flexibly change the look and feel of the UI, control the services available, manage the display of advertisements, and change the UI in a variety of other ways. The Convergence UI is built specifically to support customization in the following ways:
Change the look and feel of the UI (implemented by customizing themes).
Brand the product as you'd like, altering the banner, text, icons, and so on.
Customize each domain in its own way.
Manage the display and location of advertisements.
Control which back-end services are made available to end users.
Localize the UI for languages in addition to those supported automatically by the product.
Integrate third-party applications, in addition to the standard services such as mail and calendar.
Table 1-1 lists the directory placeholders used in this guide:
Table 1-1 Convergence Directory Placeholders
| Placeholder | Description |
|---|---|
|
GlassFish_Home |
The directory in which the GlassFish Server software is installed. For example: /opt/glassfish3/glassfish. |
|
Convergence_Domain |
The directory containing the configuration files for the domain in which Convergence is Installed. Convergence_Domain is created in GlassFish_Home/domains. By default, Convergence_Domain is GlassFish_Home/domains/domain1. |
|
c11n_Home |
The directory in which all Convergence customization files and directories are created. c11n_Home must be Convergence_Domain/docroot/iwc_static/c11n. |
The following list briefly describes the main customization features provided by Convergence.
Theme
You can customize the look and feel of the UI by adding new themes. Each theme constitutes a set of icons, colors, fonts, and so on, which can be made available to end users through the banner of the UI. End users can then choose from a selection of site-defined themes.
Branding and Banner
You can change the brand and banner of the UI. In a hosted-domain environment, different banners and brands can be developed for each domain.
Tailoring Customizations for Individual Domains and End Users
You can control the level of customization. Most customization features can be targeted for
The entire site
A particular domain in a hosted-domain environment
A particular user or set of users, according to the way they are provisioned
For example, the theme, banners and other widgets, availability of services, and language can be customized for all three levels: site-wide, domain-specific, and individual end-users.
Controlling Which Services Are Available to End Users
You can enable and disable the services available to end users. For example, if you do not want users to use the calendar service, you can disable it. Services include mail, address book, calendar, and instant messaging; and so on.
Further, you can control the subset of services available to the whole site, to an individual domain, or to particular end users. See Convergence System Administrator’s Guide for more information.
Customizing Locales
You can make languages available to end users, in addition to those provided by Convergence, by adding your own language resources to the source code.
Integrating Advertisements Within Convergence
Convergence provides predefined advertisement space (which may include banner, text, images, and so on), which you can customize. You can specify the set of events (such as refreshing a page or reading a message) that trigger a call to the advertising API. Ads can be located in the top, bottom, left, and right panels of the UI, or at the top, bottom, left, and right of the email message viewer.
Integrating Third-Party Applications into Convergence
You can enable new services, in addition to the services provided by Convergence (mail, calendar, address book, and IM). A new service can be made available in the UI and integrated with the existing services. For example, you could add a tab in the UI and integrate an end user mailing list management application within Convergence.
Customization in Convergence requires different sets of skills, depending on which aspects of the UI you intend to customize. For theme customization, you should have expertise in CSS styling and graphic design.
For Javascript customization, you should have expertise in Javascript, dojo, and dijits. In addition, you will need to become familiar with the Convergence architecture and code.
For information about the Convergence architecture, directory structure, and the mapping of dojo declarations, see "Technical Overview".
Customizing Convergence for the first time consists of the following general steps:
Enabling the customization framework in Convergence.
See "Enabling the Customization Framework" for more information.
Creating one or more customizations.
See "Customizing Convergence" for more information.
Restarting the Glassfish server.
See "Restarting the GlassFish Server" for more information.
See "Possible Problems" for information about dealing with problems with your customizations.
Use the Convergence iwcadmin command-line utility to verify that Convergence customizations are not enabled (the default).
iwcadmin -o client.enablecustomization
The command line displays client.enablecustomization = false if customization is disabled.
Log in with Convergence client and view the user landing page.
Verify the iwc.log and (optionally) Firebug console output.
iwc.log: Check for "Client customization service is disabled for the deployment:"
PROTOCOL: WARN from com.sun.comms.client.protocol.delegate.agent.ClientOptionsAgent Thread httpSSLWorkerThread-9000-0 at 11:21:16,948 - client preferences not found for domain: sfbay.sun.com . . . PROTOCOL: INFO from com.sun.comms.client.entity.user.sun.CommsUser Thread httpSSLWorkerThread-9000-0 at 11:04:40,021 - Client customization service is disabled for the deployment
Firebug console: Check for no console entries about customization when it is off. Here is the console entry that would precede the customization service entry:
Scroll bar dimensions: Object w=13 h=13
You should not see:
Loading Service: Customization Object enabled=true displayName=Customization name=c11n
Enable customizations using the iwcadmin command:
iwcadmin -o client.enablecustomization -v true
Verify that the iwc_admin.log shows the change:
ADMIN: INFO from com.sun.comms.client.admin.mbeans.CommonMBean Thread RMI TCP Connection(7900)-129.145.185.117 at 11:49:40,804 - Value of config parameter client.enablecustomization modified to true
See "Enabling and Disabling Customization" for more information about enabling and disabling customizations for domains and users.
Customize Convergence, as outlined in this guide.
Customization changes do not take effect until you stop and start GlassFish server. If you log in to the Convergence client before restarting GlassFish server, the content remains the same.
Stop the GlassFish server.
Start the GlassFish server.
Log in to Convergence.
Verify that the iwc.log entry "Client customization service is disabled..." does not appear. The iwc.log entry previously noted should not appear. In the entry, look soon after "ClientOptionsAgent."
Verify that Firebug console contains the following:
Loading Service: Customization Object enabled=true displayName=Customization name=c11n
If the Convergence customization does not appear to be active after making the iwcadmin command change and restarting the GlassFish server, the most likely cause of problems is that GlassFish server did not fully stop. View the GlassFish server log for errors. For example, you can use the tail command on the log file referenced by the start script's output:
# tail -f /opt/glassfish3/glassfish/domains/domain1/logs/server.log . . . [#|2009-01-20T11:55:00.264-0800|INFO|sun-appserver9.1|javax.enterprise.system.core|_ThreadID=10;_ThreadName=main;|Application server startup complete.|#]
If this entry does not appear, GlassFish server has not started properly. If GlassFish server is still responding to web requests, the content will be the old content, and not reflect the enabled customization service.
The Convergence directory includes an example of customized code provided in the Convergence_Domain/docroot/iwc_static/c11n_sample directory. This directory is not live; that is, Convergence does not use the javascript and CSS files in this directory when it loads files at run time.
The clln_sample directory includes the following customization samples:
Themes
i18n samples
A mail.CreateMessage widget
helloConvergence service
Before you can use the customization example, the Convergence Server must be enabled for customization. Use the Convergence iwcadmin command-line utility, to set the client.enablecustomization parameter to true.
iwcadmin -o client.enablecustomization -v true
The customization directory, called c11n_Home, is Convergence_Domain/docroot/iwc_static/c11n. The custom files in c11n_Home extend the code base, overwriting the standard elements with the customized elements. Note the following information about c11n_Home:
c11n_Home does not exist by default. You must create it in Convergence_Domain/docroot/iwc_static and the directory name must be c11n
In c11n_Home, if config.js exists, customizations are booted based on how they are defined in this file.
For more information about the directory placeholders used in this guide, see Table 1-1, "Convergence Directory Placeholders".
The easiest way to create c11n_Home is to copy the sample customization directory and name it c11n. The sample customization directory is Convergence_Domain/docroot/iwc_static/c11n_sample. Then restart the GlassFish server so it can recognize and register the c11n_Home directory. After that, customization is ready to go.
The following example shows how to copy the c11n_sample to make c11n_Home:
cd /Convergence_Domain/docroot/iwc_static
cp -r c11n_sample c11n
You can also manually create c11n_Home.
The following list shows the structure of the /c11n_sample directory:
c11n_sample/
config.js (configuration file)
allDomain/
js/ (contains widgets and custom applications)
service/ (contains additional services)
widget/ (contains UI widgets)
customize.js (general customization JavaScript file for adding new services, widgets, and so on)
layout/
nls/ (contains language-specific files)
themes/ (contains themes)
customize.js (customization JavaScript file specific to adding and removing themes. This file is different from js/customize.js.)
example_com/
js/ (contains example_com widgets and custom applications)
widget/ (contains example_com UI widgets)
customize.js (example_com customization JavaScript file for adding new services, widgets, and so on)
nls/ (example_com language-specific files)
themes/ (contains example_com themes)
customize.js (customization JavaScript file specific to adding and removing themes. This file is different from js/customize.js.)
The sample customization directory contains two subdirectories:
c11n_sample/allDomain
c11n_sample/example_com
The allDomain directory contains customizations that affect all domains in a hosted-domain deployment. If the deployment is in a single domain, allDomain contains customizations that affect this single domain.
The example_com directory contains customizations specific to a domain named example.com. The directory is named example_com instead of example.com. This is done for ease of programming. In your LDAP directory, all data that names or is related to the domain, example.com, should remain example.com. Do not change the dot '.' to an underscore ' _ ' in LDAP. The Convergence customization code converts the dot '.' to an underscore ' _ ' whenever the directory name is used.
At run time, Convergence uses the following rules to load the customizations:
The customizations for specific domains are loaded first.
If there are no customizations for specific domains, customizations for all domains are loaded.
The new customizations codes override the base client code.
For example, if a non example.com user logs in to Convergence, the customizations are applied from the allDomain directory. However, if an example.com user logs in to Convergence, the customizations are applied from the example_com directory.
The config.js configuration file defines the types of customization (such as theme, javascript codes, and i18n) that are enabled. The config.js file is the first one loaded from the customization directory.
The following example config.js file shows a configuration for allDomain, which has enabled the theme and javascript. It also includes a configuration for the domain example.com, which has only enabled the theme.
dojo.provide("c11n.config");
c11n.config={
// allDomain configuration
allDomain:{
module: "allDomain", //module name
themeEnabled: true, //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 a comma
}
//replace example.com for each domain configuration, change
//domain name example example.com to example_com for internal programming
example_com:{
module: "example_com", //module name
themeEnabled: true, //true if theme is customized
i18nEnabled: false, //true if i18n is customized
jsEnabled: false //true if js is customized
//the last entry must not end with a comma
}
}
Note:
Do not add a comma to the last entry of each configuration in the config.js file. Otherwise, your customization will not properly load, and you might see a c11n.config error. In the above example, there is no comma after the jsEnabled customization setting in either the allDomain or example_com configuration.Create c11n_Home.
In c11n_Home/, edit config.js so that i18nEnabled and jsEnabled are both set to true in the allDomain section:
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: 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 section:
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")
dojo.require("c11n.allDomain.js.widget.mail.CreateMessage");
Clear browser cache and open new Compose tab to view modifications.
This section discusses the following topics:
The first topic, "About Convergence Architecture Customization Support" applies to all types of customization.
The next two topics, "Dojo Basics" and "About Dojo Statements Map to the Convergence Directory Structure" apply only to more "advanced" types of customization.
You must use dojo to customize Convergence widgets. For example, to add features to the banner, or to integrate a third-party application, you will customize widgets.
To integrate an outside application, for example, you may want to add a button or icon (or both) to the UI to provide access to the application. Buttons and icons are widgets; to create them, you must write custom javascript with dojo.
If you only want to change the theme (look and feel) of the Convergence UI, or offer alternate themes to end users, you customize the theme.json file. You do not need to write dojo code. You do not need the information in the second and third sections.
Finally, "Preserving Custom Widgets During Upgrades" mainly concerns preserving dojo widget customizations, but also briefly describes how CSS or theme.json files are preserved during upgrades.
The Convergence architecture separates the standard UI elements from the corresponding customized elements. To customize the UI, you do not alter the standard UI definitions; these always remain in the code. Instead, you add customizations in a separate directory. The relationship between them is set up as follows:
A single style-sheet file, named template.css, defines all the UI elements. These elements determine the look and feel of the standard UI.
All images in the template.css file are defined as background images. If no customized images exist, the background images are loaded, and the default UI appears to the user.
A theme is a collection of styles that affect the background color, background images, border color, and font color. Rather than modifying the CSS files directly in a theme, Convergence uses a theme.json file to map UI styling into CSS format. See "Working with the Convergence UI" for more information.
Your other customized definitions, which create custom Convergence and dojo widgets, redefine the default UI elements at run time without altering the default source code.
Convergence searches for c11n_Home/config.js. If this file exists, the customization service boots your customization code based on the configuration setup defined in the config.js file.
The technique of customization begins with the loading order of the script and CSS files.
First, the files containing all the Convergence source code are loaded. These default files include the HTML, CSS, image, and javascript files.
Second, if customization is enabled, the customization code is loaded. The customization files also include CSS, image, and javascript files.
Third, the actual Convergence UI and widgets are created. The creation process uses both the customized code and standard source code to build the UI. That is, the creation process combines all your customized elements with the standard elements defined in the default code. For example, if you customize only the banner, the creation process combines the customized banner with the standard elements in the rest of the UI. The components of the standard banner that have been customized are now suppressed.
Customization is designed to work either in a single-domain or hosted-domain environment. For hosted domains, customization is applied as follows:
The settings defined in the base code are loaded and applied.
Customizations for the specific domain in which the end user has logged in are loaded and applied. Different domains can display the UI in different languages.
Thus, the loading order follows the same principle of applying the more general definitions first, followed by the more specific customizations.
You must use a reserved keyword, allDomain, to create customizations that apply across all domains in the Convergence deployment.
The loading order for customizations in the allDomain directory is the same as for any other domain.
Thus, at run time, Convergence behaves as follows:
It loads the base-code settings.
It loads either the customizations defined in allDomain or the customizations defined in a specific domain (if customizations have been created for that domain).
When Convergence is installed, the client component of the Convergence software is installed in Convergence_Domain/docroot/iwc_static.
All client source files, including the customization files, reside in the iwc_static directory. By default, iwc_static contains the following directories:
/layout /js/dojotoolkit /js/iwc /c11n_sample
If you create customizations, they must be stored in the c11n_Home directory, which must be named c11n under directory iwc_static. Thus, the c11n_Home directory must be
/iwc_static/c11n
When you patch or upgrade Convergence, files in the standard Convergence directories are updated and replaced. However, the patch or upgrade does not touch other directories and files not originally installed by the installer. The c11n_Home directory is left untouched.
Dojo code is required for customizing Convergence widgets such as the banner, buttons, icons, and so on. You may want to add or alter widgets to customize the banner or integrate a third-party application.
This release of the Convergence customization framework is built on Dojo 1.3.2. See the Dojo web site for more information:
Table 1-2 shows the dojo statements that provide the foundation for creating dojo classes:
| dojo Statement | Function |
|---|---|
|
dojo.provide("x.y.z") |
Tells dojo that the module x.y.z is defined, and puts x.y.z into the dojo internal hash. |
|
dojo.require("x.y.z") |
Finds module x.y.z from the dojo internal hash. If the module is not found, loads it. |
|
dojo.declare(className, superclass, properties) |
Creates a new className from the superclass and passes in the properties associated with the new class. |
Dojo minifies or compresses layers, single JavaScript files which combine all of the JavaScript code from multiple source files, including dependencies.
According to the dojo documentation, minification makes your JavaScript code smaller by:
Removing extra spaces and blank lines
Removing any comments
Making internal variable names shorter
Minification can make the layers load faster, and can take less time for the browser's JavaScript engine to parse.
However, minified files (for example, Convergence_Domain/docroot/iwc_static/js/iwc) are often difficult to read and debug because they are compressed. Therefore, a debugging directory is provided in the Convergence customization libraries: Convergence_Domain/docroot/iwc_static/js/debug/iwc.
The debugging directory provides the original, uncompressed content which includes source code, HTML templates, and the original Convergence file directory structure that corresponds to the source code. The debugging directory provides clear references to the Convergence source code, making it easier to read than in the compressed format.
Dojo code maps to the following directories in Convergence:
For example:
dojo.require("iwc.widget.Banner")
refers to a file located in
iwc_static/js/iwc/widget/Banner.js
For example:
dojo.require("c11n.allDomain.js.widget.Banner")
refers to a file located in
iwc_static/c11n/allDomain/js/widget/Banner.js
The Convergence base code, in particular the dojo javascript files that define the UI widgets, are designed to allow you to create custom files that can be preserved automatically when the Convergence software is upgraded.
When you create custom files in c11n_Home, those files are not touched during upgrades. Therefore, they are always preserved.
However, when you create customized dojo widgets, you can use a few different methods to copy or extend the base dojo code. Each will have different ramifications when the Convergence software is upgraded.
Before you begin coding, you should plan which approach to take. Choose the one that best suits your goals.
First, let's briefly look at the simplest type of customization: how custom themes are handled during upgrades.
It is not possible to upgrade themes created for Convergence 1.x. Themes created for Convergence 2.x are automatically preserved when upgrading to later versions of Convergence. However, if in future releases, new variables are added to the dojo template file or to specific themes, you will need to add those values to your theme.json files and any new images.
By default, custom widgets residing in the c11n_Home directory are preserved during Convergence upgrade. However, changes are made to the base code directory and to file names, your custom widgets may need to be modified. To do so:
Map your custom widgets to the new widget name: see "About Convergence UI Widgets" to determine new widget names.
Review the examples in the c11n_sample directory and in this guide to determine if the functionality of your custom widgets is similar to the provided examples. You can then modify your custom widgets to match the provided examples.
If you are unable to match your custom widget to the provided examples, change the widget name, dojo.require, and dojo.declare lines.
Review the base code widget to determine if the DOM node(s) and dojoAttachPoint have same names.
After changing your widget names, you can run a tool such as Firebug for Firefox to debug your custom widgets.
If after following these steps, you are still unable to retain your widget customization, contact your support channels.
If you create a lot of dojo customizations you will notice that the browser will need to download all of your customization files individually. Convergence already requires a lot of files to be downloaded by the browser, so increasing the number of files by another 10 or 20 or so will only make the initial load time worse.
Instead of creating the customizations as individual files, you can add the customizations directly to customize.js. You can have an unlimited number of customizations, but still only one file will be required.
For example, instead of:
c11n_Home/allDomain/js/widget/mail/option/VacationMessage.js
dojo.provide("c11n.allDomain.js.widget.mail.option.VacationMessage");
dojo.require("iwc.widget.mail.option.VacationMessage");
dojo.declare("iwc.widget.mail.option.VacationMessage", iwc.widget.mail.option.VacationMessage, {
constructor: function() {
// your customizations to this widget
},
last: ""
});
and
c11n_Home/allDomain/js/customize.js
dojo.require("c11n.allDomain.js.widget.mail.option.VacationMessage");
you can consolidate it all into one file. Furthermore, pobrien78 correctly points out that you can get rid of the last dojo.require() line:
c11n_Home/allDomain/js/customize.js
dojo.provide("c11n.allDomain.js.widget.mail.option.VacationMessage");
dojo.require("iwc.widget.mail.option.VacationMessage");
dojo.declare("iwc.widget.mail.option.VacationMessage", iwc.widget.mail.option.VacationMessage, {
constructor: function() {
// your customizations to this widget
last: ""
});
Finally, you might want to consider running this file through a JavaScript compressor such as ShrinkSafe to reduce the size, and therefore latency, of the JavaScript by browsers.
With the exception of system-generated attributes, custom-useroptions.properties defines mappings between LDAP attributes which can be retrieved through the get_allprefs.iwc command from your LDAP directory for any customization purpose. It allows site administrators to map custom LDAP attributes. For example, you can obtain employee numbers from your LDAP directory through the get_allprefs.iwc command, which you can use to customize the UI with the custom-useroptions.properties file.
The custom-useroptions.properties file exists in the following directory: /var/opt/sun/comms/iwc/config/
Use custom-useroptions.propertiesUsed with:iwc.protocol.iwcp.setUserPrefs to set custom attributes. Once defined, the custom properties can be accessed in the iwc.userPrefs.custom javascript objectYou can update the custom properties by using iwc.protocol.iwcp.setUserPrefs.
The following file syntax describes how to map custom LDAP attributes in custom-useroptions.properties, where <mapping-name> is the parameter name to be passed to setUserprefs and <ldap-attribute> is the LDAP attribute to be mapped.
# This property file is a mapping of request parameter name for a custom user # preference to its corresponding LDAP attribute name. # Format: # <mapping-name>=<ldap-attribute> # Where: # - <mapping-name> must start with "custom." (without quotes). # ex: custom.mysmsnumber=<ldap-attribute> # - <ldap-attribute> is a name of the ldap attribute in user's LDAP entry. # + To use a single valued attribute, just provide the name of the attribute. # ex: custom.mysmsnumber=smsNumber # + To use a multi valued attribute with sub-attributes, delimit the ldap # attribute with a ":" followed by the sub-attribute name. # ex: custom.mysmsnumber=contactMode:sms (for multi valued ldap attribute # contactMode with values as say - contactMode: sms=<value> etc # + To use a multi valued attribute, delimit the ldap attribute with a ":" # followed by a *. # ex: custom.mysmsnumber=smsNumbers:* # - In all the above cases, the xml response to the client would have the # mapping name (excluding "custom.") as the element name and the user preferenc # as the value of a <value> element (child of mapping element).
Example of custom-useroptions.properties:
custom.name=cn
To use a custom user option in a Convergence customization, set the option, as shown in the following example:
iwc.userPrefs.custom.name
To update a custom user option in a Convergence customization, use setUserPrefs, as shown in the following example:
/* where data is a array of objects. For example: */
var data = [];
data.push({name:<param name>,value:<param value>});
var deferred = iwc.protocol.iwcp.setUserPrefs(data, true /* always sync */);
deferred.addCallback(this, function() {
//success
});