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.
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:
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.
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:
To create a new OpenMRS Platform server, run the following:
Finally, navigate to the server directory (probably
~/openmrs/platform) and 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.
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.
2. 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:
You can then install the generator:
Next, create a directory for your Open Web App and change into it. Then run the following to scaffold your app:
The output should be something like:
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
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:
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.
To speed up the development workflow, we can deploy directly to the app data directory on the filesystem using the following command:
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:
~/openmrs/platform/owa(replace "platform" with the name of your server) !! TODO: confirm this
/usr/share/tomcat7/.OpenMRS/owa!! TODO: confirm this
- Docker: TODO
gulp deploy-local will inject your bower dependencies, then copy everything in the
dist folder to the server.
The Open Web App generator by default uses Bower for package management. To add a new package (say, angular) just run:
This will download the angular package and store it in the
bower_components directory. You must use the
When you run
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:
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
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
Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
<!-- bower:css --> <!-- endbower -->
To produce a ZIP file that can be uploaded via the Open Web Apps module management page, run:
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.