Dev Getting Started
So you want to applications written on the OpenIZ disconnected client platform? Doing so is quite easy once you get the tooling setup. This tutorial will show you how to setup your development environment and get started writing OpenIZ applets.
Before we get started, let's stop and review some terminology. If you've ever downloaded the vanilla version of the OpenIZ Disconnected Client you've probably seen this.
This is because the default applet that ships with the OpenIZ platform has no real user interface. In order to get OpenIZ to be a little more useful, you need to tell it what to do. This is done with something called an applet.
An applet contains several things:
- The clinical protocols (schedules for performing actions) for the applet (or for the global system)
- The business rules which should be triggered on the server and mobile device when data is inserted/updated/deleted
- Clinical template files which dictate the structure of data
- The user interface pages that end users will interact with
- The controllers for those pages which control the behavior
- Any images and resources that those pages require
- A manifest file which specifies the translations to be used in the application, any menu items to add to the root element
Applets are distributed as package (pak) files when they're complete. A pak file minifies and compresses the applet contents, and allows for easy distribution of the applet to servers and mobiles. In order to produce these files and to debug your applets you'll need to get the SDK.
The SDK is downloaded from the OpenIZ Disconnected Client page. There is an installer for windows, however the SDK can be used on Linux and MacOS as well.
In order to develop applets you'll need the following software:
To develop on Windows, you'll need the following tools installed:
- An HTML/JavaScript editor of your choice. This tutorial will use Visual Studio Code
- A graphics editor (optional) for editing graphics files
- An XML editor (any text editor will do, but an XML aware editor will make your life a lot easier)
- The OpenIZ DC SDK
To develop on MacOSX or, you'll need the following tools installed:
- The Mono Framework 4.x or better (http://www.mono-project.com/)
- An HTML/JavaScript editor of your choice. This tutorial will use Visual Studio Code
- A graphics editor (optional) for editing graphics files
- An XML editor (any text editor will do, but an XML aware editor will make your life a lot easier)
- The OpenIZ DC SDK
After you have your toolchain setup, you'll need to start an empty applet. You can clone the template project:
# git clone https://github.com/MohawkMEDIC/openizdctpl.git myproject
Cloning into 'myproject'...
remote: Counting objects: 72, done.
remote: Total 72 (delta 0), reused 0 (delta 0), pack-reused 72
Unpacking objects: 100% (72/72), done.
Checking connectivity... done.
Next, we can hook up our HTML/JavaScript editor to the directory. If you prefer you can have the entire project loaded:
There are a few folders to go over here:
- controllers - This is where the logic which controls your user interface should go
- css - Any stylesheets you are using should be placed here
- data - Any data resources (reference weights, etc.) are to be located here. Anything located here can be fetched on the server or mobile via getData()
- img - Any image assets you wish to use are here
- rules - This is where your javascript business rules go
- templates - Any Act or Entity templates (the things that tell OpenIZ what sub-type of something is) go here
- views - Any HTML views should go here.
- viewmodel - Any JavaScript view-model files should go in here
- Manifest.xml - This is the application manifest which dictates your applet ID and name
Additionally there is a helper script which will build your applet using the built-in SDK. There are two files, one which builds in debug mode and one which optimizes the package file.
If you like you can run the build-debug.bat file to verify that you can build applets. If you are successful you will see this output.
#build-debug.bat
Processing C:\demo\\myproject\....
Reading Manifest...
Processing C:\demo\\myproject\.\.gitignore...
Processing C:\demo\\myproject\.\build-debug.bat...
Processing C:\demo\\myproject\.\build-release.bat...
Processing C:\demo\\myproject\.\index.html...
Processing C:\demo\\myproject\.\jsconfig.json...
Processing C:\demo\\myproject\.\LICENSE.md...
Processing C:\demo\\myproject\.\Manifest.xml...
Processing C:\demo\\myproject\.\README.md...
Skipping directory C:\demo\\myproject\.\.git
Skipping directory C:\demo\\myproject\.\.ref
Processing C:\demo\\myproject\.\controllers\index.js...
Processing C:\demo\\myproject\.\css\theme.css...
Processing C:\demo\\myproject\.\img\icon.png...
Processing C:\demo\\myproject\.\rules\org.sample.applet.rule.hpv.js...
Processing C:\demo\\myproject\.\templates\act.observation.discharge.json...
Processing C:\demo\\myproject\.\views\act.observation.discharge.html...
Processing C:\demo\\myproject\.\views\dashboard.html...
WARNING:>>> THIS PACKAGE IS NOT SIGNED - MOST OPEN IZ TOOLS WILL NOT LOAD IT
That last line will be important when we go to deploy our pak file. But for now, you should notice a bin directory was created. In that .bin directory is our pak file.
2017-07-07 04:21 PM 12,061 org.sample.applet.pak
When developing an applet, you will want to debug the applet in a way that is easier than running the applet compiler (that is really only for going to production and distribution). To debug your applet we use the minims command from the OpenIZ SDK Command prompt.
Running a quick help you'll see the options for minims
OpenIZ Mini IMS - Disconnected Client Debugging Tool
Version 0.9.6.26042
--applet Identifies the source code directories to debug
--ref Adds a reference to the current IMS session
--help Shows help and exits
--reset Deletes all configuration data restoring the MiniIMS to its default state
To run our sample applet, we're going to need to point the minims at the applets source directory, we'll also need to reference the location of the org.openiz.core.pak file (as the myproject applet references that package)
minims --ref=org.openiz.core.pak --ref=org.openiz.templates.pak --applet="C:\demo\myproject"
If you're successful, you should see the demo application's index.html appear in the main window.
Just to make sure you can edit, add "Hello World" to the index file, when you refresh you will be presented with the new content.
Which results in our updated file
