Report function

I've added a report function to the stable branch. In practise this is 
implemented as two new export modules; one for displaying a report about a 
single case, and one for displaying a report about the whole data.

This works for me, but could use some more testing. Also, there are a few 
eval() in there which I need to either wrap in Safe or check for dangerous
characters. Until I've done that, the report function is disabled per 
default.

The following is the instruction file now residing in docs/REPORTS.txt. 
There is an example of how it looks towards the end.

...

INSTALLING
----------
From version 3.2.6 and forward, Mod_Survey is distributed with an 
optional report function. For now, this function is not enabled
per default. To enable the function, add the following to survey.conf
near the top of the file:

   PerlSetEnv _SURVEY_EXPORT_overview "Survey::Export::OverviewReport"
   PerlSetEnv _SURVEY_EXPORT_case     "Survey::Export::CaseReport"

And change this line

   PerlSetEnv   _SURVEY_OPTIONAL_EXPORTS "browse,desc,freq,gfreq"

So that it reads

   PerlSetEnv   _SURVEY_OPTIONAL_EXPORTS "browse,desc,freq,gfreq,overview,case"

Then restart apache.



REPORT FILE STRUCTURE
---------------------
To make a report, create a new text file with the same base name as the 
survey file but with the extension ".report" instead. (For example, the 
report for a survey called "example.survey" should be named 
"example.report).

The file should have three sections:

<SELECTOR>[variable]</SELECTOR>
<OVERVIEW>[html code]</OVERVIEW>
<CASE>[html code]</CASE>

SELECTOR is the variable used to select which case to display for a
case report.

OVERVIEW is a block of html code intermixed with special tags (see
below) to display when an overview report is requested.

CASE is a block of html code intermixed with special tags (see
below) to display when a case report is requested.



OVERVIEW REPORTS
----------------
The overview section is a block of html code where the following tags
will be replaced with the value they correspond to:

<SURVEY:COUNT VARIABLE="[variable]" />
<SURVEY:LEGAL VARIABLE="[variable]" />
<SURVEY:ILLEGAL VARIABLE="[variable]" />
<SURVEY:MIN VARIABLE="[variable]" />
<SURVEY:Q1 VARIABLE="[variable]" />
<SURVEY:MEDIAN VARIABLE="[variable]" />
<SURVEY:MEAN VARIABLE="[variable]" />
<SURVEY:Q3 VARIABLE="[variable]" />
<SURVEY:MAX VARIABLE="[variable]" />
<SURVEY:SUM VARIABLE="[variable]" />
<SURVEY:MODE VARIABLE="[variable]" />
<SURVEY:RANGE VARIABLE="[variable]" />
<SURVEY:IQR VARIABLE="[variable]" />
<SURVEY:VARIANCE VARIABLE="[variable]" />
<SURVEY:STDDEV VARIABLE="[variable]" />

The tag names should be self-explanatory. The [variable] is which 
variable to calculate the requested descriptive statistics on.



CASE REPORTS
------------
The case section is a block of html code where the following tags
will be replaced with the value they correspond to:

<SURVEY:VALUE VARIABLE="[variable]" />
<SURVEY:LABEL VARIABLE="[variable]" />
<SURVEY:QUESTION VARIABLE="[variable]" />
<SURVEY:CALCULATED CALCULATION="[calculation]" />
<SURVEY:INTERVAL CALCULATION="[calculation]" INTERVALS="[intervals]" />

<SURVEY:VALUE> is the value of a submitted variable.

<SURVEY:LABEL> is the label corresponding to the submitted value.

<SURVEY:QUESTION> is the question text for the variable.

<SURVEY:CALCULATED> performs a calculation. The [calculation] field
consists of $[variable] and mathematical expressions. For example
"$myval1 + $myval2" would sum the submitted variables "myval1" and
"myval2".

<SURVEY:INTERVAL> replaces a calculated value with a label based on
an interval description. The [calculation] field is as above. The
[intervals] field have the format "interval:label[,interval:label..]".
For example "1-12:child,13-19:teen,20-25:young adult,26-110:elderly".



HOW TO ACCESS THE REPORT
------------------------
The reports work as any other export module. Simply go to the data
meny and click the corresponding report type.



EXAMPLE REPORT
--------------
Assume we have a survey that collects the variables name, age and sex. 
The contents of the report file could be:

   <SELECTOR>name</SELECTOR>

   <CASE>
     <html><head><title>Case report</title></head><body>
     <h1>Case report</h1>
     <SURVEY:VALUE VARIABLE="name" /> is a <SURVEY:VALUE VARIABLE="age" />
     year old <SURVEY:LABEL VARIABLE="sex" />.
     </body></html>
   </CASE>

   <OVERVIEW>
     <html><head><title>Overview report</title></head><body>
     <h1>Overview report</h1>
     The average age of the respondents is <SURVEY:MEAN VARIABLE="age" />
   </OVERVIEW>

The case report would display for example "Joel is a 32 year old male.", 
while the overview report would display for example "The average age of
the respondents is 25.4".


   // Joel
Skickat av Joel Palmius <[email protected]>
till survey-discussion