Grid-SAFE

Parameters

Report Templates can be parameterised. For example, a report which shows the detail of a particular project would be very useful, especially if you could select the project for a list of possible projects. Report Parameter can be used to solve this problem.

The 'par' namespace needs to be defined in the Report.

<rep:Report 
  xmlns:rep="http://safe.epcc.ed.ac.uk/report"
   xmlns:par="http://safe.epcc.ed.ac.uk/parameter">

Explanatory text to be shown with the generated parameter form can be specified using a Text tag (from the parameter namespace).

  <par:Text>This form allows you to select the project.</par:Text>

Parameters are defined at the top of a report. Below show how a Project parameter is defined using the ParameterDef tag.

<par:ParameterDef name="MyProject" type="Project" value="1"/>

Finally parameters can be substituted into the report using the Parameter tag. This substitution is performed as a separate step early in the report processing so that parameter values can be used to control later processing steps.

<par:Parameter name="MyProject"/>

The following report:

<?xml version="1.0"?>
<rep:Report 
  xmlns:rep="http://safe.epcc.ed.ac.uk/report"
  xmlns:par="http://safe.epcc.ed.ac.uk/parameter">

<par:ParameterDef name="MyProject" type="Project" value="1"/>

<Text>My Project is <par:Parameter name="MyProject"/>.</Text>

</rep:Report>

Would generate the a parameter page

And if Project B is selected the generate report would be:

My Project is Project B.

Types of parameter

There are several different types of parameter.

Selector Types

The previous example, the Project parameter is an example of a data object parameter, where the choice of values is taken from one of the database tables. In this case Project is a classifier table which is automatically populated as accounting records are loaded. This works because the parameter type is used to look up a handler class and if the handler implements the Selector interface it is asked to provide an appropriate form input. The handler classes for all classifier tables will implement this interface and can be used to generate form inputs.

Role Selector Types

Role selector types implement the RoleSelector interface and take an additional role attribute. An example of this is the Relationship class. If you specify a Relationship table as the parameter type the selector e.g.:

<par:ParameterDef name="Project" type="ProjectRelationship" role="manager"/>

The parameter will allow users to select from those projects where they have the manager role.

Filter Selector Types

The classifier handler class also implements the FilterSelector interface that allows you greater control over the table entries to be offered by the form input. You can restrict the table valid table entries by adding a Filter element to the parameter definition.

Basic types

There are also several basic types:

• Boolean
• String
• LongString
• Integer
• Long
• Float
• Double
• Date
• TimeStamp

Here are some examples below:

<par:ParameterDef name="MyBoolean" type="Boolean"/>
<par:ParameterDef name="MyString" type="String"/>
<par:ParameterDef name="MyInteger" type="Integer"/>  
<par:ParameterDef name="MyLong" type="Long"/>  
<par:ParameterDef name="MyFloat" type="Float"/>
<par:ParameterDef name="MyDouble" type="Double"/>
<par:ParameterDef name="MyDate" type="Date"/>
<par:ParameterDef name="MyTimeStamp" type="TimeStamp"/>

These report parameters would generate:

There's a List type which allows you to select a string from a list of options. Here is an example:

<par:ParameterDef name="Fruit" type="List" value="bar" >
        <par:Choice>Apple</par:Choice>  
        <par:Choice>Bananna</par:Choice>
        <par:Choice>Orange</par:Choice>
</par:ParameterDef>

This would generate:

A special set of input types exist for selecting the time periods of reports

• Period - is a simple period between two dates

• RegularSplitPeriod – a period split into a series of regular intervals

• CalendarPeriod – a period split on units of the calendar (day/week/month etc.)

• DayCalendarPeriod – A CalendarPeriod only showing full days

• MonthCalendarPeriod – A CalendarPeriod only showing full months.

Labels

By default the label for a parameter in it's name, but a name can't have spaces in it so may look ugly in the parameter form. The parameter label this can be overridden using the label attribute in ParameterDef?. In this example the label is set to "Number of fruit" instead of FruitCount:

<par:ParameterDef label="Number of fruit" name="FruitCount" type="Integer" />

This would generate :

Default Values

Default values can be set for a parameter. For example, the

<par:ParameterDef Label="Start Date" name="StartDate" type="Date" value="01-06-2009" />

This would generate:

Because it is quite common to want default date values relative to the current date there is also a special syntax for specifying default dates relative to the current time.

Now[+-]<number>[dmy]

which translates to the current time plus or minus the specified number of days,weeks,months,years. The time is also rounded depending on the specified unit so

• Now+0y is midnight at the start of the current year
• Now-1m is midnight at the start of the previous month

Optional parameters

By default all parameters are required for a form, but a parameter can be made optional by setting the ParameterDef? attribute 'optional' to true. Here's an example:

<par:ParameterDef name="PlanB" type="String" optional="true" />

Length

The size of the text area generated for a String parameter is controlled by the length attribute. The example below shows several String parameters defined with differing lengths:

<par:ParameterDef name="Little" type="String" length="8"/>
<par:ParameterDef name="Medium" type="String" length="256"/>
<par:ParameterDef name="Big" type="String" length="1024"/>

This would generate:

ReadOnly Paremeters

In some cases a read-only parameter may be required. This can be accomplished by using a ReadOnly parameter type. Below is an example:

<par:ParameterDef name="Username" type="ReadOnly" value="bob" />

This would generate:

Formatting Parameters

The way parameter elements are expanded into the report can be fine tuned by adding a format parameter to Parameter element.

• Date forces the value to be formatted as a date/time.
• Id formats a classifier object as its integer Id. This is useful when parameters are used in filters.
• Name formats a classifier object as its default Name
• expression:expr evaluates the expression expr on the target object.
• Period formats a period object as the XML needed to configure the reporting period of the report.
• ConcisePeriod formats a period object as concise human readable text.

You can provide a custom formatting object (that implements uk.ac.ed.epcc.safe.accounting.formatters.value.ValueFormatter) by setting the class.Formatterformat-name configuration property.

If a parameter is going to be used to configure a different reporting element rather than provide user visible output directly then this requires the format of the Parameter element to match the parse format of the configuration element. In these cases it is frequently possible to use a ParameterRef element instead of Parameter and omit the formatting.

Complex Formatting

<par:FormatParameter name="project">
<rep:table>
<rep:tr><rep:th>Project Start</rep:th><rep:td>$[Date]{StartedTimestamp}</rep:td></rep:tr>
<rep:tr><rep:th>Project End</rep:th><rep:td>$[Date]{CompletedTimestamp}</rep:td></rep:tr>
<rep:tr><rep:th>Project Manager</rep:th><rep:td>${@NAME(PersonID)}</rep:td></rep:tr>
<rep:tr><rep:th>Project Executive</rep:th><rep:td>${@NAME(ProjectPI)}</rep:td></rep:tr>
<rep:tr><rep:th>Funding Body</rep:th><rep:td>${@NAME(FundingBodyID)}</rep:td></rep:tr>
<rep:tr><rep:th>Funding details</rep:th><rep:td>${FundingDetails}</rep:td></rep:tr>
<rep:tr><rep:th>Grant Code(s)</rep:th><rep:td>${GrantCode}</rep:td></rep:tr>
<rep:tr><rep:th>Review Date</rep:th><rep:td>$[Date]{ReviewDate}</rep:td></rep:tr>
</rep:table>
</par:FormatParameter> 

Repeating parameters

<par:For var="project" source="Project">
<fil:EQ><fil:Property>Status</fil:Property><fil:Value>A</fil:Value></fil:EQ>
<par:Content>

<rep:Text> Project <par:Parameter name="project"/> %lt;/Text>
  
</par:Content>
</par:For>

<par:Repeat name="PeriodParameter" var="SubPeriod" split="Period">
Sub-Period is <par:Parameter name="SubPeriod" format="ConcisePeriod"/>
</par:Repeat>