Chapter 34 Localization: Templates and JSPs

This chapter contains the following sections:

• Desktop Templates

• File Lookup Mechanism

This chapter addresses the Desktop templates and JSPs in the Portal Server software that can be translated to support localization.

Desktop Templates

This section contains:

• Template Files

• JavaServer Pages

• Image Files

Template Files

The /var/opt/SUNWportal/portals/portal-ID/desktop/desktoptype directory contains templates that are used to generate the Desktop pages. For each directory contained in this directory, a new directory for the locale must be created. The directory name must contain the existing directory with an underscore and the name of the locale; for example, /var/opt/SUNWportal/portals/portal-ID/desktop/default is translated to /var/opt/SUNWportal/portals/portal-ID/desktop/default_locale.

All of the file names can remain the same. Only files that require translation must be created in the locale-specific directory. If a file is not found in the locale-specific directory, it is automatically taken from the directory that does not have the locale specifier.

Template files are mostly markup text with embedded tags that specify substitutions to be performed at runtime. The tags have the form [...]. The tags should not be modified during the translation process.

Each template file is encoded using Java Unicode encoding where non-ASCII characters are represented with \\uXXXX notation. Here the \\uXXXX is the hexidecimal representation of the Unicode value for the character. This type of file can be created from a native file using the Java native2ascii program available in the JDK 1.5 package that is shipped with the Portal Server software.

JavaServer Pages

JSP files end with the .jsp suffix. The encoding for each top-level JSP file is specified using a header at the top of the file. The header appears as the following:

<%@ page contentType="text/html; charset=encoding" %>

where encoding is the desired encoding such as UTF-8 or EUC-JP. Note that this is only for top-level JSP files. JSPs that are statically included by other JSPs must use the encoding of the including JSP. That is, JSPs that are statically included by other JSPs using

<%@ include file="relativeURL" %>

must use the encoding of the including JSP. JSPs that are dynamically included using:

<jsp:include page="{ relativeURL | <%= expression %>}" flush="true" />

must have their own page directive that contains the encoding.

Image Files

If image files referenced by the existing templates are inappropriate for a locale, the references can be changed to refer to new files. The new file must be placed in the document root of the web container at PortalServer-base/web-src directory and then deploy it with the PortalServer-base/bin/psadmin deploy sub command. Or, you can deploy a new WAR file into the location of your choice.

File Lookup Mechanism

Desktop content can be customized based on the following factors:

• Desktop type

• Locale

• Client type

The DesktopServlet performs a search for a localized file before selecting a default. In order to perform the search, the DesktopServlet uses the user’s locale attribute in the user’s directory entry (or preferredLocale attribute in the Sun Java System Access Manager) and searches for the file. The user’s directory entry stores the user’s preferred locale in the preferredLocale attribute. The value of this attribute must be in the standard International Organization of Standards (ISO) locale format. For example, for the United Kingdom, this code is en_UK.

Locales are searched from more to less specific. For example, for a locale setting of en_US_WE, the search order would be: en_US_WE, en_US, en. If the locale-specific property is not found, then the non-locale-specific version is returned (if it exists).

The /var/opt/SUNWportal/portals/portal-ID/desktop directory stores the directories that present the desktop content. In the administration console, this is referred to as desktop type. The portal customizer can include different sets of files to alter the appearance of the desktop for different groups including localizations. The portal customizer must create a directory that contains the localized content at the same location (as the default content) and append the ISO locale code to the directory name.

Developing and Deploying JSP or Template Files

The Enterprise Sample JSP and template files are located in the PortalServer-DataDir/portals/portal-ID/desktop/enterprise_sample directory. The JSP and template files can be copied to a custom directory and modified by the developer or the developer can create new JSP or template files for their deployment.

For the JSPs, you can find compilation and runtime errors in the desktop debug log at PortalServer-DataDir/portals/portal-ID/logs/portal-instance/portal.0.0.log. Also, all JSPProvider based Desktop channels have a property called showExceptions. By default, this property is set to false; setting it to true causes the JSP exception to show up as the content of the channel.

When you create a container, you need to create a new subdirectory for your newly created container in the PortalServer-DataDir/portals/portal-ID/desktop/desktopType directory. That is, the newly created container should be placed based on what the desktopType is. If the Enterprise Sample portal is installed, then the desktopType is, by default, enterprise_sample; so, create a new directory for the container under enterprise_sample so that any JSP and template that is being added can adopt the same look and feel that as defined in the sample portal. If sample portal is not installed, and if you have set up a custom desktopType, for example, foo, then the new container directory must be created directly under foo.

Either copy the modified JSP or template files here, or place your newly created files here. If you use a sample container without changing any content or file names, you do not need to create a new subdirectory nor copy any files there. (In the example that follows, a new subdirectory is needed, because a new container is created.)

For example, let’s say you create a new container called newSingleContainer whose display profile definition is the following:

<Container name="newSingleContainer" provider="JSPSingleContainer">
    <Properties>
        <String name="helpURL" value="desktop/newSingle.html"/>
        <String name="title" value="A new single container"/>
        <String name="contentPage" value="newsinglecontent.jsp"/>
        <Boolean name="isEditable" value="true"/>
        <String name="editType" value="edit_subset"/>
    </Properties>
    <Available/>
    <Selected/>
    <Channels/>
</Container>

Because the file specified for the contentPage property is different from the contentPage value for the provider definition, you need to create a new directory under the PortalServer-DataDir/portals/portal-ID/desktop/enterprise_sample directory called newSingleContainer. You then only need to copy the newsinglecontent.jsp file to this new directory. The system is able to locate all other JSPs referenced by the JSPSingleContainer provider.

If desired, rather than customizing the sample portal JSP and template files directly, you can create a separate directory for your organization’s customized files, and perform customization on those files. This preserves the initially installed portal JSP and template files.

To Create Customized Organization JSP and Template Files

1. Change directories to the Desktop JSP or template directory.

   For example,

   cd PortalServer-DataDir/portals/portal-ID/desktop

2. Create a new directory for your organization’s JSPs and templates.

   For example,

   mkdir sesta

3. Copy the JSPs and templates that you wish to modify into the new directory location, maintaining the same directory structure.

   For example, if your new Desktop type will modify PortalServer-DataDir/portals/portal-ID/desktop/default/JSPProvider/content.jsp, copy this file to PortalServer-DataDir/portals/portal-ID/desktop/sesta/JSPProvider/content.jsp, and customize the file for the new Desktop type in that location.

4. Customize the JSPs templates in the sesta directory as required.

5. Change the dynamic Desktop Type attribute in the Portal Server software administration console to use the newly created directory.