Portal Guide
CHAPTER 10
This chapter describes how administrators and end-users can localize portal applications. It covers the following topics:
exteNd Director supports the following locales:
|
Country code |
Language |
|---|---|
|
en |
English |
|
de |
German |
|
es |
Spanish |
|
it |
Italian |
|
fr |
French |
|
ja |
Japanese |
|
ko |
Korean |
|
pt |
Portuguese |
|
ru |
Russian |
|
zh_CN |
Chinese (China) |
|
zh_TW |
Chinese (Taiwan) |
exteNd Director allows administrators and end-users to set locales for a portal, as follows:
|
Role |
Task |
|---|---|
|
Portal administrators |
|
|
End-users |
Select a preferred language for their view of the portal, as described in Selecting a preferred language for the portal. |
Portal administrators can restrict the portal to a subset of supported languages, thereby overriding browser settings. End-users can then choose from only that subset of languages for localizing their view of the portal.
To restrict languages for the portal:
Open the Portal subsystem configuration file.
Find the key com.novell.afw.portal.locale.PreferredLocaleList
By default, the value is an empty list, which means that end-users can choose from all supported locales for localizing their view of the portal.
To restrict the portal to a subset of supported locales, enter a comma-separated list of desired locales in the <value> element.
TIP: Use the country codes listed in Supported locales. For example, if you want end-users to choose only from English, Spanish, French, and German, the descriptor should look like this:
<property> <key>com.novell.afw.portal.locale.PreferredLocaleList</key> <value>en,es,fr,de</value> </property>
If the Directory realm is eDirectory, follow these additional steps:
Define an attribute in eDirectory to contain the preferred locale for the portal.
Make this attribute available to your directory application. In the portal application project, select Project>Director>Configuration, select the User tab, and add the attribute you just defined to the list in the Include User Attributes box.
If the attribute is not called locale, enter the correct name as the value of the key com.novell.afw.portal.locale.MetaName in the Portal subsystem configuration file.
Save the Portal subsystem configuration file.
Select and enable graphical user interfaces with which end-users can select a preferred language, as described in Enabling graphical interfaces for selecting a preferred language.
exteNd Director provides several graphical interfaces for end-users to select a preferred language for their view of the portal. By default, these interfaces are not exposed to the end-user. It is up to the portal administrator to enable one or more of these interfaces as desired. Here are some guidelines:
To enable locale selection in the Login portlet:
Start the DAC, as described in accessing the DAC.
Navigate to portlet registrations, as described in Accessing portlet registrations in the deployed portlet application.
A panel opens in the right content pane, listing all the preferences defined for the registered Login portlet, along with their current values.
On the Preferences tab, set Show Preferred Language UI to True and click Save Preferences.
To enable locale selection in the Portal Personalizer:
Start the DAC, as described in accessing the DAC.
Navigate to portlet registrations, as described in Accessing portlet registrations in the deployed portlet application.
A panel opens in the right content pane, listing all the preferences defined for the registered Personalize portlet, along with their current values.
On the Preferences tab, scroll to Show Preferred Language UI, set it to True, and click Save Preferences.
Now users will be able to select a preferred language in the Portal Personalizer.
To expose the ChooseLocale portlet:
Start the DAC, as described in accessing the DAC.
Navigate to portlet registrations, as described in Accessing portlet registrations in the deployed portlet application.
A panel opens in the right content pane, listing all the settings defined for the registered ChooseLocale portlet, along with their current values.
On the Settings tab, scroll to Hidden from User, set it to False, and click Save Settings.
Grant the appropriate authorizations to use the ChooseLocale portlet by following these steps:
Assign List and Execute permission as needed to the end-users who need to select a preferred language.
TIP: For more information, see Assigning security permissions for portlet registrations.
Add the ChooseLocale portlet to a container or shared page that is accessed by end-users.
Typically, administrators add the ChooseLocale portlet to the end-user's home page—that is, the container and shared pages that display in the browser after the end-user logs in to the portal. In this example, the administrator added the ChooseLocale portlet to the header section of the home container page:
TIP: See Adding content to a container page.
Make sure the page can be accessed by the end-users who need to select a preferred language.
TIP: See Assigning pages to users and groups.
Portal administrators can provide end-users with several methods for selecting a preferred language for their individual views of the portal, as described in Enabling graphical interfaces for selecting a preferred language. Check with your administrator about which methods to use:
|
Method |
How? |
|---|---|
|
Select a language at login |
|
|
Select a language in the Portal Personalizer |
|
|
Select a language from a portal page |
If your portal administrator enabled locale selection at login, follow this procedure:
To select a language at login:
Open a browser and enter the following URL:
http://server name/project context/portal
TIP: For example, if you are running a project called MyProject on a server called localhost, type this URL: http://localhost/MyProject/portal.
The default portal page opens in your browser, allowing you to enter the portal Web tier as a guest user.
Click Login in the upper right corner of the page.
Enter your user name and password, then click Login or press the Enter key.
If your portal administrator enabled locale selection in the Portal Personalizer, follow this procedure:
To select a language in the Portal Personalizer:
Start the Portal Personalizer, as described in Starting the Portal Personalizer.
Scroll to Preferred Language and choose a language from the dropdown menu.
The language you chose becomes the default language for the portal.
If your portal administrator enabled locale selection on a shared or container page, follow this procedure:
To select a language from a portal page:
Open a browser and enter the following URL:
http://server name/project context/portal
TIP: For example, if you are running a project called MyProject on a server called localhost, type this URL: http://localhost/MyProject/portal.
The default portal page opens in your browser, allowing you to enter the portal Web tier as a guest user.
Click Login in the upper right corner of the page.
The exteNd Director Login portlet opens in your browser and prompts you to log in to the portal.
Enter your user name and password, then click Login or press the Enter key.
Your home page opens in the browser.Typically, administrators add locale selection capability to your home page.
If you cannot choose a language from your home page, ask the portal administrator for the name of the page that provides locale selection and navigate to that page.
In this example, you can select a preferred language in the header section of the home page:
Select a language from the Preferred Language dropdown list, then click Go.
The Java Portlet Specification provides detailed guidelines about localizing portlets. This section describes the exteNd Director implementation of the specification. It includes information about how to localize the following kinds of data:
Much of what is presented to the user through portlets is determined by portlet preferences. These preferences can be modified with the preference sheet provided through exteNd Director or through customized access provided via the doEdit method of the portlet.
Consider the MessagePortlet, an accessory portlet shipped out of the box with exteNd Director. Three preferences are defined in the novell-portlet.xml deployment descriptor.
<portlet-preferences>
<preference name = "message">
<data-type>String</data-type>
<required>true</required>
<multi-valued>false</multi-valued>
</preference>
<preference name="height">
<data-type>Integer</data-type>
<required>false</required>
<multi-valued>false</multi-valued>
</preference>
<preference name="width">
<data-type>String</data-type>
<required>true</required>
<multi-valued>false</multi-valued>
</preference>
</portlet-preferences>
Default values for each preference are provided through the portlet.xml descriptor file. Default values provided via this mechanism are referred to as definition-level preferences.
<portlet-preferences> <preference> <name>message</name> <value><![CDATA[<span class="nv-paragraphTextBody"><b>Quote of the Day: <]]><![CDATA[/b><br><br>I do not know what I may ap]]><![CDATA[pear to the world; but to myself I seem to have been only like a boy playing on the seashore, and diverting myself in now and then finding a smoother pebble or a prettier shell than ordinary, whilst the great ocean of truth lay all undiscovered before me. <br><br><b>(Isaac Newton)</b></span>]]> </value> </preference> <preference> <name>height</name> </preference> <preference> <name>width</name> <value>100%</value> </preference> </portlet-preferences>
Adding the MessagePortlet to a shared page, with no additional configuration parameters applied at assignment or registration time, results in the display of the default, English quote from Isaac Newton.
In a localized application, you would need to provide mechanisms for the user to localize the message, as well as the presentation for doing so. This section focuses on the latter.
Using the portlet preference sheet, the administrator (or if given the appropriate rights, the user) can modify portlet preferences. Configuration information such as display names, descriptions, and values are handled through the portlet container and can be localized with the use of resource bundles which are associated with a given portlet in the descriptor resource-bundle element in portlet.xml.
<resource-bundle>com.novell.afw.portal.portlet.message.MessageRsrc</resource-bundle>
The code below shows the structure and contents of the default MessagePortlet resource bundle.
package com.novell.afw.portal.portlet.message;
import com.novell.afw.portlet.api.EbiPortletConstants;
import java.util.*;
/**
* Default resource bundle for Message Portlet
*/
public class MessageRsrc extends ListResourceBundle {
public static final String BUNDLE_ID = "com.novell.afw.portal.portlet.message.MessageRsrc";
public static final String PREF_NAME_TAG = "javax.portlet.preference.name.";
public static final String PREF_DESC_TAG = "javax.portlet.preference.description.";
static final Object[][] contents = {
{ EbiPortletConstants.RESOURCE_BUNDLE_TITLE_KEY, "Message"},
{ EbiPortletConstants.RESOURCE_BUNDLE_SHORT_TITLE_KEY, "Display messages in regular text or HTML"},
{ EbiPortletConstants.RESOURCE_BUNDLE_DESCRIPTION_KEY, "Display messages in regular text or HTML"},
{ EbiPortletConstants.RESOURCE_BUNDLE_KEYWORDS_KEY, "message, text, html"},
{PREF_NAME_TAG+"message", "Message"},
{PREF_DESC_TAG+"message", "Message to display in portlet. It can include text and HTML markup"},
{PREF_NAME_TAG+"height", "Height"},
{PREF_DESC_TAG+"height", "Desired height of table containing the message"},
{PREF_NAME_TAG+"width", "Width"},
{PREF_DESC_TAG+"width", "Desired width of table containing the message, can be percentage."},
};
/**
* Gets the object array.
*/
public Object[][] getContents() {
return contents;
}
}
The message resource bundle above extends ListResourceBundle and the bundle id is provided as a static member variable. The bundle contains one method which returns a two dimensional object array with key value pairs provided in the bundle.
Using exteNd Director, configuration display such as preference names and descriptions for a portlet can be localized in the preference sheet simply by utilizing standard naming conventions. For example, providing the key value pair below and associating the resource bundle with the portlet in the portlet.xml will allow the portlet container to display a localized description of the message preference in the portal preference sheet.
{PREF_DESC_TAG+"message", "Message to display in portlet. The message may include text and HTML markup"},
By providing a resource bundle for each supported locale (Spanish in this example), you can provide localized display of preference names and descriptions.
package com.novell.afw.portal.portlet.message;
import com.novell.afw.portlet.api.EbiPortletConstants;
import java.util.*;
/**
* Spanish resource bundle for Message Portlet
*/
public class MessageRsrc_es extends ListResourceBundle {
public static final String BUNDLE_ID = "com.novell.afw.portal.portlet.message.MessageRsrc";
public static final String PREF_NAME_TAG = "javax.portlet.preference.name.";
public static final String PREF_DESC_TAG = "javax.portlet.preference.description.";
static final Object[][] contents = {
{ EbiPortletConstants.RESOURCE_BUNDLE_TITLE_KEY, "Mensaje"},
{ EbiPortletConstants.RESOURCE_BUNDLE_SHORT_TITLE_KEY, "Mostrar mensajes en texto normal o HTML"},
{ EbiPortletConstants.RESOURCE_BUNDLE_DESCRIPTION_KEY, "Muestra los mensajes en texto o HTML"},
{ EbiPortletConstants.RESOURCE_BUNDLE_KEYWORDS_KEY, "message, text, html"},
{PREF_NAME_TAG+"message", "Mensaje"},
{PREF_DESC_TAG+"message", "Mensaje que se mostrará en el portlet."},
{PREF_NAME_TAG+"height", "Altura"},
{PREF_DESC_TAG+"height", "Altura deseada de la tabla que contiene el mensaje"},
{PREF_NAME_TAG+"width", "Width"},
{PREF_DESC_TAG+"width", "Anchura deseada de la tabla que contiene el mensaje."},
};
/**
* Gets the object array.
*/
public Object[][] getContents() {
return contents;
}
}
A browser specifying es (or a variation such as es-mx) in the request header, would trigger the retrieval of Spanish labels and descriptions from the resource bundle above in the portlet preference sheet, without additional coding required in the portlet or the framework.
When the browser specifies a locale (es in this example), the container will search for the preference label name and descriptions in the following order (using the preference hierarchy):
The container looks for the key in the es resource bundle (bundle name MessageRsrc_es.java). If the key exists, it displays the value for that key. If secondary locales are presented on the request header, the container also attempts to retrieve the keys in the user's preferred order.
If no keys are found in the specified resource bundles, or the resource bundles do not exist, the container looks for the key in the portal's preferred locale resource bundle. The "Preferred Locale" can be changed in the PortletService's config.xml by changing the value of the property with the key named PortletService/preferred-locale. exteNd Director ships with en as the preferred locale, so in this case, the container would look for the key in the MessageRsrc_en.java bundle.
Finally, the container looks for the key in the default bundle, in this case MessageRsrc.java.
So far, the discussion has centered around the localization of configuration display information such as labels for and descriptions of preferences in the preference sheet. Generating a localized message through a portlet using preference values (such as in the MessagePortlet) requires localization of the preference itself. This topic is described in the next section.
You can localize preferences at definition, registration, and page assignment time. Consider the MessagePortlet as an example. The MessagePortlet generates XML. In this case, the message itself is a preference, and is retrieved from the RenderRequest object provided to the doView method of the portlet.
//get the preference object from RenderRequest
javax.portlet.PortletPreferences prefs = req.getPreferences();
//add the message element to emitted XML. Document creation steps ommitted
e = baseDoc.createElement("message");
e.appendChild(baseDoc.createCDATASection(prefs.getValue("message","")));
rootNode.appendChild(e);
Because localization of preferences and proper retrieval from the preference hierarchy is also handled by the portlet container, by the time the message is wrapped in the CDATA section of the XML output, it has already been retrieved from the hierarchy and been localized appropriately.
Preferences exist in a multi-level hierarchy, where each level lower in the hierarchy of preferences can override preferences defined at higher levels. The lower the level in the hierarchy, the more user-specific the preference. There are four levels:
The administrator can localize messages at the top three levels.User level preferences are not localized since it is assumed that the user will always want to see the values entered verbatim, and not have these change based on browser locale.
The definition level is the highest level of preferences. It is generated at runtime based on the preferences declared in the portlet.xml and resource bundles. All registrations and instances of a portlet will start out with these same preferences. These preferences can not be changed at runtime, but may be overridden at lower levels.
The definition level preferences can be viewed in the Director Administration Console under the Portlet Management section. For each deployed portal application, all portlets that are defined in portlet.xml will be available in the portlet tree for selection. When you drill down through the tree and select a portlet, the configuration information contained in the portlet.xml for the given portlet is displayed as read-only values. An administrator can not change values in the Portlet Definition screen in the DAC; the portlet.xml must be changed explicitly. The Portlet Definition screen in the DAC shows where a unique instance of a portlet is identified and registered with the portal application. The portlet's initial preferences are pulled from portlet.xml.
In the unlikely scenario that localized preferences must be set at definition time, developers can follow the example of the WelcomeMessagePortlet. In the portlet.xml for the WelcomeMessagePortlet, the message preference value is set to welcome. This welcome value is part of a key found in the WelcomeMessageRsrc resource bundle. Thus at definition time (in the portlet.xml), a preference can be localized by creating a specific resource bundle for this definition, localizing each subclass bundle as described previously, and setting localized preference values there.
The registration level is the second highest level of preferences. The registration level preferences inherit from the definition level. Registration level preferences can be changed during the registration of a portlet (done in the DAC by the administrator). Each registration of a portlet can override preferences defined at the definition level independently of one another.
Simple preferences Simple preferences are preferences that have data types other than Complex (such as String, Boolean, and Select). The MessagePortlet, for example, uses simple preferences. In the DAC, when you drill down to the MessagePortlet in the tree and select the MessagePortlet registration, the Portlet Definition screen will appear. Each registered instance of the message portlet will appear when you expand the MessagePortlet in the tree. Each registered instance is denoted with a green flag and the unique instance name which was assigned in the portlet definition:
In this case, the unique instance name is the same as the portlet name, MessagePortlet. When the unique instance of the portlet is registered, then the configuration information is pulled from the definition level settings for the portlet and can be modified by the administrator in the DAC on the Portlet Registration page. Included in the configuration information are five tabs: General, Categories, Settings, Preferences, and Security. To localize a portlet, you work with the following tabs in the Portlet Registration:
In the Settings tab, the content title is localized as shown below:
In the Preferences tab, the preferences defined for the portlet are available for modification. The initial page displayed allows the administrator to set the default locale preferences for the specific content instance only. The default locale preferences are set on the initial page, as shown below:
To assign localized preferences, you need to select the detail link for the preference you want to modify. On the Content Preferences page, the administrator can create a new localized preference for each supported locale or modify existing localized preferences for the registered instance. These preferences are persisted in the database at the registration level. When a portlet is assigned to a shared page, the preferences that were provided at registration can be overridden. For example, if the Message preference is selected, the following screen is presented for changing registration level preferences:
For each preference, the label, value, and description can all be localized.
Complex preferences Complex preferences are preferences that go beyond the simple preferences. Complex preferences have a user-defined interface, so they do not follow the same user interface as simple preferences. Complex preferences are identified and associated with an editor in novell-portlet.xml. For example, the following entry for the SurveyPortlet associates the SurveyComplexPredEditor Portlet with the survey-data preference.
<preference name="survey-data"> <data-type>Complex</data-type> <required>true</required> <config-portlet>SurveyComplexPrefEditor</config-portlet> </preference>
Like other portlets, there is also an entry in portlet.xml for the complex preference editor. Unlike the simple preferences, complex preferences will only have localization defined for the Settings tab; hence, you will only localize the content title. There will be no information in the Preferences tab for a complex preference, because a complex preference is a type of preference that will be included in the definition for the portlet itself.
Consider the example below:
On the left hand navigation pane, Survey is the main portlet and SurveyComplexPrefEditor is the portlet that handles the editing of the complex preference. In the screen shown above, you can see that Survey Details has a different link than the rest of the preferences. This is because Survey Details is a complex preference. Its user interface is handled in SurveyComplexPrefEditor.java, which is accessed by clicking the View/Edit Custom Preference link. After clicking the link, you can change registration level preferences, just as you would change complex preferences at assignment time.
For more information, see Complex preferences under Setting localized preferences at page assignment time.
The page assignment level is the third highest level of preferences. Assignment time occurs when a portlet is placed on a page. At assignment time, any default, writable preference can be modified.
The assignment level is the lowest level at which text can be localized.
Simple preferences Simple preferences are preferences that have data types other than Complex (such as String, Boolean, and Select). The MessagePortlet uses simple preferences that can be localized at assignment time. For example, if a message portlet is placed on a shared page, the default message can be overridden. To override the default message, the administrator can modify the portlet preferences established at definition or registration by selecting the Content Preferences link. On the Content preferences page, the default preference values for the portlet are displayed.
To assign localized preferences, select the detail link for the preference you want to modify. For example, if you select the Message preference, the following screen is presented:
In the above case only the default message has a value assigned. The administrator can create a new localized preference for each supported locale from this page. For each preference, the label, value, and description can all be localized. If the administrator created a localized preference in Spanish for this instance of the message portlet, when the portlet is rendered in the portal via the browser and the default language preference defined in the browser settings is Spanish, then the portlet container will retrieve and display all message content in Spanish.
If the message preferences have not been localized by the administrator for a particular locale, then the preference will be retrieved from the hierarchy via the rules discussed earlier. This page is analogous to the Content Preferences page in the DAC, which is used when a portlet is registered.
Complex preferences Complex preferences have a user-defined interface, so they do not follow the same user interface as simple preferences. Instead the developer may decide how to store the localized preferences using the com.novell.afw.portlet.api.* API.
Several of the accessory portlets that ship with exteNd Director have complex preferences, including Shortcut, HTML, Topics, NewsGroups (NNTP), and Survey. All complex preferences in the accessory portlets are stored as XML DOM Strings and are commonly referred to as complex preferences. For every complex preference, there is a portlet to handle the editing of the preference (for example ShortcutComplexPrefEditorPortlet.java).
Each of the xxxComplexPrefEditorPortlets extends com.novell.afw.portal.portlet.util.ComplexPrefEditorPortlet and utilizes methods in com.novell.afw.portal.portlet.util.ComplexPrefUtil. Together, they handle the storing of localized complex preferences. The user interface resembles the screen shown below:
First, the user must select the locale. Then, the user edits the complex preference for that locale. The complex preference editor for the ShortcutPortlet (link preference) is shown below for reference.
Some text requiring localization is not be stored as a preference. Validation and error messages are examples of this kind of text.
Messages used by portlets can be stored in and retrieved from resource bundles. For example, if the message portlet were modified to allow for message input through the doEdit mode of the portlet, localized validation messages could be generated in the portlet doEdit mode and added to the portlet's XML output by using the resource bundle, as shown below:
//get the appropriate resource bundle.
ResourceBundle resource = ResourceBundle.getBundle(MessageRsrc.BUNDLE_ID);
// No message provided by the user. Retrieve localized validation message
String validationMessage = resource.getObject("validation.error.message.required").toString();
//add validation message to XML output – baseDoc creation ommitted
e = baseDoc.createElement("validation-message");
e.appendChild(baseDoc.createTextNode(validationMessage));
rootNode.appendChild(e);
Within each resource bundle, the validation error message is localized by pairing the message with the appropriate key:
//message in the default resource bundle
{"validation.error.message.required", "Message is required."},
//message in the es resource bundle
{"validation.error.message.required", "Mensaje es necesario"},
The localized validation in the XML output is then trapped and displayed to the user in the style sheet of the associated portlet:
<!-- Display any validation errors --> <xsl:if test="validation-message"> <xsl:value-of select="validation-message"/> </xsl:if>
References to images, alt tags, and other resources within the XSL also require localization.
In order to take advantage of transformation by the container, a portlet must link to the style sheet in the novell-portlet.xml deployment descriptor. In the case of the NetworkFile portlet, the style sheet is specified in this manner:
<user-agent>
<device-name>Generic_HTML</device-name>
<file-name>$RESOURCE_SET$/portal-style/NetworkFilePortlet.xsl</file-name>
</user-agent>
The NetworkFilePortlet.xsl contains a pointer (an xsl:include) to the XSL file containing localized variables. The appropriate file (NetworkFilePortlet_es.xsl, etc.) is included at runtime based on the user's specified locale:
<xsl:include href="NetworkFilePortlet_locale.xsl"/>
The NetworkFilePortlet.xsl contains the following element for message display to the user to confirm deletion when navigating the file system via the portlet:
<xsl:value-of select="$TextDeleteConfirmHint" />
In the event that the default is triggered (no other messages in the user's specified locale were found), the following variable definition is pulled from NetworkFilePortlet_locale.xsl, and the message is displayed in English:
<xsl:variable name="TextDeleteConfirmHint">Please verify these are the items to be deleted</xsl:variable>
If es is specified, the following is pulled from the variable defined in NetworkFilePortlet_es.xsl, and the message is displayed in Spanish:
<xsl:variable name="TextDeleteConfirmHint">Compruebe que estos son los elementos que desea suprimir</xsl:variable>
In this case, all of the XSL files are located at the root of the portal-style directory.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...