1.38 Plugins

DHIS2 comes with plugins which enable you to embed live data directly in your web portal or web site. Currently, plugins exist for charts, maps and pivot tables.

Please be aware that all of the code examples in this section are for demonstration purposes only . They should not be used as is in production systems. To make things simple, the credentials (admin/district) have been embedded into the scripts. In a real scenario you should never expose credentials in javascript as it opens a vulnerability to the application. In addition you would create a user with more minimal privileges rather than make use of a superuser to fetch resources for your portal.

It is possible to workaround exposing the credentials by using a reverse proxy such as nginx or apache2. The proxy can be configured to inject the required Authorization header for only the endpoints that you wish to make public. There is some documentation to get you started in the section of the implementers manual which describes reverse proxy configuration.

1.38.1 Embedding pivot tables with the Pivot Table plug-in

In this example we will see how we can embed good-looking, light-weight html pivot tables with data served from a DHIS2 back-end into a Web page. To accomplish this we will use the Pivot table plug-in. The plug-in is written in Javascript and depends on the jQuery library only. A complete working example can be found at http://play.dhis2.org/portal/table.html . Open the page in a web browser and view the source to see how it is set up.

We start by having a look at what the complete html file could look like. This setup puts two tables in our web page. The first one is referring to an existing table. The second is configured inline.

<!DOCTYPE html>
<html>
<head>
  <script src="https://dhis2-cdn.org/v227/plugin/jquery-2.2.4.min.js"></script>
  <script src="https://dhis2-cdn.org/v227/plugin/reporttable.js"></script>

  <script>
    reportTablePlugin.url = "https://play.dhis2.org/demo";
    reportTablePlugin.username = "admin";
    reportTablePlugin.password = "district";
    reportTablePlugin.loadingIndicator = true;

    // Referring to an existing table through the id parameter, render to "report1" div

    var r1 = { el: "report1", id: "R0DVGvXDUNP" };

    // Table configuration, render to "report2" div

    var r2 = {
      el: "report2",
      columns: [
        {dimension: "dx", items: [{id: "YtbsuPPo010"}, {id: "l6byfWFUGaP"}]}
      ],
      rows: [
        {dimension: "pe", items: [{id: "LAST_12_MONTHS"}]}
      ],
      filters: [
        {dimension: "ou", items: [{id: "USER_ORGUNIT"}]}
      ],

      // All following properties are optional
      title: "My custom title",
      showColTotals: false,
      showRowTotals: false,
      showColSubTotals: false,
      showRowSubTotals: false,
      showDimensionLabels: false,
      hideEmptyRows: true,
      skipRounding: true,
      aggregationType: "AVERAGE",
      showHierarchy: true,
      completedOnly: true,
      displayDensity: "COMFORTABLE",
      fontSize: "SMALL",
      digitGroupSeparator: "COMMA",
      legendSet: {id: "fqs276KXCXi"}
    };

    reportTablePlugin.load([r1, r2]);
  </script>
</head>

<body>
  <div id="report1"></div>
  <div id="report2"></div>
</body>
</html>

Two files are included in the header section of the HTML document. The first file is the jQuery javascript library (we use the DHIS2 content delivery network in this case). The second file is the Pivot table plug-in. Make sure the path is pointing to your DHIS2 server installation.

Now let us have a look at the various options for the Pivot tables. One property is required: el (please refer to the table below). Now, if you want to refer to pre-defined tables already made inside DHIS2 it is sufficient to provide the additional id parameter. If you instead want to configure a pivot table dynamically you should omit the id parameter and provide data dimensions inside a columns array, a rows array and optionally a filters array instead.

A data dimension is defined as an object with a text property called dimension . This property accepts the following values: dx (indicator, data element, data element operand, data set, event data item and program indicator), pe (period), ou (organisation unit) or the id of any organisation unit group set or data element group set (can be found in the web api). The data dimension also has an array property called items which accepts objects with an id property.

To sum up, if you want to have e.g. “ANC 1 Coverage”, “ANC 2 Coverage” and “ANC 3 Coverage” on the columns in your table you can make the following columns config:

columns: [{
  dimension: "dx",
  items: [
    {id: "Uvn6LCg7dVU"}, // the id of ANC 1 Coverage
    {id: "OdiHJayrsKo"}, // the id of ANC 2 Coverage
    {id: "sB79w2hiLp8"}  // the id of ANC 3 Coverage
  ]
}]
Pivot table plug-in configuration
Param Type Required Options (default first) Description
url string Yes Base URL of the DHIS2 server
username string Yes (if cross-domain) Used for authentication if the server is running on a different domain
password string Yes (if cross-domain) Used for authentication if the server is running on a different domain
loadingIndicator boolean No Whether to show a loading indicator before the table appears
Pivot table configuration
Param Type Required Options (default first) Description
el string Yes Identifier of the HTML element to render the table in your web page
id string No Identifier of a pre-defined table (favorite) in DHIS2
columns array Yes (if no id provided) Data dimensions to include in table as columns
rows array Yes (if no id provided) Data dimensions to include in table as rows
filter array No Data dimensions to include in table as filters
title string No Show a custom title above the table
showColTotals boolean No true | false Whether to display totals for columns
showRowTotals boolean No true | false Whether to display totals for rows
showColSubTotals boolean No true | false Whether to display sub-totals for columns
showRowSubTotals boolean No true | false Whether to display sub-totals for rows
showDimensionLabels boolean No true | false Whether to display the name of the dimension top-left in the table
hideEmptyRows boolean No false | true Whether to hide rows with no data
skipRounding boolean No false | true Whether to skip rounding of data values
completedOnly boolean No false | true Whether to only show completed events
showHierarchy boolean No false | true Whether to extend orgunit names with the name of all anchestors
aggregationType string No “DEFAULT” | “SUM” |“AVERAGE” | “AVERAGE_SUM_ORG_UNIT”|“LAST”|“LAST_AVERAGE_ORG_UNIT”| “COUNT” | “STDDEV” | “VARIANCE” | “MIN” | “MAX” Override the data element’s default aggregation type
displayDensity string No “NORMAL” | “COMFORTABLE” | “COMPACT” The amount of space inside table cells
fontSize string No “NORMAL” | “LARGE” | “SMALL” Table font size
digitGroupSeparator string No “SPACE” | “COMMA” | “NONE” How values are formatted: 1 000 | 1,000 | 1000
legendSet object No Color the values in the table according to the legend set
userOrgUnit string / array No Organisation unit identifiers, overrides organisation units associated with curretn user, single or array
relativePeriodDate string No Date identifier e.g: “2016-01-01”. Overrides the start date of the relative period

1.38.2 Embedding charts with the Visualizer chart plug-in

In this example we will see how we can embed good-looking Highcharts charts ( http://www.highcharts.com ) with data served from a DHIS2 back-end into a Web page. To accomplish this we will use the DHIS2 Visualizer plug-in. The plug-in is written in JavaScript and depends on the jQuery library. A complete working example can be found at http://play.dhis2.org/portal/chart.html . Open the page in a web browser and view the source to see how it is set up.

We start by having a look at what the complete html file could look like. This setup puts two charts in our web page. The first one is referring to an existing chart. The second is configured inline.

<!DOCTYPE html>
<html>
<head>
  <script src="https://dhis2-cdn.org/v227/plugin/jquery-2.2.4.min.js"></script>
  <script src="https://dhis2-cdn.org/v227/plugin/chart.js"></script>

  <script>
    chartPlugin.url = "https://play.dhis2.org/demo";
    chartPlugin.username = "admin";
    chartPlugin.password = "district";
    chartPlugin.loadingIndicator = true;

    // Referring to an existing chart through the id parameter, render to "report1" div

    var r1 = { el: "report1", id: "R0DVGvXDUNP" };

    // Chart configuration, render to "report2" div

    var r2 = {
      el: "report2",
      columns: [
        {dimension: "dx", items: [{id: "YtbsuPPo010"}, {id: "l6byfWFUGaP"}]}
      ],
      rows: [
        {dimension: "pe", items: [{id: "LAST_12_MONTHS"}]}
      ],
      filters: [
        {dimension: "ou", items: [{id: "USER_ORGUNIT"}]}
      ],

      // All following properties are optional
      title: "Custom title",
      type: "line",
      showValues: false,
      hideEmptyRows: true,
      regressionType: "LINEAR",
      completedOnly: true,
      targetLineValue: 100,
      targetLineTitle: "My target line title",
      baseLineValue: 20,
      baseLineTitle: "My base line title",
      aggregationType: "AVERAGE",
      rangeAxisMaxValue: 100,
      rangeAxisMinValue: 20,
      rangeAxisSteps: 5,
      rangeAxisDecimals: 2,
      rangeAxisTitle: "My range axis title",
      domainAxisTitle: "My domain axis title",
      hideLegend: true
    };

    // Render the charts

    chartPlugin.load(r1, r2);
  </script>
</head>

<body>
  <div id="report1"></div>
  <div id="report2"></div>
</body>
</html>

Two files are included in the header section of the HTML document. The first file is the jQuery JavaScript library (we use the DHIS2 content delivery network in this case). The second file is the Visualizer chart plug-in. Make sure the path is pointing to your DHIS2 server installation.

Now let us have a look at the various options for the charts. One property is required: el (please refer to the table below). Now, if you want to refer to pre-defined charts already made inside DHIS2 it is sufficient to provide the additional id parameter. If you instead want to configure a chart dynamically you should omit the id parameter and provide data dimensions inside a columns array, a rows array and optionally a filters array instead.

A data dimension is defined as an object with a text property called dimension . This property accepts the following values: dx (indicator, data element, data element operand, data set, event data item and program indicator), pe (period), ou (organisation unit) or the id of any organisation unit group set or data element group set (can be found in the web api). The data dimension also has an array property called items which accepts objects with an id property.

To sum up, if you want to have e.g. “ANC 1 Coverage”, “ANC 2 Coverage” and “ANC 3 Coverage” on the columns in your chart you can make the following columns config:

columns: [{
  dimension: "dx",
  items: [
    {id: "Uvn6LCg7dVU"}, // the id of ANC 1 Coverage
    {id: "OdiHJayrsKo"}, // the id of ANC 2 Coverage
    {id: "sB79w2hiLp8"}  // the id of ANC 3 Coverage
  ]
}]
Chart plug-in configuration
Param Type Required Options (default first) Description
url string Yes Base URL of the DHIS2 server
username string Yes (if cross-domain) Used for authentication if the server is running on a different domain
password string Yes (if cross-domain) Used for authentication if the server is running on a different domain
loadingIndicator boolean No Whether to show a loading indicator before the chart appears
Chart configuration
Param Type Required Options (default first) Description
el string Yes Identifier of the HTML element to render the chart in your web page
id string No Identifier of a pre-defined chart (favorite) in DHIS
type string No column | stackedcolumn | bar | stackedbar | line | area | pie | radar | gauge Chart type
columns array Yes (if no id provided) Data dimensions to include in chart as series
rows array Yes (if no id provided) Data dimensions to include in chart as category
filter array No Data dimensions to include in chart as filters
title string No Show a custom title above the chart
showValues boolean No false | true Whether to display data values on the chart
hideEmptyRows boolean No false | true Whether to hide empty categories
completedOnly boolean No false | true Whether to only show completed events
regressionType string No “NONE” | “LINEAR” Show trend lines
targetLineValue number No Display a target line with this value
targetLineTitle string No Display a title on the target line (does not apply without a target line value)
baseLineValue number No Display a base line with this value
baseLineTitle string No Display a title on the base line (does not apply without a base line value)
rangeAxisTitle number No Title to be displayed along the range axis
rangeAxisMaxValue number No Max value for the range axis to display
rangeAxisMinValue number No Min value for the range axis to display
rangeAxisSteps number No Number of steps for the range axis to display
rangeAxisDecimals number No Bumber of decimals for the range axis to display
domainAxisTitle number No Title to be displayed along the domain axis
aggregationType string No “DEFAULT” | “SUM” |“AVERAGE” | “AVERAGE_SUM_ORG_UNIT”|“LAST”|“LAST_AVERAGE_ORG_UNIT”| “COUNT” | “STDDEV” | “VARIANCE” | “MIN” | “MAX” Override the data element’s default aggregation type
hideLegend boolean No false | true Whether to hide the series legend
hideTitle boolean No false | true Whether to hide the chart title
userOrgUnit string / array No Organisation unit identifiers, overrides organisation units associated with curretn user, single or array
relativePeriodDate string No Date identifier e.g: “2016-01-01”. Overrides the start date of the relative period

1.38.3 Embedding maps with the GIS map plug-in

In this example we will see how we can embed maps with data served from a DHIS2 back-end into a Web page. To accomplish this we will use the GIS map plug-in. The plug-in is written in JavaScript and depends on the Ext JS library only. A complete working example can be found at http://play.dhis2.org/portal/map.html . Open the page in a web browser and view the source to see how it is set up.

We start by having a look at what the complete html file could look like. This setup puts two maps in our web page. The first one is referring to an existing map. The second is configured inline.

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css" href="http://dhis2-cdn.org/v215/ext/resources/css/ext-plugin-gray.css" />
  <script src="http://dhis2-cdn.org/v215/ext/ext-all.js"></script>
  <script src="https://maps.google.com/maps/api/js?sensor=false"></script>
  <script src="http://dhis2-cdn.org/v215/openlayers/OpenLayers.js"></script>
  <script src="http://dhis2-cdn.org/v215/plugin/map.js"></script>

  <script>
    var base = "https://play.dhis2.org/demo";

    // Login - if OK, call the setLinks function

    Ext.onReady( function() {
      Ext.Ajax.request({
        url: base + "dhis-web-commons-security/login.action",
        method: "POST",
        params: { j_username: "portal", j_password: "Portal123" },
        success: setLinks
      });
    });

    function setLinks() {
      DHIS.getMap({ url: base, el: "map1", id: "ytkZY3ChM6J" });

      DHIS.getMap({
        url: base,
        el: "map2",
        mapViews: [{
          columns: [{dimension: "in", items: [{id: "Uvn6LCg7dVU"}]}], // data
          rows: [{dimension: "ou", items: [{id: "LEVEL-3"}, {id: "ImspTQPwCqd"}]}], // organisation units,
          filters: [{dimension: "pe", items: [{id: "LAST_3_MONTHS"}]}], // period
          // All following options are optional
          classes: 7,
          colorLow: "02079c",
          colorHigh: "e5ecff",
          opacity: 0.9,
          legendSet: {id: "fqs276KXCXi"}
        }]
      });
    }
  </script>
</head>

<body>
  <div id="map1"></div>
  <div id="map2"></div>
</body>
</html>

Four files and Google Maps are included in the header section of the HTML document. The first two files are the Ext JS JavaScript library (we use the DHIS2 content delivery network in this case) and its stylesheet. The third file is the OpenLayers JavaScript mapping framework ( http://openlayers.org ) and finally we include the GIS map plug-in. Make sure the path is pointing to your DHIS2 server installation.

<link rel="stylesheet" type="text/css" href="http://dhis2-cdn.org/v215/ext/resources/css/ext-plugin-gray.css" />
<script src="http://dhis2-cdn.org/v215/ext/ext-all.js"></script>
<script src="https://maps.google.com/maps/api/js?sensor=false"></script>
<script src="http://dhis2-cdn.org/v215/openlayers/OpenLayers.js"></script>
<script src="http://dhis2-cdn.org/v215/plugin/map.js"></script>

To authenticate with the DHIS2 server we use the same approach as in the previous section. In the header of the HTML document we include the following Javascript inside a script element. The setLinks method will be implemented later. Make sure the base variable is pointing to your DHIS2 installation.

Ext.onReady( function() {
  Ext.Ajax.request({
    url: base + "dhis-web-commons-security/login.action",
    method: "POST",
    params: { j_username: "portal", j_password: "Portal123" },
    success: setLinks
  });
});

Now let us have a look at the various options for the GIS plug-in. Two properties are required: el and url (please refer to the table below). Now, if you want to refer to pre-defined maps already made in the DHIS2 GIS it is sufficient to provide the additional id parameter. If you instead want to configure a map dynamically you should omit the id parameter and provide mapViews (layers) instead. They should be configured with data dimensions inside a columns array, a rows array and optionally a filters array instead.

A data dimension is defined as an object with a text property called dimension . This property accepts the following values: in (indicator), de (data element), ds (data set), dc (data element operand), pe (period), ou (organisation unit) or the id of any organisation unit group set or data element group set (can be found in the web api). The data dimension also has an array property called items which accepts objects with an id property.

To sum up, if you want to have a layer with e.g. “ANC 1 Coverage” in your map you can make the following columns config:

columns: [{
  dimension: "in", // could be "in", "de", "ds", "dc", "pe", "ou" or any dimension id
  items: [{id: "Uvn6LCg7dVU"}], // the id of ANC 1 Coverage
}]
GIS map plug-in configuration
Param Type Required Options (default first) Description
el string Yes Identifier of the HTML element to render the map in your web page
url string Yes Base URL of the DHIS2 server
id string No Identifier of a pre-defined map (favorite) in DHIS
baseLayer string/boolean No ‘gs’, ‘googlestreets’ | ‘gh’, ‘googlehybrid’ | ‘osm’, ‘openstreetmap’ | false, null, ‘none’, ‘off’ Show background map
hideLegend boolean No false | true Hide legend panel
mapViews array Yes (if no id provided) Array of layers

If no id is provided you must add map view objects with the following config options:

Map plug-in configuration
layer string No “thematic1” | “thematic2” | “thematic3” | “thematic4” | “boundary” | “facility” | The layer to which the map view content should be added
columns array Yes Indicator, data element, data operand or data set (only one will be used)
rows array Yes Organisation units (multiple allowed)
filter array Yes Period (only one will be used)
classes integer No 5 | 1-7 The number of automatic legend classes
method integer No 2 | 3 Legend calculation method where 2 = equal intervals and 3 = equal counts
colorLow string No “ff0000” (red) | Any hex color The color representing the first automatic legend class
colorHigh string No “00ff00” (green) | Any hex color The color representing the last automatic legend class
radiusLow integer No 5 | Any integer Only applies for facilities (points) - radius of the point with lowest value
radiusHigh integer No 15 | Any integer Only applies for facilities (points) - radius of the point with highest value
opacity double No 0.8 | 0 - 1 Opacity/transparency of the layer content
legendSet object No Pre-defined legend set. Will override the automatic legend set.
labels boolean/object No false | true | object properties: fontSize (integer), color (hex string), strong (boolean), italic (boolean) Show labels on the map
width integer No Width of map
height integer No Height of map
userOrgUnit string / array No Organisation unit identifiers, overrides organisation units associated with current user, single or array

We continue by adding one pre-defined and one dynamically configured map to our HTML document. You can browse the list of available maps using the Web API here: http://play.dhis2.org/demo/api/24/maps .

function setLinks() {
  DHIS.getMap({ url: base, el: "map1", id: "ytkZY3ChM6J" });

  DHIS.getMap({
 url: base,
 el: "map2",
 mapViews: [
   columns: [ // Chart series
  columns: [{dimension: "in", items: [{id: "Uvn6LCg7dVU"}]}], // data
   ],
   rows: [ // Chart categories
  rows: [{dimension: "ou", items: [{id: "LEVEL-3"}, {id: "ImspTQPwCqd"}]}], // organisation units
   ],
   filters: [
  filters: [{dimension: "pe", items: [{id: "LAST_3_MONTHS"}]}], // period
   ],
   // All following options are optional
   classes: 7,
   colorLow: "02079c",
   colorHigh: "e5ecff",
   opacity: 0.9,
   legendSet: {id: "fqs276KXCXi"}
 ]
  });
}

Finally we include some div elements in the body section of the HTML document with the identifiers referred to in the plug-in JavaScript.

<div id="map1"></div>
<div id="map2"></div>

To see a complete working example please visit http://play.dhis2.org/portal/map.html .