Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

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

Documentation

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated image to match midnight theme of code blocks.

Table of Contents

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 serverserver. Once it's downloaded, extract the ZIP archive and run the jar file either by double clicking it or executing the following command:


Code Block
language
languagebash
themeMidnightbash
titleRun 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 MySQL 5.6, Java 1.7+ and Maven 3+ installed. Newer versions of MySQL, even with compatibility options, will not work. To install and configure the OpenMRS SDK, run the following:


Code Block
language
languagebash
themeMidnightbash
titleInstall the OpenMRS SDK
mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk


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


Code Block
languagebash
themeMidnightlanguagebash
titleCreate 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:


Code Block
languagebash
themeMidnight
languagebash
titleRun 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

To set up and instance of the OpenMRS Platform using Docker

...

TODO

...

, follow the instructions in the README file in this repository. To support rapid local deploys, you'll need to make the following change to your docker-compose.yml file:


Code Block
languagediff
themeMidnight
titleSupport Local Deploys to Docker
openmrs-platform-tomcat:
  build: tomcat
  ports:
    - "8080:8080"
  container_name: openmrs-platform-tomcat
  links:
    - openmrs-platform-mysql
+  volumes:
+    - /host/location/of/owadata:/usr/local/tomcat/.OpenMRS/owa
openmrs-platform-mysql:
  build: mysql
  ports:
    - "3306:3306"
  container_name: openmrs-platform-mysql


This will create an owadata directory at /host/location/of/ on your Docker host and map that to the Open Web Apps data directory in the container. Once you've scaffolded your app (see section #3 below), edit the LOCAL_OWA_FOLDER variable in gulpfile.js to point to this directory in order to support local deploys.

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 Your 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 46+ installed to do this. See the install instructions here.

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


Code Block
languagebash
themeMidnightlanguagebash
titleInstall OWA Generator Dependencies
npm install -g yo gulp bower


You can then install the generator:


Code Block
languagebash
themeMidnightlanguagebash
titleInstall OWA Generator
npm install --gglobal @openmrs/generator-openmrs-owa


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


Code Block
languagebash
themeMidnight
languagebash
titleScaffold Open Web App
yo @openmrs/openmrs-owa


This will start up the Yeoman generator. The output should be something like:


Image Added


Follow the options in the Yeoman generator in order to scaffold the app. Depending on your setup options it might look something like this when you are done: 

Image Added



Ensure that the APP_ENTRY_POINT inside webpack.config.js is set to the proper location of your OWA's index.html. Congratulations, you have successfully scaffolded your app!


AngularJS Dependency Changes

It's possible that you can encounter TypeErrors if your OWA is using Angular 1.x. Inside package.json in the OWA's root folder, remove the ^ before the version number of each dependency related to Angular. Run npm install afterwards to install the correct versions of those dependencies. See here for more information. 

You may also have to remove the following snippet found inside home.js if you are still encountering issues:

Image Removed

...


Code Block
languagejs
themeMidnight
titleDependency code snippet
.config(['$qProvider', function ($qProvider) {
    $qProvider.errorOnUnhandledRejections(false);
}])


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 in the app directory.

The The app/manifest.webapp files contain 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:

...

General Tips

If you're building your OWA with Angular, all code should be inside components and designed in a modular manner. This will help facilitate an upcoming migration to a more recent version of Angular. 

If you're building your OWA with React, please refer to and follow the style guide. There are also React Components available for use.

For the latest information on which technologies to use, check the OpenMRS Radar which is updated quarterly. 

Building The App

To build and package your app in a distributable file, use npm Webpack.  

 

Code Block
languagebash
themeMidnight
titleBuild App
gulp

...

Scaffold Open Web App
npm run build:prod

 

This creates a zip file in the app directory. You can then upload this to an OpenMRS implementation using the Open Web Apps module admin pageModule.

Local Deployment

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


Code Block
language
languagebash
themeMidnightbash
titleDeploy Locally
gulp deploy-local

...

Scaffold Open Web App
npm run build:deploy


 The app should now show up in your OpenMRS implementation (Administration -> Open Web Apps Module -> Manage Apps) and will look something like this: 


Image Added


If you have issues using Webpack to deploy the app, ensure that the deploy directory is correct. Open the config.json file in the apps directory and make sure that LOCAL_OWA_FOLDER variable. The following are the default locations for the various server installs:

...

points to the correct directory. For example: 

{
"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.

...

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:

Code Block
themeMidnight
languagebash
titleInstall Package
bower install --save angular

This will download the angular package and store it in the bower_components directory.

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:

Code Block
themeMidnight
languagexml
titleBower 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:

Code Block
themeMidnight
languagexml
firstlineBower CSS Injection Point
<!-- bower:css -->
<!-- endbower -->

4. Deployment

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

 

Code Block
themeMidnight
languagebash
titleBuild App
gulp

This will create a ZIP file in the dist directory that you can upload on the Open Web Apps module admin page.

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

...

5/appdata/owa",
}


Using Browsersync

npm can use Browsersync to watch the files as you development and dynamically reload the app as you make changes to the code. Each time you save a file in the app's directory, the app will reload and display in the browser. This is an extremely useful tool. To use browsersync run the following command in your app's directory: 


Code Block
languagebash
themeMidnight
titleBuild App
npm run watch


If you have issues getting browsersync to work, ensure that the app is being injected. Open the config.json file in the app directory and make sure that APP_ENTRY_POINT points to the correct path. Your config.json file should look 

{
"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.5/appdata/owa",
"APP_ENTRY_POINT": "http://localhost:8081/openmrs-standalone/owa/appList/index.html"
}

Since you've built a standalone app, you want to let people access it from the OpenMRS home screen. In the Standalone or the Reference Application, you can do this by going to System Administration -> Manage Apps -> Add App Definition and then adding a definition like:


Code Block
languagejs
themeMidnight
titleHome Page Link Config
{
    "id": "listApp",
    "description": "Demo App",
    "order": 0,
    "extensions": [
        {
            "id": "demoapp.homepageLink",
            "extensionPointId": "org.openmrs.referenceapplication.homepageLink",
            "type": "link",
            "label": "Demo App",
            "url": "owa/demoapp/index.html",
            "icon": "icon-plane",
            "requiredPrivilege": "Replace with a privilege name, or else remove"
        }
    ]
}

 

You can see the available icons at http://demo.openmrs.org/openmrs/uicommons/icons.page.

For more details about Adding Icon to Reference Application Homepage, just visit Adding OWA Icon to the Reference ApplicationHomepage

Resources