dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #17229
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 510: Added section on data visualizer plugin
------------------------------------------------------------
revno: 510
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Fri 2012-04-27 14:12:51 +0200
message:
Added section on data visualizer plugin
modified:
src/docbkx/en/dhis2_user_man_web_api.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/docbkx/en/dhis2_user_man_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml 2012-04-17 10:58:49 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2012-04-27 12:12:51 +0000
@@ -195,4 +195,177 @@
</listitem>
</itemizedlist>
</section>
+ <section>
+ <title>Example: Embedding charts with the Visualizer Plugin</title>
+ <para>In this example we will see how we can embed good-looking Ext JS charts (<ulink url="http://www.sencha.com/products/extjs"/>) with data served from a DHIS back-end into a Web page. To accomplish this we will use the DHIS Visualizer plugin. The plugin is written in Javascript and depends on the Ext JS library only. A complete working example can be found at <ulink url="http://apps.dhis2.org/portal/plugin.html"/>. Open the page in a web browser and view the source to see how it is set up.</para>
+ <para>We start by including three required Javascript files in the header section of the HTML document. The first file is the Ext JS CSS stylesheet and the second is the Ext JS Javascript library (we use the Google content delivery network in this case). The third file is the Visualizer plugin. Make sure the path is pointing to your DHIS server installation.</para>
+ <screen><link rel="stylesheet" type="text/css" href="http://extjs-public.googlecode.com/svn/tags/extjs-4.0.7/release/resources/css/ext-all-gray.css" />
+<script type="text/javascript" src="http://extjs-public.googlecode.com/svn/tags/extjs-4.0.7/release/ext-all.js"></script>
+<script type="text/javascript" src="http://apps.dhis2.org/demo/dhis-web-visualizer/app/plugin/plugin.js"></script></screen>
+ <para>To authenticate with the DHIS 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 <emphasis role="italic">setLinks</emphasis> method will be implemented later. Make sure the <emphasis role="italic">base</emphasis> variabel is pointing to your DHIS installation.</para>
+ <screen>var base = 'http://apps.dhis2.org/demo/';
+
+Ext.onReady( function() {
+ Ext.Ajax.request({
+ url: base + "dhis-web-commons-security/login.action",
+ method: 'POST',
+ params: { j_username: "admin", j_password: "district" },
+ success: setLinks
+ });
+});</screen>
+ <para>Now let us have a look at the various options for the Visualizer plugin. If you want to refer to pre-defined charts already made inside DHIS you should use the <emphasis role="italic">uid</emphasis> parameter. If you want create dynamic charts you shoud include the indicators and/or dataelements parameter and omit the uid parameter. Asterisk (*) indicates that a parameter is required only when the uid parameter is not used.</para>
+ <table>
+ <title>Visualizer plugin configuration</title>
+ <tgroup cols="5">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis role="italic">Param</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Type</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Required</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Options (default first)</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>uid</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry/>
+ <entry>Identifier of a pre-defined chart in DHIS</entry>
+ </row>
+ <row>
+ <entry>type</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry>column | stackedcolumn | bar | stackedbar | line | area | pie</entry>
+ <entry>Chart type</entry>
+ </row>
+ <row>
+ <entry>indicators</entry>
+ <entry>[integer]</entry>
+ <entry>Yes*</entry>
+ <entry/>
+ <entry>Identifiers of indicators to include in chart</entry>
+ </row>
+ <row>
+ <entry>dataelements</entry>
+ <entry>[integer]</entry>
+ <entry>Yes*</entry>
+ <entry/>
+ <entry>Identifiers of data elements to include in chart</entry>
+ </row>
+ <row>
+ <entry>periods</entry>
+ <entry>[string]</entry>
+ <entry>No</entry>
+ <entry>last12Months | lastMonth | lastQuarter | last4Quarters | lastSixMonth | last2SixMonths | thisYear | last5Years</entry>
+ <entry>Names of relative periods to include in chart</entry>
+ </row>
+ <row>
+ <entry>organisationunits</entry>
+ <entry>[integer]</entry>
+ <entry>Yes*</entry>
+ <entry/>
+ <entry>Identifiers of organisation units to include in chart</entry>
+ </row>
+ <row>
+ <entry>series</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry>data | period | organisationunit</entry>
+ <entry>Dimension to use as chart series</entry>
+ </row>
+ <row>
+ <entry>category</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry>data | period | organisationunit</entry>
+ <entry>Dimension to use as chart category</entry>
+ </row>
+ <row>
+ <entry>filter</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry>data | period | organiastionunit</entry>
+ <entry>Dimension to use as chart filter</entry>
+ </row>
+ <row>
+ <entry>el</entry>
+ <entry>string</entry>
+ <entry>Yes</entry>
+ <entry/>
+ <entry>Identifier of HTML element to render the chart in</entry>
+ </row>
+ <row>
+ <entry>url</entry>
+ <entry>string</entry>
+ <entry>Yes</entry>
+ <entry/>
+ <entry>Base URL of the DHIS server</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>integer</entry>
+ <entry>No</entry>
+ <entry/>
+ <entry>Width of chart</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>integer</entry>
+ <entry>No</entry>
+ <entry/>
+ <entry>Height of chart</entry>
+ </row>
+ <row>
+ <entry>legendPosition</entry>
+ <entry>string</entry>
+ <entry>No</entry>
+ <entry>top | right | bottom | left</entry>
+ <entry>Position of chart legend</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>We continue by including two pre-defined charts and to dynamic charts to our HTML document. You can browse the list of available charts using the Web API here: <ulink url="http://apps.dhis2.org/demo/api/charts"/>.</para>
+ <screen>function setLinks() {
+ DHIS.getChart({ uid: 'R0DVGvXDUNP', el: 'chartA1', url: base });
+
+ DHIS.getChart({ uid: 'X0CPnV6uLjR', el: 'chartA2', url: base });
+
+
+ DHIS.getChart({ el: 'chartB1', url: base,
+ type: 'bar',
+ indicators: ['FnYCr2EAzWS','eTDtyyaSA7f','tUIlpyeeX9N'],
+ periods: 'last12Months',
+ organisationunits: ['ImspTQPwCqd']
+ });
+
+ DHIS.getChart({ el: 'chartB2', url: base,
+ type: 'column',
+ indicators: ['Uvn6LCg7dVU','sB79w2hiLp8'],
+ periods: 'thisYear',
+ organisationunits: ['O6uvpzGd5pu','fdc6uOvgoji','lc3eMKXaEfw','jmIPBj66vD6'],
+ series: 'data',
+ category: 'organisationunit',
+ filter: 'period'
+ });
+};</screen>
+ <para>Finally we include some <emphasis role="italic">div</emphasis> elements in the body section of the HTML document with the identifiers referred to in the plugin Javascript.</para>
+ <screen><div id="chartA1" class="chart"></div>
+<div id="chartA2" class="chart"></div>
+
+<div id="chartB1" class="chart"></div>
+<div id="chartB2" class="chart"></div></screen>
+ <para>To see a complete working example please visit <ulink url="http://apps.dhis2.org/portal/plugin.html"/>.</para>
+ </section>
</chapter>
