This article aims to show you how to easily setup your XPages application to support bidirectional (bidi) scripts, e.g. Arabic and Hebrew.
Supporting bidi or right-to-left locales is important for any company as you reach and cater for a larger audience.
In this article you will learn how to add a theme, stylesheets(css) to support both left-to-right (ltr) and right-to-left (RTL) scripts, and also how to handle some of the issues you may encounter along the way.
Bidi Support
Firstly, I'll briefly describe what a theme is. A theme is used to define the look and feel of an application. They can be set globally (all applications) or per application. A theme is handled on the server side and drives the page creation and HTML generation.
There are two themes shipped with Lotus Domino Server, webstandard and OneUI, both of which support right-to-left locales. To use one of these themes, you can either change the server default by modifying the xsp.theme value in the xsp.properties file (
<domino_directory>\xsp\nsf, to webstandard or oneui) or specify one of the themes in the application properties, Figure 1.
Figure 1 - Setting one of Domino Servers shipped themes, webstandard and OneUI, to be the Default theme
To add a theme to your application:
- Open/Create an XPages application
- Expand the Resources node in the Applications navigator.
- Right-click on Themes and select New Theme...
- Enter a name and click ok.
To use this theme instead of the server default, open the Application properties and select your theme from the Default theme combo box.
In the Source tab of the theme, you will see example XML for defining CSS files in the resources section and adding properties for controls.
Add a resource to define the main CSS file used in the application, set the content-type to “text/css” and the hyperlink(href) to the name of the stylesheet, e.g. style.css. An example of the XML for adding a resource can be seen in XPages Sample Code 1:
<resource>
<content-type>text/css</content-type>
<href>style.css</href>
</resource>
XPages Sample Code 1 – Adding a resource
Those resource can have a conditional expression, for example based on the bidi mode. A developer can then provide different CSS files depending on the text alignement. So adding support in the theme file for bidirectional locales, involves a simple JavaScript call,
context.isDirectionRTL()
or
context.isDirectionLTR()
, which checks the value of the
dir
property in the XPage.
XPages Sample Code 2 shows the XML for adding the CSS files which will have left-to-right and right-to-left specific styling.
XPages Sample Code 2 – Adding support for bidirectional locales
Figure 2 shows an example of a bidirectional XPage application. Create a new XPage, add a panel including some text.
Figure 2 - Bidirectional XPage Application
XPages Sample Code 3 shows the classes which have been added to the stylesheets:
style.css
.bidiPanel {font-size:12pt;; font-weight:bold;}
bidiLTR.css
.bidiPanel{
float:left;
background:url(background.jpg) no-repeat scroll left top;
}
XPages Sample Code 3 - Sample CSS for left-to-right script
In style.css, add the general properties that aren't affected by the locale, e.g. I have added font attributes. In bidiLTR, where all the left-to-right specific styling will be placed, I have left aligned the text within the panel and specified a background image which has a curved corner on the top left. To apply the bidiPanel class to the panel see Figure 2 above. Also within the application, I have set the left padding of the panel to 15pixels. The rendered left-to-right XPage can be seen in Figure 4 and the rendered XPage source code below.
NOTE: There are some CSS properties and HTML controls that will change depending on the bidi mode, e.g. by default in left-to-right mode text on a page is left aligned. When the page is rendered in a right-to-left mode the text will now be right aligned. A table is an example of a HTML control which is displayed differently depending on which mode it is in. In ltr mode, as to be expected you read the table cells from left-to-right, in RTL mode the table is flipped so you are now reading the table cells from right-to-left, Figure 3.
Figure 3 - HTML table flipped in RTL mode

Figure 4 - Rendered left-to-right XPage
In Figure 4 we can see that the text within the panel is left aligned and is indented because of the padding-left property being set to 15pixels, also the background image is left positioned.
The source code below, XPages Sample Code 4, shows the two new CSS files included. The bidiLTR.css was added because the locale of the browser is set to English, therefore
context.isDirectionLTR()
returned true and
context.isDirectionRTL()
returned false.
<html lang="en">
<head>
<title></title>
<script type="text/javascript" ...></script>
<script type="text/javascript" ...></script>
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xsp.css">
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xspLTR.css">
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xspFF.css">
<link rel="stylesheet" type="text/css" href="/Bidi.nsf/style.css">
<link rel="stylesheet" type="text/css" href="/Bidi.nsf/bidiLTR.css">
</head>
<body class="xspView tundra">
<form id="view:_id1" method="post" action="/Bidi.nsf/Bidi.xsp" class="...>
<div style="padding-left:15.0px"class="bidiPanel">
hello world
</div>
XPages Sample Code 4 - Source code from Figure 3
Next to add support for right-to-left locales, in bidiRTL.css add the following class:
.bidiPanel{
float:right;
background:url(background.jpg) no-repeat scroll right top;
}
Set the browser to a right-to-left locale, e.g. Arabic or Hebrew, by changing the browsers language then preview the XPage, Figure 5.
Figure 5 - Rendered right-to-left XPage with display errors
As you can see in Figure 4, this is not the desired display you want to see. The background image is the wrong way around and the text is not indented.
When creating images that are designed to look a certain way, e.g. the background image above, you should think about creating an alternative right-to-left image. This can be easily accomplished by horizontally flipping the image in an image editor. So now I have created a specific right-to-left image called backgroundRTL.jpg that is a mirror image of background.jpg.
For the padding issue it may be a better idea to set those type of properties, e.g. padding, margin, etc., into the relevant CSS files. So remove the padding-left value from the panel properties and set it in bidiLTR.css and bidiRTL.css instead. Now bidiLTR.css will have the added declaration,
padding-left:15px
, and bidiRTL.css will have a new declaration for the right padding,
padding-right:15px
.
The right-to-left bidiPanel class should be the opposite to what is in bidiLTR.css. So, for example, where you have a
text-align: left
change it to a
text-align:right
, a
float:right
change it to a
float:left
, a
padding-left
replace it with
padding-right
, and where you have an image that is distinctive to one side you should flip it, and so on, this can be seen in the three stylesheets discussed in this article, XPages Sample Code 5.
style.css
.bidiPanel {font-size:12pt; font-weight:bold;}
bidiLTR.css
.bidiPanel {
float:left;
background:url(backgroundLTR.jpg) no-repeat scroll left top;
padding-left:15px;
}
bidiRTL.css
.bidiPanel {
float:right;
background:url(backgroundRTL.jpg) no-repeat scroll right top;
padding-right :15px;
}
XPages Sample Code 5 – Full CSS from the three stylesheets used in the application
Figure 6 shows the correct layout and styling for Bidi.xsp, the padding has now being applied to the right with padding-left value set, the background image for the panel uses the right-to-left image, and the text is right aligned.
Figure 6 - Right-to-left XPage rendered correctly
The source code below, XPages Sample Code 6, shows that the bidiRTL.css file is now used instead of its left-to-right brother. This is a result of the browser being set to a right-to-left locale, the
lang=”ar”
means the language-code for the page is set to Arabic.
<html dir="rtl" lang="ar">
<head>
<title></title>
<script type="text/javascript" ...></script>
<script type="text/javascript" ...></script>
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xsp.css">
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xspRTL.css">
<link rel="stylesheet" type="text/css" href="/domjava/xsp/theme/webstandard/xspFF.css">
<link rel="stylesheet" type="text/css" href="/Bidi.nsf/style.css">
<link rel="stylesheet" type="text/css" href="/Bidi.nsf/bidiRTL.css">
</head>
<body class="xspView tundra">
<form id="view:_id1" method="post" action="/Bidi.nsf/Bidi.xsp" class="...>
<div class="bidiPanel">hello world</div>
XPages Sample Code 6 – Source code from Figure 6.
The other stylesheets included in the source are from the webstandard theme, which are imported because the theme created in the application extends the Domino Servers webstandard theme,
<theme extends="webstandard"
.
TIP: In Domino Designer, each individual control and XPage can be given a direction property, overriding the direction of the page. To do this, click on the control or XPage, select the All Properties section under the Properties tab and set the
dir property to Left to right or Right to left, Figure 7.
Figure 7 - Setting the direction for an individual control or XPage
Summary
You should now have a good understanding of how to support bidirectional scripts and quickly and easily be able to setup your application to support the numerous locales whose content flows from right-to-left.
Remember to watch out for the properties which may be set, in Domino Designer, in the controls and not in the stylesheet, e.g. padding, margins, etc. Also be careful of images which are designed to look one way, e.g. they may have curved borders on one side, try flipping the image horizontally.
Resources
- Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content
- XPages: How to use the localization options
- XPages: JavaScript Internationalization
- What gets automatically added to an XPages property file for translation?
- Time Zone and Locale use in XPages