Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Documentation

Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

This page will briefly discuss the development workflow for developing Open Web Apps. For a description of what Open Web Apps are, see the wiki page. Much of this document is derived from the Developing an HTML+JS Open Web App Quickly wiki page.

1. Setup OpenMRS

In order to develop Open Web Apps, you will need an OpenMRS server running locally. The ways to do this are described below.

Standalone

The quickest and easiest way to set up a server locally is to download the latest standalone server from the OpenMRS downloads page. You will need Java 1.7+ to run the standalone server. Once it's downloaded, extract the ZIP archive and run the jar file either by double clicking it or executing the following command:


Run the OpenMRS standalone server
java -jar openmrs-standalone.jar


The first time you run the server you will be asked if you want to insert dummy data into the system. This is recommended if you want some data to play with.

SDK

Another easy way to run an OpenMRS server is to use the OpenMRS SDK. To use this method you must have Java 1.7+ and Maven 3+ installed. To install and configure the OpenMRS SDK, run the following:


Install the OpenMRS SDK
mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk


To create a new OpenMRS Platform server, run the following:


Create a Platform Server
 mvn openmrs-sdk:setup-platform -DserverId=platform -Dversion=1.11.5


Finally, navigate to the server directory (probably ~/openmrs/platform) and run:


Run a Platform Server with the SDK
mvn openmrs-sdk:run


It is also possible to run a Reference Application server using the SDK. See the SDK docs for instructions on how to do this.

Enterprise

The enterprise install is usually meant for production environments, and involves installing MySQL and Tomcat manually, then downloading the OpenMRS Platform WAR file from the OpenMRS downloads page and deploying it to Tomcat. See the full documentation here.

Docker

TODO

2. Install the Open Web Apps module

This is described on the Open Web Apps Module page. It's the same as installing any other other module

3. Scaffold Open Web App

A boilerplate Open Web App along with some associated build (Gulp) and package management (Bower) tooling can be scaffolded using the Yeoman OpenMRS OWA generator. You will need NodeJS 4+ installed to do this. See the install instructions here.

Once you have NodeJS installed, you need to install Yeoman, Gulp and Bower as follows:


Install OWA Generator Dependencies
npm install -g yo gulp bower


You can then install the generator:


Install OWA Generator
npm install -g generator-openmrs-owa


Next, create a directory for your Open Web App and change into it. Then run the following to scaffold your app:


Scaffold Open Web App
yo openmrs-owa


The output should be something like:

4. Development

All the Open Web App files are in the app directory, everything else is used for building and managing packages. Any files you add manually must be added in the app directory.

The manifest.webapp files contains the information that OpenMRS needs to host your app. See the Open Web Apps Module documentation for details. The launch_path property contains the path to your app entry point. This is the page that will be loaded when you click on your app in OpenMRS.

The command to build the distributable version of your app is just:


Build App
gulp


This will create a ZIP file in the dist directory containing your code and packages. This ZIP file can be uploaded on the Open Web Apps module admin page.

Local Deployment

To speed up the development workflow, we can deploy directly to the app data directory on the filesystem using the following command:


Deploy Locally
gulp deploy-local


The path to the local deploy directory is contained in gulpfile.js in the LOCAL_OWA_FOLDER variable. The following are the default locations for the various server installs:

  • Standalone/path/to/openmrs-standalone-2.3.1/appdataowa
  • SDK~/openmrs/platform/owa (replace "platform" with the name of your server) !! TODO: confirm this
  • Enterprise/usr/share/tomcat7/.OpenMRS/owa !! TODO: confirm this
  • Docker: TODO

Running gulp deploy-local will inject your bower dependencies, then copy everything in the dist folder to the server.

Managing Packages

The Open Web App generator by default uses Bower for package management. To add a new package (say, angular) just run:


Install Package
bower install --save angular


This will download the angular package and store it in the bower_components directory. You must use the --save option.

When you run gulp or gulp deploy-local the installed bower packages will automatically be injected into your html files at the location you choose. To specify the location, add the following to your HTML files:


Bower Javascript Injection Point
<!-- bower:js --> <!-- endbower -->


During the build process, the appropriate markup to include your packages will be injected between these comments, and the packages will be copied into the dist/lib directory.

You may also need to include the CSS files from your installed packages in your HTML. This is done in the same way, except you replace js with css:


Bower CSS Injection Point
<!-- bower:css --> <!-- endbower -->


5. Deployment

To produce a ZIP file that can be uploaded via the Open Web Apps module management page, run: 


Build App
gulp


This will create a ZIP file in the dist directory that you can upload.

See the Development section above to see how to speed up your development workflow using local deploys.

Resources

 

  • No labels