Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.
Note: The branding procedure described in this article is only applicable to the stand-alone Sametime Connect client. It cannot be used for the embedded Sametime client in Lotus Notes®.
Customization of the Lotus Sametime Connect client can be achieved through the use of branding plug-ins. Current users might be interested in creating their own personal branding plug-ins. On a larger scale, a company might be interested in using a communication tool that can be branded with the company’s identity. If a company were to adopt Lotus Sametime as their communication and collaboration tool, the Lotus Sametime client could be customized with the company’s branding, and the branding could automatically appear to all company users of the tool.
A sample branding plug-in for the fictitious company Your Co is included with this article as a download. The article provides instructions on how to install the plug-in into a single instance of the Lotus Sametime 8.0 and later client, tips for updating the sample plug-in with other images, and guidelines for creating personalized or company branding. Neither development experience nor an Eclipse integrated development environment (IDE) is required to perform the operations described in this article.
Lotus Sametime allows you to have several branding plug-ins installed concurrently in your Lotus Sametime Connect client without causing conflict in your environment. Users can easily switch between brandings if they choose to do so. Custom branding plug-ins can also be installed in Lotus Sametime 7.5, but they require a different plug-in than the one provided with this article.
Branding can be applied to three areas in the Lotus Sametime Connect client. In figure 1, the three branding areas are shown. In the screen capture, the Lotus Sametime windows are stacked. The login window opens on top, the contacts list window opens beneath that, and the chat window is on the bottom.
Figure 1. The three branding areas of the Lotus Sametime Connect client
The first branding area that users see is the login window, shown in figure 2.
Figure 2. Your Co branding in the login window
The branding in figure 2 places an image above the user login fields. The second branded area is below the Contacts/Primary Contacts lists. This region is rendered from an HTML file. In the Your Co example seen in figure 3, the HTML file contains some links and a branding image (the Lotus Sametime client window in the figure has been reduced in size).
Figure 3. Your Co branding in the Contacts hub
The third branding area is located near the right top corner of the Lotus Sametime chat window (see figure 4).
Figure 4. Your Co branding in the chat window
Install the sample plug-in
For this article, assume that users have the Lotus Sametime client installed in the directory C:\SametimeConnect8.
The plug-in is packaged as part of a feature site. For more information on building feature sites, see the technote, " Automatically updating Sametime 7.5.x Connect clients."
Your Co feature site
Download the yourco_feature_site.zip file, included in this article.
To learn more about ZIP archive files, JAR archive files, extracting files from an archive, or creating an archive file, see the section "Working with archive files" later in this article.
Extract all files from yourco_feature_site.zip onto your hard disk, for example, into the directory C:\temp. This step creates a folder called YourCoSametimeBranding in the C:\temp folder. Figure 5 shows the file structure.
The ZIP file contains a site.xml file and JAR files for the feature and plug-in. When you install this feature, you point to the base directory YourCoSametimeBranding.
Figure 5. Your Co feature site file structure
The site.xml file contains the identifier and the location of the feature as shown in listing 1.
Listing 1. The feature tag in site.xml
<?xml version="1.0" encoding="UTF-8"?> <site> <feature url="features/yourbranding_feature_8.0.0.jar" id="yourbranding_feature" version="8.0.0"/> </site>
The yourco_feature_8.0.0.jar file contains a single file, feature.xml. This file is the feature descriptor, containing the feature ID, label, description, the ID of the plug-in, and copyright and license descriptions as shown in listing 2.
Listing 2. Feature descriptor in feature.xml
<?xml version="1.0" encoding="UTF-8"?> <feature id="yourbranding_feature" label="Your Branding Sametime Feature" version="8.0.0" plugin="yourbranding.branding"> <description url=""> [Enter Feature Description here.] </description> <copyright url=""> [Enter Copyright Description here.] </copyright> <license url=""> [Enter License Description here.] </license> <plugin id="yourbranding.branding" download-size="0" install-size="0" version="8.0.0"/> </feature>
To install the plug-in in Lotus Sametime 8.0 and later, follow these steps:
- Launch the Lotus Sametime client and log in. From the Tools menu, select Plug-ins, then select Install Plug-ins.
- In the window that displays, select the second option, Search for new features to install.
- Click Next. Click the Add Folder Location button, and browse to the folder where you extracted the yourco_feature_site.zip (C:\temp\YourCoSametimeBranding). Click OK. See figure 6.
Figure 6. Add the folder location of the plug-in
- The location list shows temp/YourCoSametimeBranding. Ensure that the check box next to the location is selected, and click Finish.
- In the next window that displays, expand temp/YourCoSametimeBranding and select Your Co’s Sametime Feature 8.0.0, then click Next. See figure 7.
Figure 7. Select the features to install
- Click I accept the terms in the license agreements, then click Next. See figure 8.
Figure 8. Accept the feature’s license agreement
- Click Finish. You then see a message indicating that you need to restart Lotus Sametime. You can do so. Upon restart, you do not see the Your Co branding.
Set the Lotus Sametime branding
To instruct the Lotus Sametime client to select the Your Co branding instead of the default branding, you can modify the file plugin_customization.ini. This file is located in the C:\SametimeConnect8\rcp directory. Create a copy of the plugin_customization.ini file for backup. Open the file for editing using a text editor. To change the branding, you must set a preference in this file. Set the stBranding preference as follows:
This code should display on one line in the file. yourco.branding.yourco_custom is the identifier of the Your Co branding feature plug-in. yourco_custom is the plug-in identifier in plugin.xml, and yourco.branding is the feature identifier in feature.xml. The feature identifier is also specified in the site.xml file.
After you have made this change, save the file, exit Lotus Sametime (if it is running), and then relaunch Lotus Sametime. You should be greeted by the login window, branded with the Your Co logo.
You can have several branding plug-ins installed in Lotus Sametime concurrently. To switch to a different plug-in, change the stBranding property in the plugin_customization.ini file so that it refers to the identifier of the branding plug-in that you want to use. If Lotus Sametime cannot find the plug-in referenced in the plugin_customization.ini file, it uses the default branding. Any changes made to plugin_customization.ini require that you relaunch Lotus Sametime.
Overview of the plug-in code
The plug-in is installed in this file:
The contents of the yourco.branding_8.0.0 folder are the extraction of the yourco.branding_8.0.0.jar file from the yourco_feature_site.zip. This folder contains the plugin.xml file, which provides the description of the plug-in. See listing 3.
Listing 3. The contents of the plugin.xml file
<?xml version="1.0" encoding="UTF-8"?> <plugin> <extension id="yourco_custom" point="com.ibm.collaboration.realtime.ui.stbranding"> <stbranding id="yourco.branding.login" name="login dialog branding" targetView="com.ibm.collaboration.realtime.login"> <image file="brand/images/YOURCO_400X100.jpg"/> </stbranding> <stbranding height="64" id="yourco.branding.chat" name="chat window branding" targetView="com.ibm.collaboration.realtime.chatwindow" valign="top" width="64"> <image file="brand/images/YOURCO_64X64.png"/> </stbranding> <stbranding height="35" id="yourco.branding.imhub" name="contact list branding" targetView="com.ibm.collaboration.realtime.imhub" valign="bottom"> <website url="/brand/im_hub.html"/> </stbranding> </extension> </plugin>
Note some of the details that are specified in this file:
- The login image (brand/images/YOURCO_400X100.jpg)
- The chat window image (brand/images/YOURCO_64X64.png)
- The chat window image height and width (64 and 64 pixels)
- The contact list branding URL (/brand/im_hub.html)
- The contact list height (35 pixels)
Modifying the sample plug-in
To make modifications to the sample plug-in, first create a copy of the YourCoSametimeBranding folder in C:\temp, and call it C:\temp\My_YourCoSametimeBranding. In the My_YourCoSametimeBranding\plugins folder, extract the contents of the yourco.branding_8.0.0.jar into the folder My_YourCoSametimeBranding\plugins\yourco.branding_8.0.0. See figure 9.
Figure 9. Modified feature file structure
The Your Co images are located in My_YourCoSametimeBranding\plugins\yourco.branding_8.0.0\brand\images.
To use your own branding images, you can copy your image files into the same directory, and then change the file reference in the file C:\temp\My_YourCoSametimeBranding\plugins\ yourco.branding_8.0.0\plugin.xml. Also, you can adjust the width and height sizes where appropriate. For sizing considerations, see the next section, "Branding recommendations."
To modify the contact list branding area, open the file C:\temp\My_YourCoSametimeBranding\plugins\ yourco.branding_8.0.0\brand\im_hub.html for editing. In the Your Co plug-in, the HTML file displays two links and an image. Modify as desired, and adjust the height in the plugin.xml file if necessary.
When you are ready to test your changes, follow these steps:
- Create a JAR file for the plug-in, consisting of the contents of the yourco.branding_8.0.0 folder: C:\temp\My_YourCoSametimeBranding\plugins\ yourco.branding_8.0.0.jar.
- Uninstall the Your Co sample branding plug-in from Lotus Sametime (see the section, "Removing or disabling the sample Plug-in," for more details), and install it again. Remember to reference the updated feature update site in C:\temp\My_YourCoSametimeBranding.
To change the identifier of the plug-in or feature, you need to modify the plugin.xml file, feature.xml, and site.xml files.
To modify any feature information such as the license or copyright description, you need to extract the yourco.branding_feature_8.0.0.jar file, make changes to the feature.xml file, recreate the JAR file, and then reinstall the feature site.
The image sizes used in the Your Co branding sample are as follows:
- Contact list: 130 x 30 pixels
- Chat window: 64 x 64 pixels
- Login window: 400 x 100 pixels
Keep in mind that the user can resize the chat window and contact list window. You might want to consider using images with transparent backgrounds. If an image is used in the contact list, you could also set the background color in the HTML to that of the background color of the image. In this sample, the image in the contact list is placed to the right in a table of 100 percent width in the HTML. If the list is resized, the logo stays all the way to the right.
If your company would like to use Lotus Sametime as a business tool for communication, a custom branding plug-in can be created and included in the core Lotus Sametime package for deployment. This customization means that the company’s branding automatically displays to all company users of the Lotus Sametime client. Branding plug-ins can be automatically provisioned to users’ clients through administrative controls. There are several methods for doing this. You can easily package the plug-in so that it is included in the Lotus Sametime client 8.0 installation package, or you can post it on an update site and set the Lotus Sametime client to automatically receive the updates. The Lotus Sametime server can be configured to force the update to all clients within an environment.
To add a personal touch to Lotus Sametime, consider creating a branding plug-in that includes your own personal pictures, favorite links (in the contact list branding space), and more. Perhaps consultants who are constantly on the road would like to add small images of a loved one to their Lotus Sametime clients. For example, see the image in figure 10.
Figure 10. A branded login screen
Removing or disabling the sample plug-in
To uninstall or disable the plug-in, go to the Tools menu in Lotus Sametime Connect client, select Plug-ins, then select Manage Plug-ins. In the left navigation of the window that displays, expand the folder C:\SametimeConnect8\shared\eclipse and click Your Co’s Sametime Feature 8.0.0. Click Uninstall in the right panel.
Working with archive files
There are several archive types and several tools that you can use to work with file archives. The two archive types mentioned in this article are ZIP (.zip) files and JAR (.jar) files. WinZip is a popular utility for working with archive files. If you don’t have WinZip installed, you can download a trial offering http://www.winzip.com.
To open an archive file (JAR or ZIP) and extract the files from it, launch WinZip, go to the File menu, and then select Open Archive. Browse to the file you want to open, and then click Open. In the Actions menu, select Extract. Browse to the folder you want to extract the files into, for example, C:\temp, and then click Extract.
To create an archive file (ZIP or JAR), use Microsoft® Windows® Explorer to browse to the folder or files that are going into your archive. Select the files and folders to be added to the archive. Right-click, go to WinZip, and then select Add to Zip file. In the Add to archive field, enter the file name for the new archive (you can browse to the folder by using the Open button), and then click Add.
Through branding plug-ins, the Lotus Sametime 8.0 and later Connect client provides unique user experiences. Branding plug-ins can be created, installed, and used by individuals, or they can be used company-wide.
Your Co images provided by Mandee M. Astuti, sister of the author. Mandee is the Creative Director of Vamp Design, http://www.vamp-design.com.
- Participate in the discussion forum.
- Refer to the IBM Lotus Sametime product page.
- Refer to the technote, "Automatically updating Sametime 7.5.x Connect clients."
- Refer to the IBM Redbooks® publication, "Extending Sametime 7.5 - Building Plug-ins for Sametime."