Projects:RTL/Functional Specifications
Contents |
Right To Left writing support in Openbravo ERP
Overview
Purpose
Nowadays Openbravo ERP is a multi-language software. In fact, there exists translation projects for more than 30 different languages. One of the languages in which application is completely translated is the Arabic one. Arabic language is “written in a form known as right-to-left (RTL), in which writing begins at the right-hand side of a page and concludes at the left-hand side. This is different from the left-to-right (LTR) direction used by most Western languages.”[1] Moreover, not only Arabic language is written in this format, but also dozens of languages used in a lot of north-African, Middle Eastern and Asian countries.
This project's aim consists of adapting Openbravo ERP to support languages that are written from right to left. Kenzo Repole - Openbravo partner and localizer for Saudi Arabia - has developed a 2.35 application with a cool RTL aspect, just modifying css, html and javascript files in the webapps folder of Tomcat. The result is:
In order to obtain this aspect, these changes where made:
- For every html document, the attribute 'direction=”rtl”' was added to every <html> tag. [2]
- Login_FS.html file was modified, changing the name and width of the frames.
- Utils.js file was changed: changing the frame that must be hidden when pressing the arrow button between frames.
- Some css files of the skin where modified: alignment of text, table's borders values, ...
At this point, almost all issues encountered for giving a RTL aspect to Openbravo ERP are identified. As this work was made directly on the compiled files of Tomcat's webapps folder, this changes are not persistent, and this work must be applied to the source files. At the same time, this changes must be dynamic: if the application has a RTL language set, and then it changes to a LTR language, then all changes must be rollbacked. Exists some other aspects that must be noted, such as grid behavior -write header's texts from right to left, enlarge column's width when dropping header to the left, and not to the right-.
This project will study and apply all the necessary changes in the Openbravo ERP code, so translations that need a RTL application look are supported in version 2.50.
Scope
A priori, the development of this project will involve, at least, this actions:
- Add a “direction” attribute to the translations, with two possible values: RTL and LTR, and create a session variable that contains this flag, updated every time the user changes the language.
- Modifications in the wad code so, depending on the “Text Direction” session variable value, adds the attribute 'direction=”rtl”' or 'direction=”ltr”' in every html tag. [2]
- Modifications in the manually generated html pages, so all of them sets the dir attribute depending on the “Text Direction” session variable value.
- Modifications in the login page's frames.
- Changes in the way skins are managed.
Design Considerations
A new attribute must be added to all application languages: direction. This attribute will be mandatory, and will be set to one of this two values: RTL or LTR.
When a user logs in the application, a session variable “Direction” will be fulfilled with the direction attribute value of the used language.
It has been written in the Overview section that the main changes performed in the application files, to write it in a RTL way where:
- For every html document, the attribute 'direction=”rtl”' was added to every <html> tag. [2]
- Login_FS.html file was modified, changing frames' name and width.
- Utils.js file was changed: changing the frame that must be hidden when pressing the arrow button between frames.
- Some css files of the skin where modified: alignment of text, table's borders values, ...
Let's see how can this project perform each of these actions in Openbravo ERP code:
(1). Add into html code the “dir” tag
Here two different actions must be differentiated. Those to be performed in WAD-generated windows, and those that must be performed in the manually created windows.
- WAD engine must add a tag in the html code: the attribute direction, setting the value depending on the “Direction” session variable value.
- The manually created html files must accept a new parameter, and set the attribute direction depending on the “Direction” session variable value.
In order to follow the html version 5 standard definition, maybe the direction attribute must be set in the body tag, more than in the html tag.[3]
If a RTL language is set, then the menu must be located at the right part of the window, and not in the left part, as in a LTR language. Moreover, the menu width must be a 25% of the page width, no matter if it is located at the right or left part of the window. Currently, the frames are set in the Login_FS.html file, and ones the user has logged in, there is no change in this frame sets.
The proposed solution is to develop two different pages to set the frames, one for an RTL aspect:
and another, as it is currently, for LTR languages:
so depending on the chosen language, jump to one page with one frame set or another. When changing the language in the application, change the parent page, to the RTL frame set one, or the LTR frame set one.
Two issues are detected here:
- How to name the frames: the menu frame is always called the same way, or the left frame is always called the same way.
- Implications with the hidden frame.
The first issue will affect to the changes to be made in the Javascript file that shows/hides the menu.
Here, it can be useful to develop a new login page, where user can choose the language in which the page is printed, so he starts already in a RTL or LTR frame set, depending on the login language.
(4). Changes in the skins
Depending on the language direction, some css files must be different. For example: change padding, float and margin values so objects keep a bigger margin at the right, and not at the left; also changing the text-align values, background values of images is required, amongst other changes.
To afford this, the compilation process may create two sub-folders for each skin: one for RTL languages, and another for LTR languages. In the one for RTL languages, some all the changes in text-align, background, padding and margin values should be done. If it's not easy to automatize this changes, then they will have to be done manually, and check when changing to a RTL language, if the current skin supports RTL, otherwise show an error, besides the fact that effort needed to maintain skins will double.
Exists one more point about the skins: some images of the skin must be flipped horizontally in the skin, if a RTL language is set. It can be done also during the compilation process: under the RTL sub-folder of the skin, take the png files, and flipped it horizontally with help of a graphics management Java class, such as the Graphics2D class[4].
The last step of this issue is to make pages use one skin or another, depending on the “Direction” session variable value. This can be done if xml engine, when pasting this “link” tag in web pages
<link rel="stylesheet" type="text/css" href="../../../../../web/skins/Default/Main/Main_Manual.css" ...
adds a subfolder in the href path:
<link rel="stylesheet" type="text/css" href="../../../../../web/skins/RTL/Default/Main/Main_Manual.css" ...
depending on the “Direction” session variable value.
Please note that currently, any language can be set, in combination with any skin. There are no restrictions, because both things are completely independent in the application. If possible, the RTL implementation must preserve this independence.
Functional Requirements
User Roles & Profiles
This changes will affect to every user of the application, that want to use a translation in an RTL format language.
All localizers developing a translation of Openbravo ERP to a RTL written language, should take into account all changes performed by this project.
All developed skins for the application may be affected.
Business process definition
- Users compiles application, and when skin is copied from sources, then two sub-folders are created: ltr and rtl. This task is invoked from src/build.xml build local context task.
- In the ltr folder, the whole skin folder is copied.
- In the rtl folder, the whole skin folder is copied, and modifications necessary for giving application an rtl aspect are performed with java code.
- User creates a new language in the application, and all fields are filled in. One of them is RTL language. This alerts that when this language is set, the application must be shown in a RTL aspect.
User story
The multinational company 'Conservas El Gordo & Co Ltd.', located in London, has been using Openbravo ERP for five years. After some months of negotiations, the company acquires the Jordan company 'Amman Ltd.', and want this to work, also, with Openbravo ERP. The only change to be performed in the server -located in London's headquarters-, is to import the Arabic translation. It will be shown in a RTL aspect in browsers of users in Jordan.
Functional requirements based on business processes
Modifications in the skins
Num | Requirement | Importance | Status |
1.1 | Ant tasks must be modified so some actions will have to be taken while running translation tasks. | Must have | Complete |
1.2 | New java class in the src-trl source files, for performing necessary changes to the rtl skin folder. | Must have | Complete |
1.3 | Find and replace all the relative paths to the skin, to fit new folder structure: new subfolder to reach the skin (ex: ../../skins/Default/ to ../../skins/ltr/Default/) | Must have | Complete |
1.4 | Implement into Java created in 1.2 changes in rtl folder of the skin: appStatus.js and utils.js reseting frameset.cols values. | Must have | Not Needed. A JS global variable will report JS functions if RTL or LTR language is chosen. |
1.5 | Implement into Java created in 1.2 changes in rtl folder of the skin: change login_FS.html page, adding a parameter to choose rtl or ltr aspect of the language that sets the cols attribute of the frameset tag. | Must have | Complete |
1.6 | Implement into Java created in 1.2 changes in rtl folder of the skin: needed modifications in css files. | Must have | Complete |
1.7 | Implement into Java created in 1.2 changes in rtl folder of the skin: Create a file into the skin with the relation of png images to flip, in order to fit RTL aspect. | Must have | Complete |
1.8 | Implement into Java created in 1.2 changes in rtl folder of the skin: Perform flip to images in file created in 1.7 | Must have | Complete |
Database Changes
Num | Requirement | Importance | Status |
2.1 | New column added to the AD_LANGUAGE table, to announce whether the language is RTL or LTR. | Must have | Complete |
2.2 | Update all available languages to identify the RTL ones. The rest must be set to LTR. | Must have | Complete |
Linking languages to skins
Num | Requirement | Importance | Status |
3.1 | Set session variable with language direction. | Must have | Complete |
3.2 | When saving to database the skin to use, concatenate the language direction as well, according to the session variable value. | Must have | Complete |
3.3 | When saving to database the language to use, update value of rtl. | Must have | Complete |
3.4 | After logging in, and changing role information, text direction is applied. | Must have | Complete |
Open Discussion Items
Issue: 4402
http://forge.openbravo.com/plugins/espforum/view.php?group_id=100&forumid=597808&topicid=5103255
[1]: http://en.wikipedia.org/wiki/Bi-directional_text
[2]: http://www.w3.org/TR/html401/struct/dirlang.html#h-8.2
[3]: http://www.w3.org/TR/html5/semantics.html#the-dir
[4]: http://java.sun.com/j2se/1.3/docs/api/java/awt/Graphics2D.html http://java.sun.com/j2se/1.3/docs/api/java/awt/geom/AffineTransform.html