The DHIS 2.0 web solution

Throughout this text, DHIS refers to DHIS 2.0.

Index

Introduction
Supporting projects

Introduction

DHIS 2.0 web solution is based on WebWork and [Velocity]. This page assumes a fair amount of knowledge about how these frameworks work including Maven 2 and Spring.

In order to understand how the DHIS 2.0 web solution works, one has to know about the supporting projects which set up the environment.

Supporting projects

The DHIS web solution is based on a few important DHIS projects:

scm/trunk/dhis-2/dhis-support/dhis-support-webwork
scm/trunk/dhis-2/dhis-web/dhis-web-commons
scm/trunk/dhis-2/dhis-web/dhis-web-commons-resources

These projects provide configuration, common functionality, and resources, and are the fundament on which we develop user interaction modules.

dhis-support-webwork

(Located in scm/trunk/dhis-2/dhis-support/)

This module contains classes that are specific to XWork/WebWork and Velociy but are general to the web solution. The module consists of five classes and two configuration files (ignoring beans.xml):

EncoderVelocityContext

(Located in org.hisp.dhis.webwork.encoding.velocity)

This VelocityContext provides encoding and escaping functionality to the Velocity templates:

Language	Function	Description
HTML	$encoder.htmlEncode( $object )	Creates a string, safe to put in an HTML context. Example: <p>$encoder.htmlEncode( $name )</p>
XML	$encoder.xmlEncode( $object )	Creates a string, safe to put in an XML context. Example: <name>$encoder.xmlEncode( $name )</name>
JavaScript (1)	$encoder.jsEncode( $object )	Creates a string, safe to put in a JavaScript inside HTML context. Example: <a href="javascript:display( '$encoder.jsEncode( $name )' )">Display name</a>
JavaScript (2)	$encoder.jsEscape( $object, $quoteChar )	Creates a string, safe to put in a JavaScript context. Example: <script type="text/javascript"> var name = '$encoder.jsEscape( $name, "'" )'; </script> The second argument is the type of quote used around the JavaScript string.

WebWorkConfigurationInitializer

(Located in org.hisp.dhis.webwork.configuration)

This class locates all the XWork/WebWork configuration files (xwork.xml) and gives them to XWork/WebWork's configuration manager. This is necessary because when several web modules are merged with the maven-war-plugin, each web module is transformed into a JAR file containing the module's XWork/WebWork configuration file. By default, XWork/WebWork only loads the first xwork.xml file found. This class is set up as a bean and executed by Spring after the bean has been created.

WebWorkTransactionInterceptor

(Located in org.hisp.dhis.webwork.interceptor)

The transaction interceptor wraps all action executions inside transactions. The reason for wrapping a complete action in a transaction is to avoid any transaction management inside the action class. If an action needs to make several requests to the underlying database within the same transaction, this is the interceptor to use. See DHIS2:#dhis-web-commons for details.

In this module the interceptor is only prepared for referencing elsewhere.

WebWorkExceptionInterceptor

(Located in org.hisp.dhis.webwork.interceptor)

The exception interceptor should be put at the bottom of the interceptor stack, catching all exception comming from action classes and other interceptors. In case of an exception, the exception interceptor will return the result name "exception" which is globaly mapped to a template displaying the exception (exception.vm).

In this module the interceptor is only prepared for referencing elsewhere.

WebWorkI18nInterceptor

(Located in org.hisp.dhis.webwork.interceptor)

The i18n interceptor loads the right resource boundles corresponding to the currently executed action. There are two ways of using the functionality this interceptor provides:

In the Velocity templates, internationalisation is available through the $i18n and $format keys. These keys reference the I18n and the I18nFormat objects, respectively. Examples:
```
<p>$i18n.getString( "name" )</p>

<p>$format.formatDate( $date )</p>
```
In the action classes, internationalisation is available through the i18n and format properties:
```
private I18n i18n;

public void setI18n( I18n i18n )
{
    this.i18n = i18n;
}

private I18nFormat format;

public void setFormat( I18nFormat format )
{
    this.format = format;
}
```
These properties are automatically set by the interceptor if any of them exists in the intercepted action class.

In this module the interceptor is only prepared for referencing elsewhere.

dhis-support-webwork.xml

(Located in src/main/resources)

This is an XWork/WebWork configuration file (like xwork.xml). It extends webwork-default and contains declarations of the interceptors in this module.

webwork.properties

(located in src/main/resources)

This file is read by WebWork and sets up the EncoderVelocityContext + sets other necessary options.

dhis-web-commons

(Located in scm/trunk/dhis-2/dhis-web/)

This project is the endpoint towards the user interaction modules. Together with dhis-web-commons-resources, this module sets up the framework in which to create new web modules. These are the logical groupings of files and code in this module:

dhis-web-commons.xml

(Located in src/main/resources)

This is an XWork/WebWork configuration file which sets up all the interceptor stacks, exception mapping etc. This is the file you need to include and extend in your xwork.xml. This file includes and extends dhis-support-webwork.xml (see DHIS2:#dhis-support-webwork), which again includes and extends webwork-default.xml.

There are currently four interceptor stacks available:

exceptionStack - This is the default stack, so if no particular stack is defined, this is the one that is used.
transactionStack - This stack adds the transaction interceptor to the exception stack. Use this if you need to wrap your action class in a transaction.
organisationUnitTreeStack - This stack must be used when the displayed page contains the organisation unit web tree. The stack contains the organisationUnitTreeInterceptor which prepares the organisation unit web tree. This stack extends the transaction stack.
fileUploadStack - This stack adds file uploading capabilities to the exception stack, which means that it does not contain the transaction interceptor. If you need to use this stack and you need the transaction interceptor, simply specify so:
```
<action ...>
  ...
  <interceptor-ref="fileUploadStack"/>
  <interceptor-ref="transactionInterceptor"/>
</action>
```

Interceptors

(Located in org.hisp.dhis.webportal.interceptor)

There are four interceptors in this package:

WebWorkPortalMenuInterceptor - Makes the state of the menu (hidden/visible) available to the Velocity templates so that the menu can be displayed correctly.
WebWorkPortalModuleInterceptor - Makes a list of all the available web modules with an index.action to be displayed as the horizontal module menu. The modules are sorted according to the configuration of the interceptor and/or alphabetically.
WebWorkPortalParamsInterceptor - Takes the three static parameters; page, menu, and javascripts, and makes them available to the Velocity templates. The parameters are used by the main and popup templates when putting the result page together. Example:
```
<action ...>
  <result name="success" type="velocity">/main.vm</result>
  <param name="page">/dhis-web-portal/login.vm</param>
  <param name="menu">/dhis-web-portal/menu.vm</param>
  <param name="javascripts">foo.js,bar.js</param>
  <param name="stylesheets">foo.css,bar.css</param>
</action>
```
The javascripts parameter is a comma separated list of JavaScript files one wants to include in the header section of the resulting HTML page.
WebWorkPortalUserInterceptor - Makes the current user available to the Velocity templates for displaying, typically in the top right corner of the page. The two possible keywords are $currentUser (org.hisp.dhis.service.user.User) and $currentUsername (java.lang.String).

The reason for having all these interceptors is to make the action classes not having to care about common functionality and resources. The action classes should only care about what the action classes are supposed to do.

Web portal menu state

(Located in org.hisp.dhis.webportal.menu)

This collection of classes manages the state of the portal menu. Actions exist for receiving the current state, a manager stores the state in session, and an interceptor (mentioned above) makes the state available to the Velocity templates.

Organisation unit web tree

(Located in org.hisp.dhis.ouwt)

Organisation unit selection tree

(Located in org.hisp.dhis.oust)

dhis-web-commons-resources

(Located in scm/trunk/dhis-2/dhis-web/)

Contains common Velocity templates, images and other resources. All user interaction modules need to have a dependency to this project (WAR dependency).