2.2 Customizing product strings 

Previous

In IBM Connections, many strings in the user interface are stored as separate resources in text files. There are two categories of string files in IBM Connections: key-value pairs defined in property files (also known as resource bundles) that are stored in the application JAR file, and strings stored in JavaScript files. To change these user interface strings in IBM Connections, you find where the string is stored and override the default string.

Although some aspects of customizing product strings are similar to other user interface customization, others are different. For example, as with other user interface customization, you change specific files and save them to a customization directory. Changes made to the strings stored in the customization directories override the default strings. However, unlike other user interface customizations, for strings stored in property files, you always save files to the <customizationDir>\strings directory. There are no subdirectories under the strings directory. A single directory works because the file name of the customized properties file incorporates the entire directory path of the default property file it overrides. The slashes that represent directory separators are replaced by periods in the customized file name. For example, you want to override a product string that is found in the templates.properties file stored at <WAS_home>\<application_ear>\<application_war>\WEB-INF\lib\lc.util.web-3.0.jar\com\ibm\lconn\core\strings\. Save the customized properties file with the file name com.ibm.lconn.core.strings.templates.properties. The period separators in the customized file name represent the directory separators in the default file. The full file name is required. You cannot save this file as <customizationDir>\strings\templates.properties. The strings directory holds customized strings in property files. Customized strings stored in JavaScript files are stored in the customization directory that matches the installed source directory.

Another difference between product strings and other user interface customization is with translation. IBM Connections is a globalized product that uses the web browser locale to determine the language to display in the user interface. Strings are stored in language-specific and language-independent files. Strings for the default locale (language-independent files) are stored in a file without a language code in the file name. The values for the strings in these files are used when there is no product string in the locale of the web browser . Language-specific files have file names with a language code as a suffix. For example, the com.ibm.lconn.core.strings.templates.properties file is the language-independent file that contains strings used for the default locale. When there is no specific property file for the web browser locale, the strings in this default properties file are displayed. To include a Brazilian Portuguese translation of the strings in this properties file, create a separate file with com.ibm.lconn.core.strings.templates_pt-BR.properties as the file name. The strings that this file contains are shown to users in the Brazilian Portuguese locale. Make sure that there is a language-independent property file with entries for each string you create. This practice ensures that users always see the string. Also store strings that you do not want to be translated in the language-independent files (for example, your company brand names). The use of the language code suffix holds true for strings stored in JavaScript files as well. In that case, the file name follows the form, <file name>_<langcode>.js. For example, act_pt_BR.js.

General process when customizing product strings

Follow this process when customizing strings in IBM Connections:

1. Find the string you want to change in the source application files. In most cases the strings are contained in .jar files.
• For strings stored in properties files: Identify the .jar file that contains the properties file that in turn contains the key that represents the string. Extract the .jar file to a temporary location. A large number of strings exist in a variety of files in IBM Connections. For more information about the location of product strings, see the IBM Connections documentation and search for Customizing product strings.
• For strings stored in JavaScript files: Identify the .jsp file that contains the string you want to modify.
2. Copy the information to the relevant customization directory and make your changes.
• For strings stored in properties files: Copy the key-value string pair from the installed properties file to a separate text file. Modify the value. Save the file with a file name that matches the Java package to the <customizationDir>\strings directory.
• For strings stored in JavaScript files: Copy the .jsp file to the relevant customization directory. Modify the strings you want to override. Delete the default strings from the customized file.
3. For translated strings, create additional files with the language code suffix applied to the file name.
4. Test your changes by restarting the affected IBM Connections application.
5. Publish your changes when you are ready to make the changes available to others. Update the appropriate configuration properties file by checking out the file, updating the version stamp, and checking in the file. For more information, see 1.4 Publishing customizations with the wsadmin tool.

Customizing existing product strings in properties files

To help people who have questions about IBM Connections at the login page, you might direct them to a support forum hosted at your own organization. For example, you might change the text and link that directs people to the product documentation. To make that change to the login page, you could replace the key representing the string in the login.jsp page, but that would make globalization difficult. To support globalizing your customized login page, modify the value of a string in a property file.

The following figure shows the modified login page.


Before you begin
Save a copy of the login page to the customization directory. For more information about how to customize the login page, see the procedure Customizing the login page in 2.1 Matching the user interface to your company brand and policies.

Procedure
In this procedure, we modify the string value that represent the text under "Have a question" in the left column of the login page.

1. Find the key that represents the string you want to modify. In this example, find the key that represents Try the IBM Connections product documentation under "Have a question?" in the left column of the login page.
   
1. Navigate to <customizationDir>\common\nav\templates and open the login.jsp page.
2. Find the line with the key that represents the string. In this example, the key is login.description2, which represents the string "Try the IBM Connections product documentation".
   
3. Search for the key in the source application JAR files. The properties file that login.jsp loads, com.ibm.lconn.core.strings.templates, is identified at the top of the file. So we know that the string we want to change is in the templates.properties file stored in the com\ibm\lconn\core\strings directory of a JAR file. In this case, the file is the lc.util.web-3.0.jar file.
   
4. Extract the JAR file. The lc.util.web-3.0.jar files are identical in all the source directories, so use the JAR file in the Activities application:
1. Navigate to <WAS_home>\Activities.ear\oawebui.war\WEB-INF\lib\ lc.util.web-3.0.jar.
2. Extract the JAR file to a temporary directory. If your compression utility does not recognize the JAR file as a compressed format, rename the extension to a .zip.
3. Navigate to the temporary directory.
4. Open the templates.properties file in com\ibm\lconn\core\strings directory with a text editor.
2. Add the modified properties file to the customization directory:
1. Create a text file and save it with the file name com.ibm.lconn.core.strings.templates.properties in the strings customization directory <customizationDir\strings>.
   The file name must match the Java package information in the source directory. Replace the slashes that represent directory separators in the Java package with periods. In this example, the templates.properties file is stored in the com\ibm\lconn\core\strings package. For information about the location of the customization directory, see 1.2 IBM Connections customization variables.
2. Copy the line that contains the login.description2 key-value pair from the source templates.properties file and paste it in the com.ibm.lconn.core.strings.templates.properties file on its own line.
   
3. Modify the value of the string in the new file. For example:

   login.description2=Try the Renovations support forum

   
   Tip: To make sure that the key matches the original, always copy the key from the source to the customized file. Then change the value.
4. Save the file.
3. Modify strings for a specific language:
1. Create a text file and save it in the strings customization directory. Use a file name that includes the language code. For example:
• For Brazilian Portuguese, save the file with the com.ibm.lconn.core.strings.templates_pt_BR.properties file name.
• For Spanish, save the file with the com.ibm.lconn.core.strings.templates_en.properties file name.
2. Copy the line that contains the key-value pair from the translated properties file in the JAR file. For example:
• For Brazilian Portuguese, copy from the templates_pt_BR.properties file.
• For Spanish, copy from the templates_es.properties file.
3. Paste the key-value pair in the com.ibm.lconn.core.strings.templates.properties, modify the value of the string, and translate the string value to the language represented by the language code.
4. Save the files with the translated strings. For more information about the globalization of product strings, see the IBM Connections documentation and search for Customizing product strings.
   
   Tip: Strings in IBM Connections use Unicode escape codes for Unicode characters. You escape a Unicode character with \uXXXX, where XXXX is the hexadecimal representation of the character. For more information about Unicode escape codes, see the "Localization with ResourceBundles" article in the Oracle Sun Developer Network at http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/.
4. Change the link in the login page to point to the support forum:
1. In your copy of login.jsp in the customization directory, locate the href attribute for login.description2:
   
2. Replace the existing value for the href attribute with your own link. For example, http://www.example.com/supportforums.
3. Save login.jsp.
5. Test your changes:
1. Stop and restart the affected IBM Connections application using the WebSphere Application Server Integrated Solutions Console. In this case, restart all IBM Connections application servers.
2. Clear your browser cache.
3. Load the login page (http://:/homepage/login/ to test your changes.
6. Publish your changes when you are ready to make the changes available to others. In this example, the changes apply across all applications, so update the IBM Connections configuration files. For more information about publishing changes, see 1.4 Publishing customizations with the wsadmin tool.

Adding customized product strings

In the procedure Customizing the login page in 2.1 Matching the user interface to your company brand and policies, you added a section about scheduled maintenance to the login page. To support globalization, you can replace the string "Next scheduled maintenance," in login.jsp with a string in a customized properties file. You add the string to a customized properties file in the <customizationDir>\strings directory and insert references to the strings in the original file, in this case, the login.jsp file.

Tip: There is a specific method for adding and updating strings to Profiles, Communities, and the Home page applications. For an example of how to add a custom string to Profiles, see, 5.2 Specifying labels for attributes. For more information about adding strings in these other cases, see the IBM Connections documentation and search for Adding custom strings for widgets and other specified scenarios.

Before you begin
Create a com.ibm.lconn.core.strings.templates.properties file in the <customizationDir>\strings directory. For an example of how to customize the login page, see the procedure Customizing existing product strings in properties files.

Procedure
In this procedure, you replace a hard-coded string with a new key-value pair product string.

1. Add the string to the customized properties file:
1. Navigate to <customizationDir>\strings and open up com.ibm.lconn.core.strings.templates.properties with a text editor.
2. Add a string on its own line in the form of <string_key>=<string_value>. For example,
   

    login.schedmaint.title=Next scheduled maintenance

3. Save the file.
2. Replace the hard-coded string with the reference to the string key. For example, the text in the login page:
1. Navigate to <customizationDir>\common\nav\templates and open your copy of the login.jsp file in a text editor.
2. Find "Next scheduled maintenance" and replace it with a reference to the string you created. The format is fmt:message key="" />

              <%--
   

              ************************************************************************
   

              Example: Change the informational text
   

              ************************************************************************
   

              --%>
   

              <h2><fmt:message key="login.schedmaint.title" /></h2>           
   

              <p>Thursday, January 12th 2012 from 11:00PM EST to 11:59PM EST.</p>
   

              <%--           
   

              *** End Example
   

              ********************************************************
   

              --%>

3. Save the login.jsp file.
3. Modify strings for a specific language.
   The templates.properties files contains strings for the default (English) language. To create strings for other languages, add the strings and translated values to files with language codes. For example, for Brazilian Portuguese, add the login.schedmaint.title key and translated value to the com.ibm.lconn.core.strings.templates_pt_BR.properties:
   

   login.schedmaint.title=Pr\u00a3xima manuten\u00e7\u00e3o programada

   
   Tip: Strings in IBM Connections use Unicode escape codes for Unicode characters. You escape a Unicode character with \uXXXX, where XXXX is the hexadecimal representation of the character. For more information about Unicode escape codes, see the "Localization with ResourceBundles" article in the Oracle Sun Developer Network at: http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/
4. Test your changes:
1. Stop and restart the affected IBM Connections application using the WebSphere Application Server Integrated Solutions Console. In this case, restart all IBM Connections application servers.
2. Clear your browser cache.
3. Load the login page (http://:/homepage/login/ to test your changes.
5. Publish your changes when you are ready to make the changes available to others. For more information about publishing changes, see 1.4 Publishing customizations with the wsadmin tool.

Customizing product strings in JavaScript files

Although many strings in the user interface are stored in properties files, some strings are stored in JavaScript files. The location where you save the JavaScript files with customized strings is similar to customizing other aspects of the user interface but different from the location for strings stored in property files. In other words, you must save the customized .jsp file in the equivalent customization subdirectory as the corresponding installed files in the application source directories.

Additional tools for customizing product strings

It can be a challenge to figure out which property file contains the string and which JAR file contains the property file. In addition, you must change the locale of your web browser to test translated strings. You might find these utilities useful:

• Finding the property file for a string:
• On Microsoft Windows: Add a PersistentHandler registry key to support searching .jar files, or, use Cygwin or Eclipse.
• On AIX or Linux: Use the included grep command.

• Testing translated strings:

Use a locale switcher tool that changes the locale of the browser without having to install a locale-specific operating system or to change settings in the operating system. An example of a locale switcher tool is the Quick Locale Switcher add-on for the Firefox and Chrome browsers.

Troubleshooting customized product strings

If you have issues with string changes in customized application property files, try these solutions:

Problem: Your modified strings in property files are not displaying in your browser.

Solutions:
• Make sure the customized property file name matches the correct installed Java package name. For example, for the original properties file at <WAS_home>\<application_name.ear>\<application_name_war>\WEB-INF\lib\lc.util.web-3.0.jar\com\ibm\lconn\core\strings\templates.properties, save the customized file as com.ibm.lconn.core.strings.templates.properties. In other words, replace the slashes that represent directory separators with periods in the file name.
• Make sure that you saved the properties file in the <customizationDir>\strings directory. Do not use subdirectories.
• Make sure that the customized key matches the original.
• Restart the affected IBM Connections application. Changes to strings do not display after you clear your browser cache, even when the customization debugging capability is enabled.

Problem: You are not seeing the translated version of a string.

Solution: Make sure that the locale of the web browser matches the language you want to display.

Problem: Your modified strings in JSP files are not displaying in your browser.

Solution: Make sure that you saved the file in the customization directory that corresponds with the directory of the default file.

Customizing file type icons

When you view a list of files in IBM Connections, an icon represents the file. The icon is selected based on the file name extension. You can override the default icons and the extensions associated with those icons. These customized file type icons display in the Files and Communities applications, and in search results for those applications. You can add a file extension to an existing file type icon or add a file extension and associate it with a new icon. You can also associate a different icon with an existing extension.

The file type icon image is displayed using a background image. This technique allows you to customize the image in a CSS file rather than by changing HTML markup throughout the product. To override a file type icon associated with an extension, you copy your icon images to the appropriate customization directory and define style rules to use those icons. As with other user interface customization, you can modify the file type icons for all applications (in this case, the Files and Communities applications) or for a subset of applications. For more information about the file type icons and extensions, see the IBM Connections documentation and search for file type icons and extensions.

Before you begin

• Turn on the customization debugging capability so that you can view your changes without having to restart the IBM Connections server. For more information about customization debugging, see 1.2 IBM Connections customization variables.
• Decide whether you want to replace the logo in all applications or in a subset of the applications. This procedure assumes that you change the logo for all applications. For more information about customizing a specific application, see 1.1 How customization works.
• Create or get access to the icons that you want to use. You need icons in three sizes: 16x16 pixels, 32x32 pixels, and 64x64 pixels.
• Add a file with an .odp extension to IBM Connections so that you can test the changes to the icon.

Procedure
In this procedure, you override the file type icon that is associated with .odp files.

1. Save your images to the customization directory, for example, an images directory in the common customization directory.
1. Create an images directory in the customization directory at <customizationDir>\common\nav\common\styles\.
2. Copy your three image files to the new images directory. For example, Lotus_Symphony_16.png, Lotus_Symphony_32.png, Lotus_Symphony_64.png
2. (Optional) Verify that the images appear in your browser. View the image at http:// <server>:<port>/files/nav/common/styles/images/<imageFileName>.
3. Create a directory named base at <customizationDir>\common\nav\common\styles\.
4. Copy the installed style sheet that controls file type icons to the customization directory:
1. Navigate to the <WAS_home>\Activities.ear\oawebui.war.\nav\common\styles\base directory. Because the sprite-lconn.css style sheet files are identical in all the source directories, you can use the file from application.
2. Copy the sprite-lconn.css style sheet to the common customization directory <customizationDir>\common\nav\common\styles\base\. For more information about the customization directory, see 1.1 How customization works.
5. Override the style sheet for the default theme to match your new logo:
1. Open your copy of the sprite-lconn.css style sheet in the customization directory.
2. Locate the line with the rule for the extensions you want to override. For example, search for .lconn-ftype16-odp to find the rule for files with the .odp extension.
   
3. Delete the references to the extensions in the original rules. Delete .lconn-ftype16-odp, .lconn-ftype32-odp, and .lconn-ftype32-odp from the lines.
4. Add rules to the sprite-lconn.css style sheet to override the installed rules.
   

   /* Replace the standard icon for .odp files with the Symphony logo (a custom image) */
   

   .lconn-ftype16-odp {background-image: url("../images/Lotus_Symphony_16.png") !important; background-position: 0 0 !important;}
   

   .lconn-ftype32-odp{background-image: url("../images/Lotus_Symphony_32.png") !important; background-position: 0 0 !important;}
   

   .lconn-ftype64-odp{background-image: url("../images/Lotus_Symphony_64.png") !important; background-position: 0 0 !important;}

5. Delete all the other rules in the style sheet. IBM Connections loads the default rules from the installed style sheet in the source application directories. What remains in the customized style sheet only is a set of rules that override the default rules.
   
6. Save sprite-lconn.css
6. Test your changes:
1. Clear your browser cache.
2. Navigate to the Files application and view the .odp file you uploaded to test your changes to the icon.
7. Publish your changes when you are ready to make the changes available to others. In this example, the changes apply across all applications, so update the IBM Connections configuration files. For more information about publishing changes, see 1.4 Publishing customizations with the wsadmin tool.

Parent topic: 2.0 Customizing the user interface