Making a help page

I have been working on the following ticket. The request was to improve upon what was already on the help page (which pretty much was nothing).  So, I went through the entire OpenMRS wiki and picked out top candidates for links that I wanted to include in the help page.  I ended up splitting the help page into three sections of links.  This included links on what OpenMRS is, links to OpenMRS guides, and links to information on getting in contact with the OpenMRS team.  Here is a view of what my help page ended up looking like.

 

 The actual coding for this work was not too difficult.  It included simple HTML but also I needed to learn how to make this work within the Spring Framework that is implemented with OpenMRS.  After a bit of research, I found that in general, code goes into the .jsp files and text (for the web pages) goes into a .properties file.  So, in the .jsp file, you may have something like this...

<ul>
    <li><a href="https://wiki.openmrs.org/x/GwAJ"><spring:message code="help.user.text"/
</a></li>

And then there is a corresponding property in the .properties file such as the following....

help.user.text=User's Guide 

This is simple enough but I ran into a special situation where links that had text around them would have to be handled differently. The solution to this ended up being to pass parameters to the .properties file like so..

<li><spring:message code="help.about.text" arguments="<a href='https://wiki.openmrs.org/x/3gNN'>,</a>"/></li> 

And the corresponding property in the properties file would look something like this...

help.about.text={0}High Level Introduction{1} to OpenMRS 

(where '0' and '1' represent arguments)

The final effect that this would give would be to display the following line.

High Level Introduction to OpenMRS

I submitted a patch for this page a couple of days ago but the developers had some feedback to give me before committing it. This feedback was given via Crucible, a very neat code review tool. This allowed for the developers to hi-light specific lines in my code and make comments on it. See the following screen shot for an example.

 


I submitted a patch last night which addressed the issues which were brought up to me and I expect that it will be accepted pending an ongoing discussion regarding this ticket. A few OpenMRS developers have been debating whether or not links should be put into the .properties file or if they should be in the .jsp file. On the side of keeping the links in the .jsp file, this approach seems to be much better from a design stand point. But, on the side of keeping the links in the .properties file, there is an argument that links can be localized and therefore should be placed here so that translators can later work with them.