2.2 Creating Apps

DHIS2 apps are constructed with HTML, JavaScript and CSS files, similar to any other web application. Apps also need a special file called manifest.webapp which describes the contents of the app. A basic example of the manifest.webapp is shown below:

{
    "version": "0.1",
    "name": "My App",
    "description": "My App is a Packaged App",
    "launch_path": "/index.html",
    "appType": "APP",
    "icons": {
        "16": "/img/icons/mortar-16.png",
        "48": "/img/icons/mortar-48.png",
        "128": "/img/icons/mortar-128.png"
    },
    "developer": {
        "name": "Me",
        "url": "http://me.com"
    },
    "default_locale": "en",
    "activities": {
        "dhis": {
            "href": "*",
            "namespace": "my-namespace"
        }
    },
    "authorities": [
         "MY_APP_ADD_NEW",
         "MY_APP_UPDATE",
         "MY_APP_DELETE"
    }
}

The manifest.webapp file must be located at the root of the project. Among the properties are:

"activities": {
    "dhis": {
        "href": "http://apps.dhis2.org/demo",
        "namespace": "my-namespace"
    }
 }

The namespace property can be added if your app is utilizing the dataStore or userDataStore api. When adding the namespace property, only users with access to your app are allowed to make changes to the namespace. A namespace can only be reserved in this way once. If another app tries to reserve a namespace already in use, the installation of the other app will fail.

If you have a collection of apps that want to share the same namespace, but also wish to reserve it, the users of the apps needs to have the authority to use the app that initially reserved the namespace.

Note

Namespaces will not be created until atleast one key-value pair is present in the namespace. Specifying a namespace in the manifest only restricts the access and does not create any data in the namespace.

The appType property specifies how the app will be displayed by the DHIS2 instance. The possible values for appType and their effects are explained in the following table.

App types
App type Description
APP Will be listed in the “apps” menu
DASHBOARD_WIDGET Available from the search box on the dashboard, can be added as an item on any dashboard
TRACKER_DASHBOARD_WIDGET Can be embedded in the tracker dashboard (this type is not yet supported)
RESOURCE Resource apps are packages that can be shared by multiple other apps. These apps are not shown anywhere in the UI, except from in the app management app.

If no appType is specified in the manifest, the system will use “APP” by default.

To read the JSON structure into JavaScript, you can use a regular AJAX request and parse the JSON into an object. Most Javascript libraries provide some support, for instance with jQuery it can be done like this:

$.getJSON( "manifest.webapp", function( json ) {
    var apiBaseUrl = json.activities.dhis.href + "/api";
} );

The app can contain HTML, JavaScript, CSS, images and other files which may be required to support it . The file structure could look something like this:

/
/manifest.webapp    #manifest file (mandatory)
/css/               #css stylesheets (optional)
/img/               #images (optional)
/js/                #javascripts (optional)

Note

It is only the manifest.webapp file which must be placed in the root. It is up the developer to organize CSS, images and JavaScript files inside the app as needed.

All the files in the project should be compressed into a standard zip archive. Note that the manifest.webapp file must be located on the root of the zip archive (do not include a parent directory in the archive). The zip archive can then be installed into DHIS2 as you will see in the next section.