OpenMRS Exercise

Set up the development environment
  Download and install Apache Tomcat 6.0.16.   Download the .tar.gz file. TAR files are similar to ZIP files, in that a single TAR file consists of many files "glued" together. The .gz suffix indicates that the file has been compressed with gzip. Use the following command to extract the TAR file: $ gzcat apache-tomcat-6.0.16.tar.gz | tar xvfB - This command says to uncompress apache-tomcat-6.0.16.tar.gz, and send then extract the files from the resulting uncompressed TAR file. This will create the directory apache-tomcat-6.0.16 which contains the tomcat web server package. Since tomcat is written in Java, it does not need to be compiled. We recommend that you execute this command in your home directory, or even better in a directory called apps in your home directory, just to keep things organized. </li> </ul> </li>

<li> Configure Eclipse. <ul> <li> Hopefully EasyEclipse Java Server is already installed. If not, unpack the file you copied into your account yesterday. Again, we recommend that you do so either in your home directory or (preferably) in the apps</tt> subdirectory. To configure Eclipse, start it up, then select Window->Preferences</tt> and configure Tomcat as follows: <ol> <li> In the Tomcat pane, select "Version 6.x" and set "Tomcat home" to the apache-tomcat-6.0.16</tt> directory from the previous step. </li> <li> In the Tomcat Manager pane, set the "ManagerApp username" to "tcmanager" (no quotes) and "ManagerApp password" to abcd1234</tt>. Click on "Add to tomcat-users.xml." </li> </ol> Unfortunately, uploading a web app (like OpenMRS) to the tomcat server from within Eclipse does not seem to work. In this configuration step, we have set up Tomcat itself to allow you to upload the web app from the Tomcat Manager web app; for that, you must have a Tomcat user with the right permissions, which is what we did in step 2. Now start Tomcat by clicking on the fourth button from the left in the Eclipse toolbar. </li> </ul> </li>

<li> Install OpenMRS from the OpenMRS Subversion repository. Do this by creating a new Subversion project. Use http://svn.openmrs.org</tt> as the server and navigate to openmrs/trunk</tt>. Build the WAR (web app archive) file by right-clicking on build.xml</tt> and selecting Run As->Ant Build</tt>. This will build the web app but not install it on the Tomcat server. </li>

<li> Configure the OpenMRS runtime properties as follows: <ol> <li>Create the directory .OpenMRS</tt> in your home directory.</li> <li>With a text editor, create the file openmrs-runtime.properties</tt> in .OpenMRS</tt>.</li> <li>Add the following lines to openmrs-runtime.properties</tt>: connection.username=openmrsuser connection.password=tryopenmrs connection.url=jdbc:mysql://storage1.cs.trincoll.edu:3306/openmrs?autoReconnect=true </ol> What this step does is to tell the web app (once you finally access it) where the database is located and what (MySQL) username and password to use to access it. We won't actually use the database for this exercise, but OpenMRS will not run without this being properly configured. </li>

<li> Install the web app into Tomcat: <ol> <li>Open a web browser and point it to http://localhost:8080/manager/html. You will be prompted for a user name and password; enter tcmanager</tt> and abcd1234</tt>.</li> <li>Navigate to the bottom of the Manager page to "Select WAR file to upload." Browse to openmrs/dist/openmrs.war</tt> in your Eclipse workspace.</li> <li>Click on "Deploy."</li> </ol> </li>

<li> See if all has worked properly by pointing your browser at http://localhost:8080/openmrs. You should get the OpenMRS login screen; you can log in with Username admin</tt> and Password <tt>test</tt>. </li>

</ol>

Create a Logo Message Module
<ol>

<li> Create a new module called <tt>LogoMsg</tt> module. Follow the instructions at http://openmrs.org/wiki/Creating_Your_First_OpenMRS_Module through step 4. </li>

<li> Your module should provide content at the <tt>org.openmrs.navigation.homepage</tt> extension point (see http://openmrs.org/wiki/Module_Extension_Points for a discussion of extension points). Provide the content by writing a class that extends <tt>org.openmrs.module.Extension</tt> and provides the content by overriding <tt>getOverrideContent</tt> to return a <tt>String</tt> such as "The H-FOSS Edition." Don't forget to modify <tt>config.xml</tt> to register your module for this extension point. Build your module by right-clicking on <tt>build.xml</tt> and selecting "Run As->Ant Build." This will create a file with an <tt>.omod</tt> extension in the <tt>dist</tt> directory of your module project. </li>

<li> Install your module in the web app as follows: <ol> <li>Copy the <tt>.omod</tt> file to <tt>.OpenMRS/modules</tt> (create the directory if it does not exist).</li> <li>Reload the OpenMRS web app by going to the Tomcat manager, finding <tt>openmrs</tt>, and clicking on "Restart."</li> </ol> </li>

<li> Restart OpenMRS by pointing your browser to http://localhost:8080/openmrs. </li>

<li> Repeat these steps until the OpenMRS logo is replaced with "The H-FOSS Edition." </li>

</ol>

Make a better Logo Message Module
It would be much nicer to add a message after the standard logo than to wipe it out. Figure out how to do so. This involves making a new extension point in the core presentation file <tt>web/WEB-INF/view/index.jsp</tt>. After doing so, you will need to rebuild the OpenMRS web app and re-deploy it through the Tomcat manager. An ideal solution to this problem would have the following features: <ol> <li>The class you use to add content at the extension point provides that content via a method other than <tt>getOverrideContent</tt>; for example, see <tt>web/WEB-INF/view/admin/index.jsp</tt> for how the <tt>org.openmrs.admin.list</tt> extension point requires classes that register for it implement certain methods.</li> <li>Instead of hard-coding a message in your class that registers for your new extension point, instead read it from the <tt>openmrs-runtime.properties</tt> file; I think <tt>System.getProperty</tt> should be helpful here. I really don't know if this is possible---I haven't tried it.</li> </ol>