{"type":"doc","content":[{"type":"paragraph","content":[{"text":"Open Web Apps promise to transform OpenMRS development by letting devs with standard HTML+JS skills build apps (a) without needing any knowledge of Java or OpenMRS's server-side code, (b) with more efficient dev processes that don't require deploying an OpenMRS module each time you want to see a change.","type":"text"}]},{"type":"paragraph","content":[{"text":"This tutorial describes how you can quickly build a freestanding Open Web App on top of the OpenMRS Reference Application. (A future tutorial will talk about how to integrate Open Web App code with existing code.)","type":"text"}]},{"type":"paragraph","content":[{"text":"We assume that you have a development environment set up, to build JavaScript webapps, e.g. you have ","type":"text"},{"text":"npm","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"git","type":"text","marks":[{"type":"em"}]},{"text":", and you have a suitable text editor.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"In a hurry?","type":"text"}]},{"type":"paragraph","content":[{"text":"Want to skip this and just start writing code? Fork this git repo: ","type":"text"},{"text":"https://github.com/djazayeri/openmrs-owa-tutorialexample","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/djazayeri/openmrs-owa-tutorialexample"}}]},{"text":" or scaffold your app using the ","type":"text"},{"text":"Yeoman generator","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.npmjs.com/package/generator-openmrs-owa"}}]},{"text":".","type":"text"}]}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"68117ac5-9873-4132-b077-dafbe2ee8626"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 1 - Run OpenMRS locally","type":"text"}]},{"type":"paragraph","content":[{"text":"You need to be running OpenMRS locally to be able to do rapid development (because you need to be able to copy files from your dev environment to the \"server\"). You can run OpenMRS in a number of ways, but the easiest would be to download the latest Standalone version of the Reference Application.","type":"text"}]},{"type":"paragraph","content":[{"text":"To use the standalone:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Download the latest Standalone release of the Reference Application from ","type":"text"},{"text":"http://openmrs.org/download/","type":"text","marks":[{"type":"link","attrs":{"href":"http://openmrs.org/download/"}}]},{"text":" (at time of writing this is \"OpenMRS 2.3.1 Standalone Edition\").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unzip it, and run openmrs-standalone.jar (or run-on-linux.sh)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Choose Demonstration Mode (so that you have access to demo patients).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Wait a few minutes for OpenMRS to start up","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You can log in as admin/Admin123","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 2 - Install the Open Web Apps module","type":"text"}]},{"type":"paragraph","content":[{"text":"This is described on the ","type":"text"},{"text":"Open Web Apps Module","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25461755"}}]},{"text":" page. It's the same as installing any other module.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once this is done you should verify that a folder called \"appdata/owa\" has been created underneath your unzipped openmrs-standalone folder. To be able to develop rapidly, you'll want to know the path of that folder, to copy files into it. (You will need to know this in Step 5.)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 3 - Create the Skeleton of Your Open Web App","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"There is a Yeoman generator available to automatically create your skeleton. See the documentation ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/Open+Web+App+Development+Workflow#OpenWebAppDevelopmentWorkflow-2.ScaffoldOpenWebApp"}}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Create the folder where you will build your Open Web App, following the convention of \"openmrs-owa-yourappname\" (to make it easily recognizable on github).","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ mkdir openmrs-owa-tutorialexample\n$ cd openmrs-owa-tutorialexample\n$ git init","type":"text"}]},{"type":"paragraph","content":[{"text":"Within this folder, create your ","type":"text"},{"text":"manifest.webapp","type":"text","marks":[{"type":"em"}]},{"text":" file, as described on the ","type":"text"},{"text":"Open Web Apps Module","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25461755"}}]},{"text":" page. (If you want to use IntelliJ for this, create a \"Static Web\" project and consider ","type":"text"},{"text":"this gitignore file","type":"text","marks":[{"type":"link","attrs":{"href":"https://raw.githubusercontent.com/github/gitignore/master/Global/JetBrains.gitignore"}}]},{"text":".)","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, create your ","type":"text"},{"text":"index.html","type":"text","marks":[{"type":"em"}]},{"text":" file (or some other filename if you specified something else as the launch_path in your ","type":"text"},{"text":"manifest.webapp","type":"text","marks":[{"type":"em"}]},{"text":").","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\n \n \n \n \n

Tutorial Example

\n If you see this, it works.\n \n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"We are going to use ","type":"text"},{"text":"npm","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.npmjs.com/getting-started/installing-node"}}]},{"text":" and ","type":"text"},{"text":"gulp","type":"text","marks":[{"type":"link","attrs":{"href":"http://gulpjs.com/"}}]},{"text":" to build our webapp. Make sure you have npm installed (e.g. from the linked instructions).","type":"text"}]},{"type":"codeBlock","content":[{"text":"// you only need to do these once ever\nnpm install --global gulp\nnpm install --global gulp-zip\n \nnpm init\n// enter requested info (defaults will work fine); this creates package.json\n \nnpm install --save-dev gulp\nnpm install --save-dev gulp-zip\n// this would be a good time to add \"node_modules\" to your .gitignore file\n// while you are doing this, also add \"dist\" to your .gitignore file","type":"text"}]},{"type":"paragraph","content":[{"text":"Create your gulpfile, whose default task will build the Open Web App zip file:","type":"text"}]},{"type":"codeBlock","content":[{"text":"'use strict';\nvar gulp = require('gulp');\nvar zip = require('gulp-zip');\n\nvar THIS_APP_NAME = 'tutorialexample'; // REPLACE THIS\n\nvar sources = ['manifest.webapp', '**/*.html', '**/*.js', '**/*.css', '**/*.png',\n '**/*.otf', '**/*.eot', '**/*.svg', '**/*.ttf', '**/*.woff', '**/*.woff2',\n '!node_modules', '!node_modules/**', '!gulpfile.js'];\n\ngulp.task('default', function () {\n return gulp.src(sources)\n .pipe(zip(THIS_APP_NAME + '.zip'))\n .pipe(gulp.dest('dist'));\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"At this point you can run the \"gulp\" command, and you will see a zip file created in a ","type":"text"},{"text":"/dist","type":"text","marks":[{"type":"em"}]},{"text":" directory.","type":"text"}]},{"type":"paragraph","content":[{"text":"(You can find all the code we've seen up to this point at ","type":"text"},{"text":"https://github.com/djazayeri/openmrs-owa-tutorialexample/tree/skeleton-with-zip","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/djazayeri/openmrs-owa-tutorialexample/tree/skeleton-with-zip"}}]},{"text":".)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 4 - Upload Your Open Web App Through the Web UI","type":"text"}]},{"type":"paragraph","content":[{"text":"You need to upload your Open Web App ZIP file through the OpenMRS web UI once. (It's okay, after this first time you'll be able to do this via a gulp command, which will speed things up.)","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Open Web Apps Module","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25461755"}}]},{"text":" page describes how to do this. (The file you want to upload is the zip file created in the /dist directory.) Once you've done this, click on your app's icon (it will be a broken image if you've followed these instructions), and verify that you see the expected index.html page.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 5 - Set Up Your Project for Rapid Development","type":"text"}]},{"type":"paragraph","content":[{"text":"You want to be able rapidly iterate on the UI that you are building, and with Open Web Apps we can do this in a way that is much more efficient than by writing a server-side OpenMRS module. Since we are running a local OpenMRS server, we can just set up a gulp task that copies our files to the folder on disk where they are served from. This will let us see our code changes by running a single gulp task, and refreshing the browser window.","type":"text"}]},{"type":"paragraph","content":[{"text":"Modify your ","type":"text"},{"text":"gulpfile","type":"text","marks":[{"type":"em"}]},{"text":" to look like this (we are adding a new ","type":"text"},{"text":"deploy-local","type":"text","marks":[{"type":"em"}]},{"text":" task, and a new variable you have to set):","type":"text"}]},{"type":"codeBlock","content":[{"text":"'use strict';\nvar gulp = require('gulp');\nvar zip = require('gulp-zip');\n\nvar LOCAL_OWA_FOLDER = '.../openmrs-standalone-2.3.1/appdataowa/'; // REPLACE THIS\nvar THIS_APP_NAME = 'tutorialexample'; // REPLACE THIS\n\nvar sources = ['manifest.webapp', '**/*.html', '**/*.js', '**/*.css', '**/*.png',\n '**/*.otf', '**/*.eot', '**/*.svg', '**/*.ttf', '**/*.woff', '**/*.woff2',\n '!node_modules', '!node_modules/**', '!gulpfile.js'];\n\ngulp.task('default', function () {\n return gulp.src(sources)\n .pipe(zip(THIS_APP_NAME + '.zip'))\n .pipe(gulp.dest('dist'));\n});\n\ngulp.task('deploy-local', function () {\n return gulp.src(sources)\n .pipe(gulp.dest(LOCAL_OWA_FOLDER + THIS_APP_NAME));\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"Now, once you have made changes to your project in your text editor or IDE, you just need to run that task:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ gulp deploy-local","type":"text"}]},{"type":"paragraph","content":[{"text":"...and then refresh your browser window, and you'll see your changes reflected.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can test this out by making an edit to the index.html file, and verifying you see that change.","type":"text"}]},{"type":"paragraph","content":[{"text":"(You can find the skeleton code we've written so far at ","type":"text"},{"text":"https://github.com/djazayeri/openmrs-owa-tutorialexample/tree/skeleton-with-deploy-local","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/djazayeri/openmrs-owa-tutorialexample/tree/skeleton-with-deploy-local"}}]},{"text":".)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Linking to Your Open Web App from the Home Screen","type":"text"}]},{"type":"paragraph","content":[{"text":"Since you've built a standalone app, you want to let people access it from the OpenMRS home screen. You can do this by going to ","type":"text"},{"text":"System Administration","type":"text","marks":[{"type":"strong"}]},{"text":" -> ","type":"text"},{"text":"Manage Apps","type":"text","marks":[{"type":"strong"}]},{"text":" -> ","type":"text"},{"text":"Add App Definition","type":"text","marks":[{"type":"strong"}]},{"text":" and then adding a definition like:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"id\": \"replace.with.something.unique\",\n \"description\": \"replace with your description\",\n \"order\": 0,\n \"extensions\": [\n {\n \"id\": \"replace.with.something.unique.homepageLink\",\n \"extensionPointId\": \"org.openmrs.referenceapplication.homepageLink\",\n \"type\": \"link\",\n \"label\": \"Replace with name of your App\",\n \"url\": \"owa/managerdashboard/index.html\",\n \"icon\": \"icon-bar-chart\",\n \"requiredPrivilege\": \"Replace with a privilege name, or else remove\"\n }\n ]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"You can see the available icons at ","type":"text"},{"text":"http://demo.openmrs.org/openmrs/uicommons/icons.page","type":"text","marks":[{"type":"link","attrs":{"href":"http://demo.openmrs.org/openmrs/uicommons/icons.page"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"To go along with this you probably want a link in the top left of your app, with a homepage icon, with an href of \"../index.html\" (or else use the value of ","type":"text"},{"text":"openmrs.href from ","type":"text"},{"text":"manifest.","type":"text"},{"text":"webapp as an absolute URL).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Contributions Welcome","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Make This Better!","type":"text"}]},{"type":"paragraph","content":[{"text":"I am not primarily a JS developer, and I have never used gulp before doing this example. I'm sure there's a cleaner way to set up the gulpfile, and I welcome someone showing the better way!","type":"text"}]},{"type":"paragraph","content":[{"text":"Also, I'd love for someone to extend the tutorial with:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how to add a JS or CSS library by downloading it from npm","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the best initial layout for an AngularJS application (ideally with routes that don't resolve until we've fetched openmrs.href from manifest.webapp)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how to combine and minify your JS","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"compass/sass instead of CSS","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"coffeescript instead of JS","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"jade instead of HTML","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how to make REST calls against the OpenMRS API (and how to do this using the ","type":"text"},{"text":"already-written AngularJS services","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-module-uicommons/tree/master/omod/src/main/webapp/resources/scripts/services"}}]},{"text":" in the uicommons module)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how to use the OpenMRS SDK as an alternative to the Standalone distribution","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"...whatever else I haven't thought of that is obvious to a JavaScript developer","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Of course it would be great to have a starter skeleton that includes Bootstrap CSS, Font Awesome, and AngularJS out of the box!","type":"text"}]},{"type":"paragraph","content":[{"text":"Edit this wiki page, or send me a pull request against ","type":"text"},{"text":"https://github.com/djazayeri/openmrs-owa-tutorialexample","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/djazayeri/openmrs-owa-tutorialexample"}}]},{"text":", or just comment with a link to your own better starter code!","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}