Web solution tips and tricks
Note on the DHIS 2 web solution
When you create your own Velocity templates for pages in your module, they are not rendered standalone. Instead they are inserted into a larger framework of templates, CSS files and JavaScripts. This is defined in the xwork.xml file of your module, in you action mappings. An example:
<action name="myaction" class="org.hisp.dhis.web.mymodule.action.MyActionClass">
<result name="success" type="velocity">/main.vm</result>
<param name="page">/dhis-web-mymodule/mytemplate.vm</param>
<param name="menu">/dhis-web-mymodule/mymenu.vm</param>
</action>
In this case /main.vm is a template in the framework. The page param is your own template, the actual content. The menu param is the template which will be rendered as the left hand side menu. The main.vm will parse and render these two templates in an appropriate place. This means main.vm will supply the html, head and body tags, plus some more framework HTML. The consequence of this is that you cannot, for example, include stylesheets directly in your page template, as this needs to be a part of the head tag in the HTML. The same problem applies to scripts.
Adding JavaScripts to your page
See Note on the DHIS 2 web solution for some background information.
JavaScripts should be included in the head element of the page. As we are using a framework to generate the head element, you need to specify in your action mappings which JavaScripts to include by using a param element. An example:
<action name="myaction" class="org.hisp.dhis.web.mymodule.action.MyActionClass">
<result name="success" type="velocity">/main.vm</result>
<param name="page">/dhis-web-mymodule/mytemplate.vm</param>
<param name="menu">/dhis-web-mymodule/mymenu.vm</param>
<param name="javascripts">script1,script2,script3</param>
</action>
<param name="javascripts">script1,script2,script3</param>
This param takes a comma separated list of relative URLs to JavaScript files.
The param can contain any number of spaces and newlines inbetween the commas and the values.
<param name="javascripts">
script1,
script2,
script3
</param>
is still a legal format.
This will result in the following HTML:
..
<head>
..
<script type="text/javascript" src="script1"></script>
<script type="text/javascript" src="script2"></script>
<script type="text/javascript" src="script3"></script>
..
</head>
..
Adding stylesheets to your page
See Note on the DHIS 2 web solution for some background information.
Stylesheet references must be included in the head element of the page. As we are using a framework to generate the head element, you need to specify in your action mappings which stylesheets to include by using a param element. An example:
<action name="myaction" class="org.hisp.dhis.web.mymodule.action.MyActionClass">
<result name="success" type="velocity">/main.vm</result>
<param name="page">/dhis-web-mymodule/mytemplate.vm</param>
<param name="menu">/dhis-web-mymodule/mymenu.vm</param>
<param name="stylesheets">css1,css2,css3</param>
</action>
<param name="stylesheets">css1,css2,css3</param>
This param takes a comma separated list of relative URLs to stylesheet files.
 | Style rule conflicts
Note that these stylesheets are included after the default stylesheets for the system, meaning that if there are any conflicting style rules, the rules in your stylesheets will override the rules in the default stylesheet. |
The param can contain any number of spaces and newlines inbetween the commas and the values.
<param name="stylesheets">
css1,
css2,
css3
</param>
is still a legal format.
This will result in the following HTML:
..
<head>
..
<link type="text/css" rel="stylesheet" media="screen" href="css1">
<link type="text/css" rel="stylesheet" media="screen" href="css2">
<link type="text/css" rel="stylesheet" media="screen" href="css3">
..
</head>
..
Adding calendar popup to your page
DHIS 2 has support for small calendar popups where you can select a date. To use these you have to add some text to your Velocity file and include 3 Javasripts.
Add these Javascripts to your action.
<action name="myaction" class="org.hisp.dhis.web.mymodule.action.MyActionClass">
<result name="success" type="velocity">/main.vm</result>
<param name="page">/dhis-web-mymodule/mytemplate.vm</param>
<param name="menu">/dhis-web-mymodule/mymenu.vm</param>
<param name="javascripts">
../dhis-web-commons/calendar/calendar.js,
../dhis-web-commons/calendar/calendar-lang.js,
../dhis-web-commons/calendar/calendar-setup.js
</param>
</action>
Add this text to your velocity file (mytemplate.vm):
<label for="startDate">$i18n.getString('start_date') ($i18n.getString( "format.date.label" ))</label>
<input type="text" id="startingPeriod" name="startingPeriod" value="$!startingPeriod" style="width:230px">
<img src="../images/calendar_icon.gif" width="16" height="16" id="getStartDate" cursor: pointer;"
title="$i18n.getString( "date_selector" )" onmouseover="this.style.background='orange';" onmouseout="this.style.background=''">
<label for="endDate">$i18n.getString('end_date') ($i18n.getString( "format.date.label" ))</label>
<input type="text" id="endingPeriod" name="endingPeriod" value="$!endingPeriod" style="width:230px">
<img src="../images/calendar_icon.gif" width="16" height="16" id="getEndDate" cursor: pointer;"
title="$i18n.getString( "date_selector" )" onmouseover="this.style.background='orange';" onmouseout="this.style.background=''">
<script type="text/javascript">
Calendar.setup({
inputField : "startingPeriod", // id of the input field
ifFormat : "$i18n.getString("format.date.label")", // format of the input field
button : "getStartDate" // trigger for the calendar (button ID)
});
Calendar.setup({
inputField : "endingPeriod", // id of the input field
ifFormat : "$i18n.getString("format.date.label")", // format of the input field
button : "getEndDate" // trigger for the calendar (button ID)
});
</script>
