Sun Java System Instant Messaging 7.2 Administration Guide

Customizing Instant Messenger

Instant Messenger is customizable. HTML and JNLP files can be customized to suit an organization's specific needs. If you want to customize the resource files for your deployment, you should run the configure utility (if you haven’t already done so after installing), customize the files, then redeploy the resource files. You need to run the configure utility first because configure creates some of the files that you can customize. (See Redeploying Resource Files for redeployment instructions.)

You can customize Instant Messenger to meet your requirements in the following ways:

This section describes the Instant Messaging server files you can modify to customize Instant Messenger. The files that you can customize are all located in the resource directory im-svr-base/html directory. See Table 3–1 for information on default directory locations.

Instant Messenger Resource Files

The Instant Messenger resource files are located within a directory referred to as the resource directory or im-svr-base/html.

Table 15–1 contains the list of Instant Messenger files in the resource directory (im-svr-base/html). It also contains the description and customization information for these files. Within the resource directory, the /locale subdirectory is represented generically in a directory path as lang, but specifically as abbreviations of languages, such as, en_US, jp, and fr_FR.

Table 15–1 Instant Messenger Resource Files in im-svr-base/html

File  

Description  

Customizable?  

lang/im.html

The initial page that launches the Java Plug-in version of Instant Messenger. 

Yes 

im.html.template

The template version of im.html.

No,  

This file is used by the installation program to generate the im.html file.

imdesktop.jar

A client .jar file, downloaded by im.html or im.jnlp files.

No 

lang/im.jnlp

The .jnlp file used to launch Java Web Start version of Instant Messenger.

Yes 

im.jnlp.template

The template version of im.jnlp.

No 

imjni.jar

A client .jar file, downloaded by im.html or im.jnlp.

No 

messenger.jar

The main client .jar file, downloaded by im.html or im.jnlp.

No 

icalendar.jar

The icalendar parser used to process calendar reminders.

No 

imnet.jar

A client .jar file, downloaded by im.html or im.jnlp.

No 

lang/imbrand.jar

This file contains customizable properties, stylesheets, images, backgrounds, and audio files. 

Yes 

lang/imssl.html

The Initial page that launches Java Plug-in version of Instant Messenger. It is used for running legacy SSL between the client and the multiplexor. Do not use this file for secure communication between the client and server over TLS.

Yes 

lang/imssl.jnlp

This file launches Java Web Start version of Instant Messenger. This file is used for running SSL between the client and the multiplexor. 

Yes 

jnlpLaunch.jsp

If an end user is already logged into Sun JavaTM System Access Manager, this file can be used to allow single sign-on and to launch Instant Messenger using Java Web Start.

Yes 

pluginLaunch.jsp

If an end user is already logged into Sun Java System Access Manager, this file can be used to allow single sign-on and to launch Instant Messenger using Java Plug-in. 

Yes 

index.html

The splash page for an LDAP deployment. It contains links to im.html and im.jnlp, as well as documentation links to windows.htm, solaris.htm, and quickref.htm. You can customize this page for your site’s requirements.

Yes 

index.html.template

The template version of index.html.

No 

lang/imhelp/SunONE.jpg

The image used by quickref.htm, solaris.htm, and windows.htm.

Can be replaced, but not modified. 

quickref.html

solaris.html

windows.html

Located in lang/imhelp/, these files provide documentation on getting started with Instant Messenger.

Yes 

lang/imhelp

Instant Messenger Online Help directory. 

No 

imwebex.jar

 

 

msgrinstall.jar

 

 

Customizing the index.html and im.html Files

If you are using Instant Messenger in a deployment without Sun Java System Access Manager, you can modify the static portion of the index.html and im.html files to produce a fully customized user interface. These HTML files contain both text and markups describing how the text is formatted and handled. Markup is implemented through a set of tags, which specify formats for headers, indents, font size, and font style.

Some of the page elements that can be modified are:

You can launch the Instant Messenger applet and the Java Web Start application from index.html. If you are running the Instant Messenger applet, modify the im.html file. The im.html file is called by index.html, and invokes the Instant Messenger applet. The im.html file is generated when you run the configure utility and contains an applet argument that points to the multiplexor.


Note –

The argument “<PARAM NAME="server" VALUE="servername">” represents the Instant Messaging multiplexor and its port in the im.html file. If you change the iim_mux.listenport parameter’s default value, you need to change the servername value to host.domain:port.


Launching Instant Messenger Using Sun Java System Access Manager SSO

To launch the Instant Messenger client using single sign-on (SSO) with Sun Java System Access Manager use IMLaunch.jsp. This file is in the resource directory.

Sun Java System Access Manager and Instant Messenger must be configured to use the same web container to enable SSO.

To launchInstant Messenger enter the following in a web browser:


codebase/IMLaunch.jsp?server=multiplexor-hostname:muliplexor-port

or


codebase/IMLaunch.jsp?server=www.example.com:5222

Where:

codebase is the codebase from which the Instant Messenger resources are downloaded. For example, http://www.example.com.

multiplexor-hostname is the host name of the mulitplexor. For example, http://www.company22.com.

muliplexor-port is the port number on which the multiplexor listens for incoming client requests. For example, 5222.

IMLaunch.jsp is used for launching Instant Messenger through either Java Web Start or Java Plug-in.

Customizing the Application (Java Web Start)

If you are running Instant Messenger using Java Web Start, you can modify the im.jnlp, imres.jnlp, and imres.jar files to customize the user interface. The following are modifications that can be made to these files:


Example 15–1 Sample im.jnlp File


<?xml version="1.0" encoding="utf-8"?>
<!-- Instant Messenger -->
<jnlp
  spec="1.0+"
  codebase="http://im.i-zed.com:80/im"
  href="en/im.jnlp">
  <information>
    <title>Instant Messaging</title>
    <vendor>I-Zed.com</vendor>
    <homepage href="http://www.I-zed.com/"/>
    <description>I-Zed’s Sun Java System Instant Messenger</description>
    <description kind="short">Instant Messenger</description>
    <icon href="CompanyLogo.gif"/>
    <offline-allowed/>
  </information>
  <security>
    <all-permissions/>
  </security>
  <resources>
    <j2se version="1.3+">
      <resources>
        <jar href="en/imres.jar"/>
        <jar href="en/imbrand.jar"/>
      </resources>
    </j2se>
    <jar href="messenger.jar"/>
    <jar href="imdesktop.jar"/>
    <jar href="imnet.jar"/>
    <jar href="icalendar.jar"/>
    <nativelib href="imjni.jar"/>
  </resources>
  <application-desc main-class="com.iplanet.im.client.iIM">
    <argument>server=im.i-zed.com:45222</argument>
    <argument>help_codebase=http://im.i-zed.com:80/im/en</argument>
  </application-desc>
</jnlp>


Note –

In the im.jnlp file, the argument <argument>servername</argument> represents the Instant Messaging multiplexor host and port. If you change the default value of the iim_mux.listenport parameter, you need to change the servername value to host.domain:port.


Contents of imbrand.jar

The tables in this section list the files in the imbrand.jar file and provide a description of each file wherever possible. The imbrand.jar file also contains the image and audio files you can use to re-brand Instant Messenger. This section contains the following tables:

Table 15–2 Configuration Files

File 

Description 

brand.properties

 

chat-styles.css

 

bgstyles.properties

Background configuration file, used to extend the background set 

Table 15–3 Emoticons

File Name 

Description 

emo_alarm.png

Shows alarm emotion graphically 

emo_angel.png

Shows angelic emotion graphically 

emo_angry.png

Shows angry emotion graphically 

emo_balloons.png

Graphic depiction of a bunch of balloons 

emo_beermug.png

Graphic depiction of a mug of beer 

emo_cake.png

Graphic depiction of a birthday cake 

emo_calendar.png

Graphic depiction of a calendar 

emo_canworms.png

Graphic depiction of a can of worms 

emo_clown.png

Graphic depiction of a clown’s head 

emo_cool.png

Shows cool emotion graphically 

emo_dead.png

Indicates dead graphically 

emo_devil.png

Shows devilish emotion graphically 

emo_dont-tell.png

Indicates a request for secrecy graphically 

emo_embarrassed.png

Shows embarrassed emotion graphically 

emo_exclamation.png

Graphic depiction of an exclamation point 

emo_flower.png

Graphic depiction of a flower 

emo_ghost.png

Graphic depiction of a ghost 

emo_goldstar.png

Graphic depiction of a gold star 

emo_grin.png

Shows a grin graphically 

emo_kiss.png

Shows a kiss graphically 

emo_laughing.png

Show laugh emotion graphically 

emo_lifepreserver.png

Graphic depiction of a life preserver 

emo_lightning.png

Graphic depiction of a thunder cloud and lightning bolt 

emo_lovestruck.png

An emoticon used to show love emotion graphically 

emo_martini.png

Graphic depiction of a martini glass 

emo_money.png

Graphic depiction of stacks of coins 

emo_musicnote.png

Graphic depiction of a musical note 

emo_nerd.png

Graphic depiction of a nerd 

emo_nottalking.png

Shows a turned-away countenance graphically 

emo_phone.png

Graphic depiction of a phone receiver 

emo_present.png

Graphic depiction of a wrapped gift 

emo_psychoknife.png

Graphic depiction of a knife 

emo_rathole.png

Graphic depiction of a rat hole 

emo_sad.png

Shows sad emotion graphically 

emo_sick.png

Shows illness graphically 

emo_sleep.png

Shows sleepiness graphically 

emo_smiley.png

Shows a smile graphically 

emo_straightfaced.png

Graphic depiction of a straight-faced person 

emo_sunshining.png

Graphic depiction of a sun 

emo_surprised.png

Shows surprise graphically 

emo_tongue-out.png

Graphic depiction of a person sticking out his tongue 

emo_violin.png

Graphic depiction of a violin 

emo_whatever.png

Shows indifference or disdain graphically 

Table 15–4 Application Icons – Windows

File Name 

Description 

im_app_icon_16.png

Title bar icon for Windows 

im_app_icon_24.png

Title bar icon for Windows 

tray_icon.ico

System tray icon for Windows 

Table 15–5 Application Icons – All Platforms

File Name 

Description 

logo_login_footer.png

Logo displayed at the bottom of the Login dialog box 

logo_register.png

Logo displayed on the Register dialog box 

logo_sun.png

Sun logo displayed on the Login dialog box 

Table 15–6 Toolbar Icons

File Name 

Description 

tb_addcontacts.png

Graphic for the Add Contacts button 

tb_alert.png

Graphic for the Send Alert button 

tb_chat.png

Graphic for the Chat With Users button 

tb_conf.png

Graphic for the Add Conferences button 

Table 15–7 Contact List Icons

File Name 

Description 

cl_folder_closed.png

Shows a closed folder graphically 

cl_folder_open.png

Shows an open folder graphically 

Table 15–8 Presence Icons - Contact List

File Name 

Description 

cl_activeconf.png

Icon displayed to indicate an active conference that appears in the Contact List 

cl_away.png

Icon for away status that appears in the Contact List 

cl_dnd.png

 

cl_idle.png

Icon displayed to show idle status that appears in the Contact List 

cl_inactiveconf.png

Icon displayed to indicate an inactive conference that appears in the Contact List 

cl_offline.png

Icon for offline status that appears in the Contact List 

cl_online.png

Icon for online status that appears in the Contact List 

cl_pending.png

Icon that indicates pending status that appears in the Contact List 

Table 15–9 Presence Icons - Status Bar

File Name 

Description 

sb_away.png

Icon for away status that appears in the Status Bar 

sb_dnd.png

 

sb_idle.png

Icon for idle status that appears in the Status Bar 

sb_offline.png

Icon for offline status that appears in the Status Bar 

sb_online.png

Icon for online status that appears in the Status Bar 

Table 15–10 Backgrounds and Background Swatches for the Palette

bgplt_tex_blue.gif

bgplt_tex_brown.gif

bgplt_tex_bubble_blue.gif

bgplt_tex_bubble_brown.gif

bgplt_tex_bubble_green.gif

bgplt_tex_bubble_grey.gif

bgplt_tex_bubble_orange.gif

bgplt_tex_bubble_purple.gif

bgplt_tex_bubble_ruby.gif

bgplt_tex_crackle_blue.gif

bgplt_tex_crackle_green1.gif

bgplt_tex_crackle_grey.gif

bgplt_tex_crackle_olive.gif

bgplt_tex_crackle_orange.gif

bgplt_tex_crackle_purple.gif

bgplt_tex_crackle_ruby.gif

bgplt_tex_gradation_blue.gif

bgplt_tex_gradation_brown.gif

bgplt_tex_gradation_green.gif

bgplt_tex_gradation_grey.gif

bgplt_tex_gradation_orange.gif

bgplt_tex_gradation_purple.gif

bgplt_tex_gradation_ruby.gif

bgplt_tex_green.gif

bgplt_tex_orange.gif

bgplt_tex_pink.gif

bgplt_tex_purple.gif

bgplt_tex_weave_blue.gif

bgplt_tex_weave_brown.gif

bgplt_tex_weave_green.gif

bgplt_tex_weave_grey.gif

bgplt_tex_weave_orange.gif

bgplt_tex_weave_purple.gif

bgplt_tex_weave_ruby.gif

bgplt_tex_white.gif

bg_tex_bubble_blue.gif

bg_tex_bubble_brown.gif

bg_tex_bubble_green.gif

bg_tex_bubble_grey.gif

bg_tex_bubble_orange.gif

bg_tex_bubble_purple.gif

bg_tex_bubble_ruby.gif

bg_tex_crackle_blue.gif

bg_tex_crackle_green1.gif

bg_tex_crackle_grey.gif

bg_tex_crackle_olive.gif

bg_tex_crackle_orange.gif

bg_tex_crackle_purple.gif

bg_tex_crackle_ruby.gif

bg_tex_gradation_blue.gif

bg_tex_gradation_brown.gif

bg_tex_gradation_green.gif

bg_tex_gradation_grey.gif

bg_tex_gradation_orange.gif

bg_tex_gradation_purple.gif

bg_tex_gradation_ruby.gif

bg_tex_weave_blue.gif

bg_tex_weave_brown.gif

bg_tex_weave_green.gif

bg_tex_weave_grey.gif

bg_tex_weave_orange.gif

bg_tex_weave_purple.gif

bg_tex_weave_ruby.gif

Table 15–11 Sounds

File Name 

Description 

alert.wav

Alert sound 

alerttpc.wav

Alert sound 

away.wav

Sound used when you change your status to away 

receive.wav

Sound used when you receive a message 

send.wav

Sound used when you send a message 

soundoff.wav

Sound used when you turn the sound off 

soundon.wav

Sound used when you turn the sound on 

Rebranding Instant Messenger

The imbrand.jar file contains all images and the properties that control the look and feel of Instant Messenger. You can customize the appearance of Instant Messenger by modifying the images and the properties in imbrand.jar.

ProcedureTo Rebrand Instant Messenger

  1. Copy imbrand.jar file to a working directory.

    For example:


    cp im-svr-base/html/lang/imbrand.jar working-directory
    
  2. Change to the working directory.


    cd working-directory 
    
  3. Extract the imbrand.jar file.


    jar xf imbrand.jar
    

    This command creates a directory tree where the resource files are copied. This directory structure has to be maintained when you modify the individual files in the imbrand.jar file.

    Alternatively, you can extract a single file included in imbrand.jar and put it under the directory structure you specify. For example, to extract only brand.properties, use the following command:


    jar xf imbrand.jar com/sun/im/desktop/brand/brand.properties
    
  4. Update imbrand.jar with the modified .gif, .wav, and .properties files.

    You can update all the files in imbrand.jar as follows:

    jar cf imbrand.jar .

    To update imbrand.jar with a single modified file, use the following command:


    jar uf imbrand.jar com/sun/im/desktop/brand/filename
    

    Where filename is the name of the file included in imbrand.jar, for example, brand.properties.

  5. Copy imbrand.jar to the resource directory.

    For example:


    cp imbrand.jar im-svr-base/html/lang/ .
    

    Note –

    If you support multiple locales in your deployment, follow the procedure for rebranding Instant Messenger for every supported locale.


Customizing User Name and Group Name Display

You can customize how Instant Messenger displays contact and group names by changing the attribute used to display contact names. By default, the Instant Messenger uses the attribute cn to represent a user's display name. In your deployment, you may prefer to use uid or some other attribute instead of cn.

Contact names appear as First Name, Last Name. For example, Frank Smith, Mary Jones, and so on. When two end users have the same first name and last name, it is impossible to know which end user has to be added to the contact list. You can customize Instant Messenger to display more information in the search results for the user search, and to display additional information in the Contact tooltip to help distinguish between contacts. For example, you can display the phone number of the Contact when the mouse is placed over the Contact.

ProcedureTo Change the Attribute Used to Display a User's Name

  1. Open iim.conf.

    See iim.conf File Syntax for instructions on locating and modifying iim.conf.

  2. Specify the attribute you want to use to display usernames as the value for iim_ldap.userdisplay.

    For example, to use the nickname attribute, set the iim_ldap.userdisplay attribute as follows:

    iim_ldap.userdisplay=nickname

  3. Save and close the file.

ProcedureTo Change the Attribute Used to Display a Group's Name

  1. Open iim.conf.

    See iim.conf File Syntax for instructions on locating and modifying iim.conf.

  2. Specify the attribute you want to use to display usernames as the value for iim_ldap.groupdisplay.

    For example, to use the uid attribute, set the iim_ldap.groupdisplay attribute as follows:

    iim_ldap.groupdisplay=uid

    Save and close the file.

ProcedureTo Customize User Name Display in Search Results

  1. Extract the files from imbrand.jar.

    See Table 15–1 for default locations for imbrand.jar

  2. Change to the following directory:

    com/sun/im/client/

  3. Open brand.properties.

  4. Add the dialogs.searchresults.format attribute to the file.

  5. Add the attributes you want to include in search results in the following format:

    ${attr:attribute-name}

    Where attribute-name is the name of the LDAP attribute.

    For example, to include the title attribute, add the following line:

    dialogs.searchresults.format=(${attr:title})

  6. Save your changes and close the file.

  7. Repackage imbrand.jar.

  8. Add the user attributes to iim.conf.

    Specify the attributes as values for the iim_ldap.userattributes parameter. Separate multiple attributes with a comma, for example:

    iim_ldap.userattributes=title,department,telephonenumber

    See iim.conf File Syntax for instructions on locating and modifying iim.conf.

ProcedureTo Customize Tooltip Contents

  1. Extract the files from imbrand.jar.

    See Table 15–1 for default locations for imbrand.jar

  2. Change to the following directory:

    com/sun/im/client/

  3. Open brand.properties.

  4. Add the contact.tooltip.format.html attribute to the file.

  5. Specify the attribute you want to display in the tooltip as the value for contact.tooltip.format.html.

    For example, if you want to display the telephone number and email address of the contact, you would enter:

    contact.tooltip.format.html=mailto: ${attr:mail} tel: ${attr:telephonenumber}

    For more information on customizing the contents of imbrand.jar file, see Customizing the Application (Java Web Start).

  6. Save your changes and close the file.

  7. Repackage imbrand.jar.