Convergence Options Customization Examples

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 Oracle WebLogic Server for Convergence.

See Convergence System Administrator's Guide for more information.

Disabling External POP Account Access

The following example removes External Accounts from the Options section of Convergence.

This is a useful example when there is a need to restrict users from modifying specific account settings 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/service/
```
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.Navigator");
```

In c11n_Home/allDomain/js/widget/option, create the JavaScript file (Navigator.js) that removes External Accounts.

dojo.provide("c11n.allDomain.js.widget.option.Navigator"); 

dojo.require("iwc.api"); 
dojo.require("iwc.widget.option.Navigator"); 

dojo.declare("iwc.widget.option.Navigator", iwc.widget.option.Navigator, 
        { 
                postCreate: function() { 
                        // call the superclass postCreate 
                        this.inherited(arguments); 

                        // remove the External Accounts 
                        iwc.api.removeOption("/Mail/External Accounts"); 

                }, 

                last: "" 
        } 
);

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Enabling or Disabling the Modification of Identity Settings

The following example prevents or allows users from editing the values in the Display Name field, Email Address field, or Reply-to Address field on the Options Local Account tab. These fields still appear in Convergence, but cannot be edited.

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");

// Disable Identity Settings
dojo.require("c11n.allDomain.js.widget.mail.option.Identity");

Do one of the following:

To disable the modification of identity settings, in c11n_Home/allDomain/js/widget/mail/option, create or modify the JavaScript file (Identity.js) that controls Identity settings.

dojo.provide("c11n.allDomain.js.widget.mail.option.Identity");
dojo.require("iwc.widget.mail.option.Identity");
dojo.declare("iwc.widget.mail.option.Identity", iwc.widget.mail.option.Identity, {

         postCreate: function () {
                 this.inherited(arguments);
                 this.senderName.setDisabled(true);
                 this.replyTo.setDisabled(true);

         },

         last: ""

});

To enable the modification of identity settings, in c11n_Home/allDomain/js/widget/mail/option, create or modify the JavaScript file (Identity.js) that controls Identity settings.

dojo.provide("c11n.allDomain.js.widget.mail.option.Identity");
dojo.require("iwc.widget.mail.option.Identity");

dojo.declare("iwc.widget.mail.option.Identity", iwc.widget.mail.option.Identity, {

         postCreate: function () {
                 this.inherited(arguments);
                 this.senderName.setDisabled(false);
                 this.replyTo.setDisabled(false);

         },

         onSubmit: function() {
                var data = [];
               data.push({name:'general.cn',value:this.senderName.attr('value')});
                var deferred = iwc.protocol.iwcp.setUserPrefs(data, true /* always sync */);
                deferred.addCallback(this, function() {
                     //success
                 });
                this.inherited(arguments);
        },

         last: ""

});

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Redirecting Users to Another Page to Change Password

This example demonstrates how you can redirect users to another page to their password for 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/widget, create a JavaScript file (option/Password.js) that redirects the change password option to www.example.com.

dojo.provide("c11n.allDomain.js.widget.option.Password");
dojo.require("iwc.widget.option.Password");
dojo.require("iwc.widget.form.BorderContainerForm");
dojo.require("iwc.widget.option.ViewerTabPane");
    
dojo.declare("iwc.widget.option.Password", [iwc.widget.option.ViewerTabPane], {
        templateString: '<div><form dojoType="iwc.widget.form.BorderContainerForm" dojoAttachPoint="form"><iframe src="graphics/www.example.com" width=100% height=1000px></iframe></form></div>',
     
        postCreate: function() {
                dojo.addClass(this.form.buttonNode.domNode, "dijitHidden");
        },
     
        last: ""
     
});

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Removing Change Password, Vacation Message, and Calendar Notification Options

The following example removes Change Password, Vacation Message, and (Calendar) Notifications from the Options section of Convergence.

This is a useful example when there is a need to restrict users from modifying specific account settings 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/service/
```
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.Navigator");
```

In c11n_Home/allDomain/js/widget/option, create the JavaScript file (Navigator.js) that removes Change Password, Mail Vacation Message, and Calendar Notifications.

dojo.provide("c11n.allDomain.js.widget.option.Navigator");

dojo.require("iwc.api");
dojo.require("iwc.widget.option.Navigator");

dojo.declare("iwc.widget.option.Navigator", iwc.widget.option.Navigator,
       {
               postCreate: function() {
                       // remove the change password option
                       iwc.api.removeOption("/Global/Change Password");

                       // remove the Mail vacation message option
                       iwc.api.removeOption("/Mail/Local Account/Vacation Message");

                       // remove the Calendar Notifcations option
                       iwc.api.removeOption("/Calendar/Notifications");

                       // call the superclass postCreate
                       this.inherited(arguments);
               },

               last: ""
       }
);

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Removing Default Language List in General Options

On the Options General tab, you can remove the Language list from the Convergence UI. By removing the Language list, users can view Convergence only in the default language configured by the application administrator.

This is a useful example when there is a need to restrict users from modifying specific account settings 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/service/
/c11n_Home/allDomain/js/widget/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.General");
```

In c11n_Home/allDomain/js/widget/option, overwrite the contents of the global options JavaScript file General.js with the following code.

dojo.provide("c11n.allDomain.js.widget.option.General");

dojo.require("iwc.widget.option.General");

dojo.declare("iwc.widget.option.General",
       iwc.widget.option.General,
       {
               buildRendering: function() {
                       this.inherited(arguments);

                       var elems = dojo.query("h2", this.form.domNode);
                       if (elems[0]) dojo.style(elems[0], "display", "none");

                       elems = dojo.query(".FormField", this.form.domNode);
                       if (elems[0]) dojo.style(elems[0], "display", "none");

               },

               last: ""
       }
);

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Removing Languages from Language List in General Options

On the Options General tab, you can remove languages from the Language list. By removing languages from the Language list, users cannot select them.

This is a useful example when there is a need to restrict users from modifying specific account settings 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/service/
/c11n_Home/allDomain/js/widget/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");
// Hide a few default languages
dojo.require("c11n.allDomain.js.widget.option.General");

In c11n_Home/allDomain/js/widget/option, extend the JavaScript file option/General.js with the following code. In this example, the languages ja, ko, zh-CN, and zh-TW are removed from the list of available languages in the Languages list.

dojo.provide("c11n.allDomain.js.widget.option.General");

dojo.require("iwc.widget.option.General");

dojo.declare("iwc.widget.option.General",
       iwc.widget.option.General,
       {
               buildRendering: function() {
                       this.inherited(arguments);

                       // remove your languages here
                       this.language.removeOption(["ja", "ko", "zh-CN", "zh-TW"]);

               },

               last: ""
       }
);

Restart the Oracle WebLogic Server and clear the browser cache to see the change.

Customizing the Default Alert Sounds

Each user can configure their Convergence to play a sound alert when they receive a new email message.

You can customize the sound files that are played to the user.

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/service/
/c11n_Home/allDomain/layout/media
```
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.service.AudioNotification");
```
In c11n_Home/allDomain/layout/media, place the two custom MP3 files, one for new email and instant messages, and one for incoming and outgoing calls.
In c11n_Home/allDomain/js/service, create the JavaScript file (AudioNotification.js) that specifies the path to the new audio files.
```
dojo.provide("c11n.allDomain.js.service.AudioNotification");
 
dojo.require("iwc.service.AudioNotification");
 
dojo.declare("iwc.service.AudioNotification",iwc.service.AudioNotification,{
       mediaPath: "media_path_directory",
       audioAlertFileName: "custom_audio_message.mp3",
       callAlertFileName: "custom_audio_call.mp3"
 
});
```
Where:.
- media_path_directory is the customized media directory relative to the location of the main.html page used for the domain. For example, if the default main.html page is used for all domains (/iwc_static/layout/main.html), media_path_directory is c11n_Home/allDomain/layout/media.
- custom_audio_message is the custom audio MP3 file for new email and instant messages.
- custom_audio_call is the custom audio MP3 file for incoming and outgoing voice or video calls.
Note:
One of the following steps are also required in WebLogic Server to enable audio alerts:
- Create a file called mimemappings.properties under the <Convergence_Domain>/config folder and add mp3=audio/mpeg.
- Add the following fields in the <Convergence_Domain>/servers\ManagedServer/tmp/_WL_user/<Convergence>/<value>/war/WEB-INF/web.xml file:
```
<mime-mapping>
  <extension>mp3</extension>
  <mime-type>audio/mpeg</mime-type>
</mime-mapping>
```
Restart the Oracle WebLogic Server and clear the browser cache to see the change.