CSPro can create HTML reports using case data as well as results from queries into paradata and other data sets. By specifying tags in your report template, you indicate to a templating engine what areas of your report are dynamic, and then via the setreportdata function, CSPro creates an object that the templating engine uses to render a dynamic report. The reporting system also supports the ability to automatically run queries on data sets based on queries specified in the report template.

This example will demonstrate how to create a simple report using Mustache, the default templating engine. The basic report template is a standard HTML file to which you add two components. First, you add a div block with the id cspro_report. This is the placeholder block where the template engine will place the results of its templating.

Second, you specify the text that you want to pass to the templating engine. Using the script element, you specify the type, application/vnd.cspro.report-template, as well as the id, cspro_report_template. In between the script tags, you specify the HTML. Using Mustache, replacement parameters are defined in between double brackets {{ ... }}, and # and / are used to start and end processing on elements of an array.

When CSPro passes this template to Mustache, the templating engine will look to replace {{title}}, and then for each occurrence (array element) of PERSON_REC, it will replace {{NAME}}, {{SEX}}, and {{AGE}}. Once it has done this, it will replace the cspro_report block with the dynamic contents.

Within CSPro, we must pass these parameters to the reporting system. Assuming that our template is saved to a file named simple_report.html, then our code might be as follows:

The calls to setreportdata set the data for the title and copy the information on the person record to an array that can be accessed in the template. The call to report specifies the name of the template. CSPro will read the template, pass in the title and person record data, and display the report in a web browser.

There are a few components that make up the reporting system, each described in detail below.

The first component is the data itself. Via calls to setreportdata, CSPro creates a JSON object and embeds it as a script with the id cspro_report_data. If your template has such an id defined, it will be overwritten; otherwise, it will be inserted in the output. If you want to define your own templating engine, it must be able to work with this JSON object.

As described above, the report template contains the HTML text that will be passed to the templating engine. That, along with the JSON data, is what turns the template into a dynamic report. The template has a few parameters:

The type must always be application/vnd.cspro.report-template.

The id uniquely identifies the script block. There are no restrictions on its name, but if you want to use the basic report functionality, then the id must be cspro_report_template and there must be a div block with the id cspro_report.

The optional data-template-engines specifies the names of the templating engines that are required to create the report. Separate multiple names with whitespace. If not specified, and if the id is cspro_report_template, Mustache will be used, as that engine comes installed with CSPro. If you specify a templating engine that CSPro cannot locate, the report generation will result in an error.

The optional data-queries specifies the names of any queries whose execution is required to create the report. Separate multiple names with whitespace. CSPro will check if data with the query name has been set via setreportdata. If not, it will search for a query with the proper name, and if found, execute it. If no suitable query can be found, the report generation will result in an error.

Any queries defined in your template will be executed prior to CSPro generating the report. Queries will be passed through the setreportdata/sqlquery functions with the result set stored under the attribute defined by data-query-name. The query has a few parameters:

The type must always be application/vnd.cspro.query.

The data-query-name is the name that CSPro uses to refer to the query. You do not need to specify an id, as CSPro uses this name instead. This is the name that corresponds to entries in a report template's data-queries.

The data-description is optional text that may be used to give a more complete description of the query.

The data-source identifies the source of the query. The reporting system must know on which database to execute the query. The options are either paradata, to execute a query on the currently open paradata log, or a dictionary name, in which case the query is executed on the currently open CSPro data source associated with that dictionary.

Most users will not have a reason to add a new templating engine, as Mustache is sufficient for most reports, but some advanced users may want to define their own engine. The engine has a few parameters:

The type must always be application/vnd.cspro.template-engine.

The data-template-engine-name is the name that CSPro uses to refer to the template engine. You do not need to specify an id, as CSPro uses this name instead. This is the name that corresponds to entries in a report template's data-template-engines.

The optional data-script-type specifies the type of code located in the script block. If not specified, it defaults to application/javascript.

The optional data-include-src identifies the file, generally a JavaScript file, that contains the source for the templating engine.

The optional data-include-type specifies the type of code found in the file identified by data-include-src. If not specified, it defaults to application/javascript.

CSPro will include in the HTML report the script block of any templating engine necessary to generate the report, as well as links to any (JavaScript) files required to run the template.

CSPro first reads in any report templates and determines what queries and template engines are required to create the report. It checks any data set via setreportdata, and if that data has an attribute with the same name as a query, then it is assumed that that data overrides the query and the query required by the template is assumed to be handled and is ignored. CSPro then looks in the report template for the definition of any queries and template engines. If they are found, then they are processed.

However, if CSPro cannot find the definition of a query or template engine in the report template, it looks in two places for these definitions, which can be included in report script definition files, which have the extension .csrs. These files consist of script blocks defining queries and template engines. First, CSPro looks in the directory where the report is being created and loads any .csrs files in that directory. If CSPro cannot find the definition of a query or template engine in those files, it then loads the .csrs files that come with default CSPro installation. If it cannot find them in either of these locations, the report generation will result in an error.

To see an example of how this works, create a basic report, using the Mustache engine, and the output of the report will use the engine as it is defined in "C:\Program Files (x86)\CSPro 7.3\Reports\CSPro Reports.csrs." You could override the default Mustache behavior by adding a template engine with the name "mustache" to your report template or to a .csrs file in the directory where your report will be created.

See also: Report Function, SetReportData Function, SqlQuery Function