Templated Reports

Overview

CSPro supports creating dynamic reports based on CSPro's text templates system, where static text is combined with delimiters, ~~, ~~~, and <? ?>, that allow the dynamic creation of sections of the report. Templated reports are defined in files, the text of which is wrapped as a CSPro logic object of the type Report.

Generally templated reports are written in HTML or Markdown, but they can be any kind of text-based file. The report's format can be modified by changing the report properties. This format is used when encoding dynamic text added to the document using ~~ fills or when using logic functions such as Report.writeEncodedLine.

Read the text templates documentation to learn how to use logic to create dynamic reports, as well as how to preview reports from the CSPro Designer or from CSCode.

Functionality

Each templated report is a CSPro logic object of type Report, which is a kind of StringWriter. The following functions can be called via dot notation:

Function	Description
save	Saves the report to a file.
view	Displays the report in an embedded web browser.
write	Writes text to the report without encoding.
writeEncoded	Writes text to the report with encoding.
writeEncodedLine	Writes text and a newline to the report with encoding.
writeLine	Writes text and a newline to the report without encoding.

getLabel	Returns the symbol's label.
getName	Returns the symbol's name.
getJson	Returns the symbol's metadata and value represented in JSON.
getValueJson	Returns the symbol's value represented in JSON.
setValueFromJson	Modifies the symbol based on a JSON representation of the value.

In addition to these object functions, templated reports can be used as arguments to the filename and view functions.

Frequency tables can be written directly to a report using the Freq.save function.

Assignments

When a templated report is used as an argument to a user-defined function (as a Report object), it is passed by reference.

Because a templated report is a kind of StringWriter, it can be passed by reference to user-defined functions that take StringWriter objects.

Add, Remove, and Rename

A templated report can be added to an application by selecting Manage Application Files under the Files menu. If creating a new HTML file, an additional dialog will be displayed with template options. The templates have an HTML scaffolding which includes popular CSS and JavaScript libraries. A templated report can be removed from the application by using the same Manage Application Files interface.

The name of the report is automatically created based on the filename, but can be modified by changing the report properties.

Conversions

Report objects can be converted to and from JSON strings.

Example 1 (Markdown)

### Report generated at ~~timestring()~~

Example 2 (HTML)

<?
numeric partial_count = 0;
numeric complete_count = 0;

forcase HOUSEHOLD_DICT do
if ispartial(HOUSEHOLD_DICT) then
inc(partial_count);
else
inc(complete_count);
endif;
endfor;
?>

<p><b>~~getsymbol(HOUSEHOLD_DICT)~~</b> has ~~partial_count~~ partial case(s) and ~~complete_count~~ complete case(s).</p>