Zen Report Class Parameters - Using Zen Reports

Associates the Zen report with a Zen application. A Zen report's application provides the default values for built-in class parameters. A value specified in the Zen Report itself takes priority over the value from the application. If you do not specify an application, the Zen report uses %ZEN.Report.defaultApplication.

If you define a new class parameter on the Zen report, there is no automatic logic to inherit the value from the Application. You need to define the parameter in both the report and the application. You can then use the macro $$$GETPARAMETER to get the value from the application, as illustrated in the following example:

/// User-defined parameter. Defined on Report and on Application.
Parameter COPYFROMAPP = "FromRpt";
Property CopyFromApp As %String(ZENURL = "CopyFromApp");
/// This callback is invoked after this report is instantiated
/// and before it is run.
Method %OnBeforeReport() As %Status
  {
    Set:..CopyFromApp="" ..CopyFromApp=$$$GETPARAMETER("COPYFROMAPP")
    Quit $$$OK
  }

The application and the report must use the same name for the parameter. You cannot use the macro $$$GETPARAMETER to coalesce values from parameters with different names. The user-specified Application should extend %ZEN.Report.defaultApplication.

Setting this parameter to true causes aggregates causes Zen reports to ignore National Language Settings (NLS) for aggregates. If it is set to false, NLS works transparently with Zen reports aggregates when the runtime mode is DISPLAY (2). The default value is true.

Setting this parameter enables support for aggregates in generated Excel spreadsheets. You can set it to any value that is a valid XML attribute name. The value becomes the name of an attribute that tags items in the generated XML as coming from an <aggregate> in the report. Used with DEFAULTMODE=”excel” and DEFAULTMODE=”xlsx”.

Contributes a type attribute to the xml-stylesheet instruction in the generated XSLT for the report; for example:

<?xml-stylesheet type="text/xsl"?>

The default CONTENTTYPE is text/xml.

Identifies an XML document that contains the data for the Zen report. See the section “DATASOURCE” in the chapter “Gathering Zen Report Data.”

Identifies the default output mode for the report. The user can override this parameter by setting $MODE in the URI.

If DEFAULTMODE is set to ps, you must also use the class parameter PS or the URI parameter $PS to provide the location of the PostScript printer.

A user can override the current DEFAULTMODE setting for the report class by providing a $MODE parameter in the URI when invoking the Zen report from a browser. Basic information about $MODE appears at the beginning of the section “Invoking Zen Reports from a Web Browser.” For additional information, also see “Changing Output Mode to View Intermediate Files” in the chapter “Troubleshooting Zen Reports.”

Contributes an encoding attribute to the xsl:output instruction in the generated XSLT for the report; for example:

<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="no"/>

The default ENCODING is "UTF-8". If you need to display characters outside the UTF-8 character set, for example in the Latin-1 set, provide an alternate value for ENCODING such as:

Parameter ENCODING="ISO-8859-1";

Specifies whether the data for an Excel spreadsheet should come from <attribute> or <element> tags. By default, data comes from <element> tags. Use of EXCELMODE = "attribute" is not recommended, because it is inflexible and unable to carry Excel metadata. Used with DEFAULTMODE=”excel” and DEFAULTMODE=”xlsx”.

Specifies whether a Zen report that generates an Excel spreadsheet generates a spreadsheet that contains multiple worksheets. If EXCELMULTISHEET = 1, the report generates a worksheet for each <group> element that is a direct child of <report>.

Identifies the to-excel stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid EXCELSTYLESHEET string and an XData ReportDisplay block, the EXCELSTYLESHEET parameter takes precedence over the XData block.

This string can be any of the following:

The URI of any valid XSLT stylesheet. You can use any URI that returns appropriate XSLT. Relative URIs are handled with respect to the current URI.

For general information about query parameters, see the “URI Query Parameters for Zen Reports” section in the chapter “Running Zen Reports.”
The name of a file containing a valid XSLT stylesheet. The file must reside in the directory specified in the CSP Files Physical Path for the Web Application definition for the Zen report. For example, if the URI for the Zen report class is:
```
http://localhost:57772/csp/myNamespace/mine.MyReport.cls
```
Then the syntax for the EXCELSTYLESHEET parameter is:
```
Parameter EXCELSTYLESHEET="data.xsl";
```
And the file data.xsl must reside in the directory specified as the CSP Files Physical Path. The default value for this directory is: /csp/myNamespace.
An empty string. In this case, the class generates a to-EXCEL stylesheet using the specification in its XData ReportDisplay block.

Warning:

Do not use a URI string that refers to the Zen report class in which the EXCELSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.

The XSLFOSTYLESHEET parameter performs the same function in reports that generate PDF output, and theHTMLSTYLESHEET parameter performs the same function in reports that generate HTML output.

Identifies the to-HTML stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid HTMLSTYLESHEET string and an XData ReportDisplay block, the HTMLSTYLESHEET parameter takes precedence over the XData block.

This string can be any of the following:

The URI of any valid XSLT stylesheet. You can use any URI that returns appropriate XSLT. Relative URIs are handled with respect to the current URI.

The URI string can refer to a to-HTML stylesheet created by another Zen report class in the same namespace. Use the $MODE=tohtml query parameter to specify that you want to use the to-HTML output from that class, as follows:
```
Parameter HTMLSTYLESHEET="MyApp.Report.cls?$MODE=tohtml";
```
For general information about query parameters, see the “URI Query Parameters for Zen Reports” section in the chapter “Running Zen Reports.”
The name of a file containing a valid XSLT stylesheet. The file must reside in the directory specified in the CSP Files Physical Path for the Web Application definition for the Zen report. For example, if the URI for the Zen report class is:
```
http://localhost:57772/csp/myNamespace/mine.MyReport.cls
```
Then the syntax for the HTMLSTYLESHEET parameter is:
```
Parameter HTMLSTYLESHEET="data.xsl";
```
And the file data.xsl must reside in the directory specified as the CSP Files Physical Path. The default value for this directory is: /csp/myNamespace.
An empty string. In this case, the class generates a to-HTML stylesheet using the specification in its XData ReportDisplay block.

Warning:

Do not use a URI string that refers to the Zen report class in which the HTMLSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.

The XSLFOSTYLESHEET parameter performs the same function in reports that generate PDF output, and the EXCELSTYLESHEET parameter performs the same function in reports that generate Excel spreadsheet output.

Contributes an indent attribute to the xsl:output instruction in the generated XSLT for the report; for example:

<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="no"/>

INDENT may be "yes" or "no". The default is "yes".

Allows you to define namespace declarations, for example:

"xmlns='http://mydefault' xmlns:ns1='http://namespace1'"

The namespace declarations are added to the root element of the generated XML and also to the stylesheet element of the generated XSL.

Like XMLSWITCH and XSLSWITCH, PDFSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section “Configuring Zen Reports for PDF Output.”

Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the PDF output file for the transformation from XSL-FO to PDF:

-pdf

This is the default value for PDFSWITCH.

If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its PDF output file. You must specify the correct option syntax using the PDFSWITCH class parameter in your Zen report class. For example:

Parameter PDFSWITCH = "-o";

Contributes an xsl:preserve-space instruction to the generated XSLT for the report; for example, if PRESERVESPACE="literallayout" the instruction is:

<xsl:preserve-space elements="literallayout"/>

The value of PRESERVESPACE can be a comma-separated list of element names.

There is no default PRESERVESPACE value. If none is supplied, Zen does not generate the instruction.

As described in the section “Zen Report Tutorial,” a Zen report class is also a Caché Server Page (CSP) class. Therefore, a Zen report class supports the same class parameters as a CSP page class, including the PRIVATE parameter, which plays an important role in Zen reports.

When PRIVATE is set to 1, the page is private. This means it can only be navigated to from another page within the same CSP session. For further details, see “Authentication and Encryption” in the “CSP Session Management” chapter in the book Using Caché Server Pages (CSP).

Specifies the location of a PostScript printer, such as:

Parameter PS = "\\devD630\BrotherH";

To send a report directly to the specified PostScript printer, without creating an intervening PDF file, set the DEFAULTMODE class parameter to"ps". You can also set $MODE=ps in the URI string and set the URI query parameter $PS to the location of the PostScript printer.

(Firefox only) Controls the filename suggested by the browser when you choose File > Save As to save the final output of running a Zen report in XHTML or PDF format. If you do not supply a value for the REPORTNAME class parameter, the browser uses the Zen report class name as the suggested filename.

The location for saved Zen report output is as follows:

C:\MyCache\CSP\myApp\

Where C:\MyCache is the name of your installation directory and myApp is the namespace where the Zen report class resides.

REPORTNAME does not work with Internet Explorer, Chrome, or Safari. In these cases the <report> must have a title attribute set; that title is used in the File > Save As prompt. REPORTNAME works with Firefox when XHTML is generated on the server side. Server-side generation takes place when the output format is PDF, when XSLTMODE or $XSLT is set to "server" (the default), or when you have instructed Zen reports to embed XSLT instructions within the output XHTML by setting EMBEDXSL or $EMBEDXSL to 1.

Unlike most parameters that share a name except for the $ (dollar sign), there is no relationship between REPORTNAME and the URI query parameter $REPORTNAME.

Controls the directory for output files specified by “The $REPORTNAME Query Parameter,” as described in the “Troubleshooting Zen Reports” section of the chapter “Running Zen Reports.”

REPORTDIR works with $REPORTNAME only. It does not interact with the REPORTNAME class parameter.

Name of a system Resource for which the current user must hold USE privileges in order to view this page or to invoke any of its server-side methods from the client.

RESOURCE may be a comma-delimited list of resource names. In this case, the user must hold USE privileges on at least one of the given Resources in order to use the page.

For further details, see the section “Application Resources” in the “Assets and Resources” chapter of the Caché Security Administration Guide.

The correct processing of sibling groups and elements requires caching of SQL queries. By default, Zen reports cache SQL queries (SQLCACHE=1). If you prefer not to cache queries while running Zen reports (SQLCACHE=0), then you cannot use sibling groups and elements without generating an error when compiling the Zen report class.

Contributes an xsl:strip-space instruction to the generated XSLT for the report; for example, if STRIPSPACE="*" the instruction is:

<xsl:strip-space elements="*"/>

There is no default STRIPSPACE value. If none is supplied, Zen does not generate the instruction.

Set suppressExcelHeaders="true" to suppress all headers that are normally generated when you create an Excel spreadsheet from a Zen report.

Lets you set a color for alternate table rows on a report-wide basis, instead of specifying the <table> attribute altcolor on each table. You can use the corresponding TableAltColor property when using GenerateReport. If you specify altcolor on a table, the table setting overrides TABLEALTCOLOR.

Lets you override the default behavior, which is to generate HTML5 when the browser supports it.

When UseHTML5 is "" (null), which is the default value, a report rendering in a browser generates HTML5 if it has determined that the browser supports HTML5. When UseHTML5 is non-null, the boolean value determines whether to generate HTML5 or not regardless of whether the browser supports HTML5. You can use the corresponding UseHTML5 property when using GenerateReport.

When a Zen report is shared among several servers for load balancing purposes, and when the Zen report uses elements such as <xslinclude> that refer to other Zen or CSP pages, the external PDF rendering engine needs a way to come back to the Caché CSP Gateway instead of going all the way back to the virtual IP. The attempt to go back to the virtual IP results in an error, since the gateway does not recognize that address.

It is possible to configure a Zen report class so that it substitutes the configured instance host name for the CSP Gateway whenever it constructs a full URL from the relative paths contained in <xslinclude> and other elements that supply URLs. To enable this feature, set the USEINSTANCEHOSTNAMEONRELATIVEURLS class parameter to 1 (true). The default is 0 (false).

You can enable or disable USEINSTANCEHOSTNAMEONRELATIVEURLS without knowing or setting the instance host name for the CSP Gateway. It is rarely necessary to configure an instance host name other than the default, which identifies the local Caché server and its Web server port. For more details, see the “Configuring Default Parameters” section in the “CSP Gateway Operation and Configuration” chapter of CSP Gateway Configuration Guide.

Identifies the XSL stylesheet that transforms XML provided by the ReportDefinition into a form appropriate for input to the ReportDisplay.

Like XSLSWITCH and PDFSWITCH, XMLSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section “Configuring Zen Reports for PDF Output.”

Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the XSL-FO data file for the transformation from XSL-FO to PDF:

-xml

This is the default value for XMLSWITCH.

If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its XSL-FO data file. You must specify the correct option syntax using the XMLSWITCH class parameter in your Zen report class. For example:

Parameter XMLSWITCH = "-d";

Identifies the to-XSLFO stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid XSLFOSTYLESHEET string and an XData ReportDisplay block, the XSLFOSTYLESHEET parameter takes precedence over the XData block.

This string can be any of the following:

The URI of any valid XSLT stylesheet. You can use any URI that returns appropriate XSLT. Relative URIs are handled with respect to the current URI.

The URI string can refer to a to-XSLFO stylesheet created by another Zen report class in the same namespace. Use the $MODE=toxslfo query parameter to specify that you want to use the to-XSLFO output from that class, as follows:
```
Parameter XSLFOSTYLESHEET="MyApp.Report.cls?$MODE=toxslfo";
```
For general information about query parameters, see the “URI Query Parameters for Zen Reports” section in the chapter “Running Zen Reports.”
The name of a file containing a valid XSLT stylesheet. The file must reside in the Web Application directory for the namespace in which the Zen report class resides. For example, if the URI for the Zen report class is:
```
http://localhost:57772/csp/myNamespace/mine.MyReport.cls
```
Then the syntax for the XSLFOSTYLESHEET parameter is:
```
Parameter XSLFOSTYLESHEET="data.xsl";
```
And the file data.xsl must reside in the directory specified as the CSP Files Physical Path. The default value for this directory is: /csp/myNamespace.
An empty string. In this case, the class generates a to-XSLFO stylesheet using the specification in its XData ReportDisplay block.

Warning:

Do not use a URI string that refers to the Zen report class in which the XSLFOSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.

The HTMLSTYLESHEET parameter performs the same function in reports that generate HTML output, and the EXCELSTYLESHEET parameter performs the same function in reports that generate Excel spreadsheet output.

Like XMLSWITCH and PDFSWITCH, XSLSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section “Configuring Zen Reports for PDF Output.”

Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the XSL-FO stylesheet file for the transformation from XSL-FO to PDF:

-xsl

This is the default value for XSLSWITCH.

If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its XSL-FO stylesheet file. You must specify the correct option syntax using the XSLSWITCH class parameter in your Zen report class. For example:

Parameter XSLSWITCH = "-s";

A value of "1.0" or "2.0" causes the XSLT for this report to be processed as XSLT Version 1.0 or XSLT Version 2.0, respectively. "1.0" is the default. The XSLTVERSION value affects the XSLT that a Zen report generates as well as any that it encounters in <xslt> sections, XData blocks, or external files. A user can override the current XSLTVERSION setting for the report class by providing an $XSLTVERSION parameter in the URI when invoking the Zen report from a browser.

XSLT 1.0 is the default, and requires no special preparation. XSLT 2.0 represents significant changes from XSLT 1.0, including more careful type checking and more options for controlling the flow of logic within the transformation. XSLT 2.0 transformations are not likely to work if they are interpreted as XSLT 1.0. Problems in the other direction occur less frequently: XSLT 1.0 transformations often work when interpreted as XSLT 2.0. However, they can produce different output than when interpreted as XSLT 1.0, or fail to work. There are no compatibility guarantees.

When invoked in the browser to generate XHTML, a Zen report generates XML, sends this XML to the client, then transforms this XML to XHTML on the client by following an xml-stylesheet processing instruction. The attributes for this instruction appear as query parameters in a URI string sent to the browser. Internet Explorer only understands URI instructions that have one parameter after the ? question mark. Problems can occur when the generated xml-stylesheet instructions for a Zen report class contains multiple parameters and the browser is Internet Explorer. This is particularly true if the Zen report class is marked as private by setting its CSP class parameter PRIVATE to 1 (True).

When EMBEDXSL=1 (true) Zen generates XSLT instructions embedded within the output XHTML. The default for EMBEDXSL is 0 (false), in which case Zen generates a separate XSLT file, rather than embedding the instructions in the XHTML file.

Embedding the XSLT instructions brings up the issue of uniqueness for XML elements in the output file. The default namespace http://www.w3.org/1999/xhtml cannot be the namespace for all the generated XML elements if the generated XML and XSLT are combined in a single HTTP response. To ensure fully qualified XML names, InterSystems recommends when you set EMBEDXSL=1 you also provide a namespace name and prefix by providing values for REPORTXMLNAMESPACE and REPORTXMLNAMESPACEPREFIX in the Zen report class, for example:

Parameter EMBEDXSL=1;
Parameter REPORTXMLNAMESPACE="http://www.example.com";
Parameter REPORTXMLNAMESPACEPREFIX="SR";

Then the generated XML looks like the following example and the XSLT is updated to work with this XML:

<SR:myReport xmlns:SR="http://www.example.com"
             runTime='2008-03-27 00:01:49'
             runBy='_SYSTEM' author='BOB' month='Jan'>
  <SR:SalesRep name='Jack'>

    <SR:record id='331' number='5'>
      <SR:date>2005-01-20</SR:date>
      <SR:customer>Yoyomo Inc.</SR:customer>
    </SR:record>

    <SR:record id='537' number='9'>
      <SR:date>2005-01-20</SR:date>
      <SR:customer>XenaData.com</SR:customer>
    </SR:record>

    <!-- more records omitted -->

  </SR:SalesRep>
</SR:myReport>

You can omit the REPORTXMLNAMESPACE or REPORTXMLNAMESPACEPREFIX parameters from the Zen report class. When EMBEDXSL=1 and these parameters are not set, they default as follows:

REPORTXMLNAMESPACE defaults to:

http://www.intersytems.com/mydefaultnamespace
REPORTXMLNAMESPACEPREFIX defaults to:

my

When an external DATASOURCE is identified, EMBEDXSL is ignored.

A user can override the current EMBEDXSL setting for the report class by providing a $EMBEDXSL parameter in the URI when invoking the Zen report from a browser.

Specifies the XML namespace to be used in the generated XML report. This is especially important if you are using EMBEDXSL=1. There is a default name, http://www.intersytems.com/mydefaultnamespace, but you can specify your own choice. For details, see EMBEDXSL.

Specifies the XML namespace prefix to be used in the generated XML report. This is especially important if you are using EMBEDXSL=1. There is a default prefix, my, but you can specify your own choice. For details, see EMBEDXSL.

Allows you to specify the processing mode to use if the URI parameter $MODE is not specified. DEFAULTMODE serves this same purpose, but cannot be used if the Zen report class is marked as private by setting its CSP class parameter PRIVATE to 1 (True). STYLESHEETDEFAULTMODE is provided to help in this case. Otherwise it is not needed.

If your Zen report uses both DEFAULTMODE and STYLESHEETDEFAULTMODE, you must set them carefully. Be aware that if both are set and the URI parameter $MODE is not specified, then STYLESHEETDEFAULTMODE overrides DEFAULTMODE as the default style mode.

If you want to use the STYLESHEETDEFAULTMODE, and your desired output format is:

Excel spreadsheet, use this combination of settings and values:
- Class parameter DEFAULTMODE may have any value
- Class parameter STYLESHEETDEFAULTMODE="toexcel"
- URI query string parameter $MODE="excel" or $MODE="xlsx"
XHTML, use this combination of settings and values:
- Class parameter DEFAULTMODE may have any value
- Class parameter STYLESHEETDEFAULTMODE="tohtml"
- URI query string parameter $MODE="html"
PDF, use this combination:
- Class parameter DEFAULTMODE may have any value
- Class parameter STYLESHEETDEFAULTMODE="toxslfo"
- URI query string parameter $MODE="pdf"
XML, use this combination:
- Class parameter DEFAULTMODE may have any value
- Omit the class parameter STYLESHEETDEFAULTMODE
- Omit $MODE, or use $MODE="xml"

The full list of possible values for STYLESHEETDEFAULTMODE is:

"tohtml" — To-HTML stylesheet in XSLT format
"toxslfo" — To-XSLFO stylesheet in XSLT format

When USETEMPFILES=1 (true) Zen writes its generated XSLT stylesheet to a file. It subsequently uses the generated XSLT stylesheet in the file to generate the output XHTML. The default for USETEMPFILES is 0 (false). In this case Zen generates and uses XSLT but does not save it to a file.

For further details, including the file locations for the generated XSLT stylesheet file, see “The $USETEMPFILES Query Parameter” in the “Troubleshooting Zen Reports” section of the chapter “Running Zen Reports.” $USETEMPFILES is the equivalent URI query parameter for USETEMPFILES.

Allows you to specify where XSLT transformation occurs, without adding to the number of query parameters in the URI string for the Zen report. XSLTMODE can have the value "browser" or "server". This causes the XSLT to be processed, and XHTML to be generated, on the server or browser, respectively.

XSLT processing is expensive; it could compromise the scalability of the application to shift XSLT processing to the server. However, the XSLTMODE option is provided to allow that flexibility. The default XSLTMODE is "server". Also see USETEMPFILES.

A user can override the current XSLTMODE setting for the report class by providing a $XSLT parameter in the URI when invoking the Zen report from a browser.

When the output mode is PDF, some processing always occurs on the server, because the third-party PDF generator engine (RenderX or FOP) runs on the server.