====== Reports ======
Reports are HTML templates that display the result of a Query.
As with forms you can create a Report XML file that contains an HTML template to display the data, or you can call the default template to display a Report using only the table name or a registry file.
To display a Report using only a table see the Report Table chapter.

===== Create a Report =====
Each Report requires a Query. So before starting a new Report, you need to create the query associated with it (see the chapter called sqlSavedQuery). 
You will find a blank template of a Report file in : pas/templates/
Example : Content of the file : “reports/Display one news.report.xml”
<code xml>
<?xml version="1.0"?>
  <report>
    <idreport><![CDATA[555]]></idreport>
    <idquery><![CDATA[onenews]]></idquery>
    <numrow><![CDATA[0]]></numrow>
    <name><![CDATA[Display one news item]]></name>
    <header><![CDATA[<TABLE class="tableform">]]></header>
    <row><![CDATA[<TR>
  <TD class="tabletdformfield"><h3>[title]</h3> ([newsdate])</td>
</tr><TR>
  <TD class="tabletdformfield">[article]</td>
</tr>]]></row>
    <footer><![CDATA[</table>]]></footer>
    <descr><![CDATA[This report displays only one news item.]]></descr>
    <recprow><![CDATA[0]]></recprow>
  </report>
</code>
The Report file contains the following tags :
idreport: Unique id of the Report used as primary key if the Report is moved to the database, unused when Reports are stored as XML files.
idquery: Name of the query associated with the Report.
numrow: Number of rows that will be displayed for that Report, 0 or 1 will display one record per row.
recprow: Number of records per row.
name: Name of the Report.
header: Header HTML template of the Report. This is html that you can modify to change the layout of the form.  
row: Row HTML template of the Report. This is html that you can modify to change the layout of the form. 
footer: Footer HTML template of the Report. This is html that you can modify to change the layout of the form. 
descr: Description of the Report. The description is used by pagebuilder to describe the report to designers.

The header is executed and displayed first, then the row is executed and displayed for each row in the result set, and after that the footer is executed and displayed.
When a Report is displayed, it works in 2 steps. First all of the tags with [] are replaced with their values or are executed based on the information in the registry. 
Then the PHP scripts in the Report are executed.
In addition to the name, description and query you have 2 other fields. 
Number of rows and number of records per row.
Numrow, Number of rows: This will limit the number of rows that will be displayed by the Report.
Recprow, Number of records per row: by default 0. This allows you to display more than one record in the row filed. By default it displays one record per row and the notation for each field is like [fieldname], but in some cases you need to display more than one record in one row. Then the notation becomes: [fieldname:0] [fieldname:1] where the number is the record number you display in that row.
It is very useful if you want to display your records in 2 columns, for example.

===== Fields Tag =====
In the row the fields of the table are presented in []. They have different notation and a few predefined functions. All the PAS variables are inside [] for report values or field names.
The report class will look for all the [variable_name] and will look for a variable_name in your query result set or values. If the report class finds one it will replace it with the value from your query result.
If the variable_name has an entry in the associate registry the report class will apply the registry for that variable_name and return the value processed by the registry.

If you want to use an array inside your PHP scripts in a report you need to escape the [].
For example :
<code php>
<?php $arrayofvalue\[key1\] = $value1 ; ?>
</code>

===== Multiple Data Records per row =====
If you have set Recprow greater than 0, then you can access multiple records within one row.
For example: [fieldname:0] will display the first record, [fieldname:1], [fieldname:2] the second and third.
This is very useful to display HTML tables with multiple records per line.
Warning a lot of Report functions don't support multiple record per row.

===== Function Call =====
With the [] notation you can also execute functions with the following syntax :
[function_name:param1:param2:param3:]

for example :
<td>[noreg:idproduct:]</td>
will execute the built-in function noreg with the idproduct field as a value. Noreg is a function that allows you to skip the execution of the registry for a specific field.
See Appendix B for the list of available functions.


===== Install a Report on a page =====
To display a Report in your PHP page you need to create a Report object and load the Report template with:
<code php>
<?php
  $r_client = new Report($conx, “display client list”);
  $r_client->execute();
?>
</code>
This example will execute the Report called “display client list”.
If you don't have any PHP scripts inside the Report template, you can replace the call to the execute() method with:
<code php>
  $r_client->display();
</code>
In some cases you may want to display a Report but using a different query. You'll need to overwrite the saved query of the Report.
You can do that with the following :
<code php>
<?php
  $r_client = new Report($conx, “display client list”);
  $r_client->setSavedQuery(“only new client”);
  $r_client->squery->query();
  $r_client->execute();
?>
</code>
Or you can feed an sql statement directly to the Report:
<code php>
<?php
  $r_client = new Report($conx, “display client list”);
  $r_client->squery = new sqlQuery($conx);
  $r_client->squery->query(“SELECT * FROM client ORDER BY name”);
  $r_client->setNoData(false);
  $r_client->execute();
?>
</code>
In case your Report didn't have a query set (<idquery>0</idquery>) then $r_client->setNoData(false) will tell the Report to use the new set query for data.

You can also overwrite the registry that a Report uses. By default the Report and saved query are going to use the registry associated with it. But in some specific pages you may want to use an alternate registry.
<code php>
<?php
  $rt_client = new Report($conx, “display client list”);
  $rt_client->setRegistry(“clientadministration”);
  $rt_client->execute();
?>
</code>

===== Display a Report with no Database Data =====
By default a Report will get the data to display from a database using an SQL Query.
If you want to display a report with data from an XML file for example, you have a few methods available in the Report class.

  * setValues(Array)
  * addValues(Array)
  * setValue(varname, varvalue)
  * setRowValues(Array[][]) 
  * getValues()

The Report object internally manages 2 Arrays, one called values that applies once to the Report (header, row and footer) and one called row_values which is a two-dimensional array that contains the variable name and its value for each row.

For example:
<code php>
<?php 
$row_data[1]['name'] = "MacOS X";
$row_data[1]['description'] = "Operating system for Apple Hardware";
$row_data[1]['url_detail_product'] = "http://www.apple.com";
$row_data[2]['name'] = "Windows XP";
$row_data[2]['description'] = "The most used OS for PC computer";
$row_data[2]['url_detail_product'] = "http://www.microsoft.com";
$row_data[3]['name'] = "Linux";
$row_data[3]['description'] = "One of the best operating systems";
$row_data[3]['url_detail_product'] = "http://www.novell.com";

$r_products = new Report($conx, "aws.productListing");
$r_products->setValue("product_type", "Operating Systems");
$r_products->setRowValues($row_data);
$r_products->execute() ; 
?>
</code>

aws.productListing.report.xml source:
<code xml>
<?xml version="1.0"?>
  <report>
    <idreport><![CDATA[555]]></idreport>
    <name><![CDATA[aws.productListing]]></name>
    <descr><![CDATA[]]></descr>
    <numrow><![CDATA[0]]></numrow>
    <idquery><![CDATA[0]]></idquery>
    <header><![CDATA[
  Display products type : [product_type]
  <TABLE class="tableform"><TR>
  <TD class="tabletdheader">Name : </TD>
  <TD class="tabletdheader">Description:</TD>
  </tr>]]></header>
    <row><![CDATA[
<TR>
  <TD class="tabletdformfield"><A href="[url_detail_product]">[name]</a></TD>
  <TD class="tabletdformfield">[description]</TD>  
</TR>
]]></row>
    <footer><![CDATA[</TABLE>]]></footer>
    <recprow><![CDATA[]]></recprow>
  </report>
</code>
You can see that the <idquery> is set to 0 this means that no SQL query will be used for this Report.

The setRowValues method will set the values for each rows.
The setValue will set the values mainly for the header and footer.

The output will result in:


===== Report Table =====
The Report table is an extension of the Report object.
The Report Table object doesn't require an existing report file to display the Report. It contains 2 extra methods that create a default query and a default template. So you only need the tablename to display its content and links to add/edit/delete records.
<code php>
<?php
  $rt_client = new ReportTable($conx);
  $rt_client->setDefault(“client”);
  $rt_client->setQuery();
  $rt_client->execute();
?>
</code>

This will display the content of the client table with one column per field. Each column is displayed with links to change the sort order of the displayed table and on the side, it displays links to Edit/Delete records.
You can use the built-in Report template or use an external Report template.
External Report template are themselves Reports and they can be found in the /report directory.
They end with the extension : tpl.report.xml, to generate one Report 3 Report templates are needed, with the following extensions : header.tpl.report.xml, row.tpl.report.xml, footer.tpl.report.xml.
In the pas/sitetemplate/report you will find a Report template called : default_report.

You can set the default_report by adding a named constant with the name of your Report template.
<code php>
<?php
define(“PAS_DEFAULT_REPORT_TEMPLATE”, “ default_report”);
?>
</code>
Add that to your config file and all the ReportTable objects will use that Report template.

Or you can set it individually when displaying the Report :
<code php>
<?php
  $rt_client = new ReportTable($conx);
  $rt_clinet->setRegistry(“limited_client”);
  $rt_client->setDefault(“client”, “default_report”);
  $rt_client->setQuery();
  $rt_client->execute();
?>
</code>
Optionally you can set a different registry than the one set for the client table.
It is also possible to overwrite the default query by setting one when displaying, it will then look like :
<code php>
<?php
  $rt_client = new ReportTable($conx);
  $rt_client->setRegistry(“limited_client”);
  $rt_client->setSavedQuery(“all.limited.clients”);
  $rt_client->setDefault(“”, “default_report”);
  $rt_client->setQuery();
  $rt_client->execute();
?>
</code>

Where “all.limited.clients” is a savedQuery from the savedquery folder.

===== Sub Report =====
It is possible to display a Report within a Report. You can even create recursive Reports.
To call a Report in your Report you will need to use the sub Report function.

     [sub:report name :param1:param2:param3:]

Example :

     <div class=”text”>[sub:display one description:idproduct:name]</div>

This example will call the Report : “display one description” and send it the parameters idproduct and name.
The parameters are fields that will be replaced with their values from the database.

Its also possible to do sub ReportTable and sub Form.

Sub reportTable :
     [subTable:display one description:idproduct:name]

Sub Form :
     [subForm:editCustomer:idcustomer]

===== Generate a Report XML file from a Report template  =====
If you are using a Report template but want to customize it, you can generate an .report.xml file from the instantiated Report object.

The serializeToXML() method will serialize your report in a xml file.
You can then customized directly the generated xml and re-instanciate our new Report object any time.

You want to create a customized version of this Report:
<code php>
<?php
  $rt_client = new ReportTable($conx);
  $rt_client->setSavedQuery(“all.limited.clients”);
  $rt_client->setDefault(“”, “default_report”);
  $rt_client->setQuery();
  $rt_client->execute();
?>
</code>

Call the property: serializeToXML(<report name>)

For example:
<code php>
<?php
  $rt_client = new ReportTable($conx);
  $rt_client->setSavedQuery(“all.limited.clients”);
  $rt_client->setDefault(“”, “default_report”);
  $rt_client->setQuery();
  $rt_client->serializeToXML(“limited.clients”);
?> 
</code>

That will create the file limited.clients.report.xml inside the report directory.
You can then modify the template of that Report and display it.