Caution

This section is deprecated and is NOT recommended for new applications.

Please see DHIS2 App Platform for the up-to-date way to build a DHIS2 Web App.

Apps¶

A packaged app is an Open Web App that has all of its resources (HTML, CSS, JavaScript, app manifest, and so on) contained in a zip file. It can be uploaded to a DHIS2 installation directly through the user interface at runtime. A packaged app is a ZIP file with an app manifest in its root directory. The manifest must be named manifest.webapp. A throrough description of apps can be obtained here.

Objetivo dos aplicativos empacotados¶

O objectivo dos aplicativos empacotados é estender a interface da web do DHIS2, sem a necessidade de modificar o código-fonte do próprio DHIS2. Um sistema a implantação geralmente terá requisitos personalizados e exclusivos. Os aplicativos fornecer um ponto de extensão conveniente para a interface do usuário. Através aplicativos, pode complementar e personalizar a funcionalidade principal do DHIS2 com soluções personalizadas de maneira fracamente acoplada e limpa.

Apps do not have permissions to interact directly with DHIS2 Java API. Instead, apps are expected to use functionality and interact with the DHIS2 services and data by utilizing the DHIS2 Web API.

Criação de aplicativos¶

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:

• The icons→48 property is used for the icon that is displayed on the list of apps that are installed on a DHIS2 instance.

• The activities property is an dhis-specific extension meant to differentiate between a standard Open Web App and an app that can be installed in DHIS2.

• The authorities property contains a list of DHIS2 authorities which can be used to restrict users from certain actions on the current app. This list will be loaded into DHIS2 during app installation process and available for selecting in User Role management form.

• The *** value for href is converted to the appropriate URL when the app is uploaded and installed in DHIS2. This value can then be used by the application's JavaScript and HTML files to make calls to the DHIS2 Web API and identify the correct location of DHIS2 server on which the app has been installed. To clarify, the *activities* part will look similar to this after the app has been installed:

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

• A settings property is optional, and can be used on a dashboard widget app to suppress showing the widget title when the widget is displayed on a dashboard:

"settings": {
    "dashboardWidget": {
        "hideTitle": true
    }
}

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.

Se tiver uma coleção de aplicativos que deseja compartilhar o mesmo namespace, mas também desejam reservá-lo, os usuários dos aplicativos precisam ter o autoridade para usar o aplicativo que inicialmente reservou o 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.

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

Para ler a estrutura JSON em JavaScript, pode usar um AJAX regular solicitar e analisar o JSON em um objeto. A maioria das bibliotecas Javascript fornecer algum suporte, por exemplo, com jQuery pode ser feito assim:

$.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.