Introduction

Abstract

Background description

OpenMRS web application includes an initial setup and update wizards those greatly simplifies DB creation, configuration and update on web-app startup.

But, when user is running installation or the database update wizards the GUI messages, on the pages which are rendered,  aren't translated into the supported languages except english.

Goal

Localization style must be alike desktop's application with choosing preferred language at 1st step of setup wizard, with ability to move back and change it while wizard is running and with storing that selected language by app for further using it.

Goals for midterm

• The selected tool should have been integrated and have a few pages localized

• The user should be able to select the language at  startup and persisted to the database

Final goals

• The user should be able to move back and forth through the wizard's pages even when the text displayed is in a language they don't understand so well or if they selected a wrong language by mistake

• Have all pages localized

• Have qualitative documentation

Understanding the basic principals of initial setup and update wizard design

Above mentioned wizards are running when OpenMRS web-application is starting.

The initial setup wizard will run either when web-app starts after first deploy or when application data directory has changed. In turn, update wizard will be runned only if there are some new changes within liquibase file which are need to be applyed to database.

For achieve of such behaviour, OpenMRS uses appropriate servlet's filters. Currently those are the InitializationFilter and the UpdateFilter. After the app's servlet's context has initialized, context initialization listener will call method setupNeeded(). And if this method returns true, it means that the filters needs to take some action and  OpenMRS won't start yet.

And since initial setup (or database update) is needed and each request  to openmrs web-application are being filtered by InitializationFilter and/or the UpdateFilter filters, then the first GET-request will cause start execution of those wizards. 

Appropriate doGet() method will be invoked for this GET-request . That method renders first page of any wizard into the server output stream. This page is rendering from  velocity template. Each wizard consists of set of sequenced pages. As mentioned above, every such page is rendering from appropriate velocity template.

When user is moving through wizard's pages he, preferably, sends POST-requests to server, which are processed by doPost() methods of filters. Depending on previous step of wizard, this method will render next corresponding page via appropriate velocity template. And all GUI messages, on the pages which are rendered from templates,  aren't translated into the supported languages.

Schedule

Proposed time-line:

This is detailed time-line that contains plans of project's execution and it's score.

10 April – 23 April

1. More thoroughly familiarize myself with the code and the community, the version control system, the documentation and do test of system;

2. Familiarize myself completely with installation and update wizard's functionality and architecture.

26 April – 22 May (before the official coding time)

1. To make a review of existing localization tools for velocity templates with providing relevant analyzes document for mentor

2. To discuss this document and explore all bottlenecks within project to become absolutely clear about my future goals and the way of it implementation

3. To determine final project's architecture and design of appropriate classes (provide necessary UML-diagrams, those describe structural and behavior aspects of project)

4. To discuss those designed diagrams with mentor.

5. To do self coding with installation and update wizard projects to improve my further understanding and ease of use;

23 May -- 18 June (official coding period starts)

1. Write code of appropriate classes considering with designed diagrams.

2. Define entire set of messages to be localized for installation and update wizards.

3. Perform a full translation for one of the the supported languages ​​(eg Italian), to be able to right away test the functionality that is being developed

19 June -- 1 July

1. Make the necessary changes with wizard's pages (notably, add page for selecting the preferred language and add appropriate control buttons and also test new navigation between wizard's pages)

2. Provide new feature for storing/retrieving user selected language.

3. Write appropriate changes into the install/update filter classes to ensure direct integration of existing velocity templates with developed on previous steps custom localization tools.

1 July – 19 July

1. Test received functionality for two languages ​​(English by default, and previously the chosen one) and bug fixes.

2. Perform further translation of interface messages into other supported languages.

3. Prepare project for midterm evaluation.

JULY 15th - MID TERM EVALUATION

20 July – 25 July:

1. To be in constant touch with the mentor and to let him know about our progress.

2. Making further changes in the code to improve the functionality, exception handling, bug removal. Most of the time will be consumed for rigorous testing and bug fixes. 

26 July – 31 July:

1. For writing documentation

1 August – 15 August:

A buffer of two weeks has been kept for any unpredictable delay.

Project's requirements

So, above mentioned goal can be successfully achieved only if developed project will satisfy next requirements:

Functional requirements  

Open

1. Appropriate page should be shown for user at first step of the setup wizard;

2. That page should contain selection list with all possible languages, checkbox for indicate that the selected language should be persisted after wizard’s finish and navigation  element (next

   Open

   

   arrow) for continue;

3. Selection list should be dynamically filled with languages basing on existing web app's message resource files;

4. The user should be able to move back and forth through the each wizard's pages by using appropriate navigation elements (arrows are preferred in case when the text displayed is in a language they don't understand so well or if they selected a wrong language by mistake);

5. When user is moving through the initial setup wizard's pages, language should not be changed until user will return to 1^st page and change it;

6. Selected by user language should be saved into cookie (or as http session's attribute) during wizard’s work and (if user have marked checkbox), it should be persisted into DB as admin’s property;

7. When user is running the database update wizard, all pages should be displayed in previously persisted language or in English by default.

Non-functional requirements

1. Support for new languages should not require recompilation;

2. Access translated text with resource bundles;

3. Resource bundles should be loaded as fast as possible (on web app startup or at first request).

4. Textual elements, such as status messages and the GUI component labels of both wizards should be completely translated into most of supported languages (Italian, Spanish, French and Portuguese);

5. Employ the use of previous

   arrow and next

   arrows as navigation elements instead of buttons with text ;

6. Only Unicode encoding characters should be used for translation;

After describing of requirements we can make more desictive steps. As we need to localize messages through velocity templates next in chapter contains analyze of existing L10n tools.

Analyze of existing L10n tools for velocity templates

Overview of existing L10n tools

Based on the above requirements to ensure L10n support for velocity templates, it's need to use an existing java properties files as message's source. Those properties files will contain translation of appropriate GUI text messages of both wizards. Those properties files are located under web app's /WEB-INF directory.

Considering the above mentioned, one of the project's central tasks is a loading message resources through Java's message resource bundle by employing some form of message localization tool. Such tool should be like a connecting element between localized messages from one hand, and velocity pages from other hand. That is why it's necessarily to pay a special attention for such tool's design.

After searching through the Internet I found several widely-used tools. When I analyzed them, I used next criteria:

• ease of use via velocity

• based on Resource bundles

• wide extensibility and good customization

So, I decided to do complete overview of the next tools which met most of criteria in one way or another:

• IncludeTool from Velocity-View extension

• Spring's tool for Resource Bundles (MessageSourceResourceBundle)

• ResourceTool from Generic-Tools

All these tools have a lot of different features and any of them can be chosen.

1) First, and as I think, not the best way is IncludeTool. This is a class from VelocityView which allows for transparent content negotiation. It’s really ease of use via velocity. Usage it “tool” from a template would be something like the following: