Report Page Templates

Overview

Page templates control the formatting of data in a report onto a printed page as a PDF. The page template controls:

• The paper size
• Printing multiple report pages on a single sheet for labels
• Standard content included on each page (e.g. the name of the report or legally required text)
• Merging data onto fixed parts of the page (e.g. placing billing and shipping address at the top of an invoice)
• Flowing data into the page (e.g. printing the lines of the invoice across multiple page)
• Where page numbers appear on the page

A page template may be specified for any report. If the page template is not specified, the report use the default formatting.

Page templates do not affect how a report gets exported to Excel.

 

Paper and label configuration

Each sheet of paper in the printed document may contain one or more pages from the report.

The simplest case is that each page of the report is on its own sheet. In this case, the page template selects the choices of 8.5" by 11" (US letter) paper, A4 paper, or a custom user specified paper size. The page template also selects whether the paper is oriented vertically (portrait) or horizontally (landscape). The width and height of a custom page size may be specified as a CSS distance or a decimal number that will be interpreted as inches. This can be used for printing on large paper (such as US legal or A3), or with a label printer on individual labels.

Alternatively the page template can specify that multiple report pages should be printed with several pages on each sheet. This is specified by the compatible label paper product:

• Avery 5167 Letter size 1/2" x 1 3/4"
• Avery 5160 Letter size 1" x 2 5/8"
• Avery 5163 Letter size 2" x 4"
• Avery 5168 Letter size 3 1/2" x 5" (portrait or landscape)
• Avery 5126 Letter size 8 1/2" x 5 1/2" (portrait or landscape)
• Avery DPS30-100 A4 size 70mm x 30mm
• Avery L7158 A4 size 64mm x 26.7mm
• Avery L4737 A4 size 63.5mm x 29.6mm
• Avery L7160 A4 size 63.5mm x 38.1mm
• Austab CL33 A4 size 70mm x 25.4mm
• Austab CL08:1 A4 size 105mm x 73.8mm

For example, selecting Avery 5163 Letter size 2" x 4" will print 10 report pages per sheet of paper in such a way that they line up with boundaries of the Avery 5163 label paper product.

 

Page breaks and report sections

The formatting engine starts a new page when the rows in the report do not fit the available space on the current page or when a forced page break has been selected for a primary column on the report.

When a forced page break is triggered, then the new page is considered the first page of a new section. Sections control how values in the report bind to variables in the page template.

When the rows in the report do not fit the current page, the following pages are considered continuation pages of the current section and do not start a new section of the report.

For example, consider a report and page template designed to print quote documents. On the report, select the Quotes with item detail data set, select the primary column Quote: Quote ID, set the grouping option to Page break before, and add additional columns for any data to be included in the document. With these selections, each quote will start a new section. If there are too many lines in the quote to fit on a single page, the additional lines will flow onto continuation pages. Since each quote is in its own section, the page template can include basic information about the quote (for example the customer name) on all pages of the quote.

 

Variables in page templates

Variables in page templates contain data from the report, report arguments supplied by the user, and information from the formatting engine.

The easiest way to add variables to the template content for a page template is to use the Insert variable into template contentselector at the bottom of the page. The selector lists all available variables on the current report. Select an item from this list to insert the correct template directive into the template content for that variable.

Both primary columns and calculated columns in the report create variables for the page template. The value for the variable is the value in the corresponding column in the first row of the current section of the report. In other words, the value for the variable is set on the first page of each section and does not change for continuation pages.

Variables for the additional information from the formatting engine are:

pageIndex

Page number of current page

pageTemplateIndex

Page number within the current section

pageTemplateFirst

True on the first page of a section. False on continuation pages. Useful for changing the page template on continuation pages using conditionals in the template content.

pageMultipleIndex

When using the option to print each section multiple times, the number of the copy currently being printed.

pageMultipleCount

When using the option to print each section multiple times, the number of copies being printed of the current section.

pageMultipleFirst

When using the option to print each section multiple times, true when the current copy is the first for the section.

pageMultipleLast

When using the option to print each section multiple times, true when the current copy is the last for the section.

pageMultipleTotal

When using the option to print each section multiple times, the total of the count of copies printed for each section.

printDate

Date the document was printed

Variables for report arguments contain the values entered by the user for named parameters when the report was run. For example, for a labels report the user may need to be able to specify the number of labels to print. Create a named parameter named something like "How many to print" and select that variable in the page template for the Print each page multiple times option. Each time the report is printed the user will be prompted to supply a value for the name parameter and that value will be used as the count to print.

 

Printing each report page multiple times

When printing labels it is frequently the case that each page of the report should be printed multiple times. The "Print each page multiple times" option allows the page template to generate multiple output page for each report page. The option allows the selection of any of the variables in the report as the number of times that the page should be printed. The variable selected is interpreted as a number and rounded to the nearest integer. If the value is not numeric (e.g. a string or blank) or if rounded number is less than or equal to zero, then that page will not be printed.

For example, when printing labels for products received on a purchase shipment you will typically want one label for each case received. Add the "Quantity case or case equivalent, sum" as a calculated column to the report, and then select the corresponding variable "Quantity case or case equivalent, sum" for the "Print each page multiple times" option on the page template to print one label for each case.

 

Template content

Template content is the part of a page template that controls the actual layout of each report page. The template content is specified as a template that is merged with the variables on the page to generate HTML and CSS. The template is merged with the variables on each report page, which allows the template to place different information on different report pages.

The formatting engine uses the HTML and CSS to render information onto the report page and control where rows from the report are flowed onto the report page. HTML and CSS generated from the template content does not flow from page to page (as it would when printed from a browser) but gets cropped to the area of the current page.

As described earlier in this document, report pages may be printed multiple times and multiple report pages may be printed on a single sheet of paper. These options are not affected by the template content and the template content does not affect the other options. First the template content is used to format each report page. Once all the report pages are generated, then the other options in the page template control how the generated report pages are placed onto each sheet of paper.

 

Additional template directives

In the context of page templates, there is an additional directive available while merging data to produce HTML and CSS

commaList

The commaList directive takes any number of parameters (either variables or constant strings) and generates a fully escaped comma separated list of the arguments. The arguments are first escaped per the rules CSV files: any value with a quote or a comma is placed in quotes, and any quote in a value is replaced by a pair of consecutive quotes. Then the comma separated list is escaped using HTML entities. For example, use the commaList directive to embed variables and text in an image using the barcode URI scheme:

 

<img src="barcode:{{commaList productProductIdConsolidate "Hello" shipmentItemLotIdConsolidate}}">

shortCode

The shortCode directive searches for the Finale defined short code for the combination of a product id, a packing, and a lot id. The arguments specified are product id, packing, lot id. The packing and lot is optional. If there is no short code defined for a combination then the directive returns an empty string. The shortCode directive can be used with the barcode URI scheme to create a barcode that will scan easily even if the product id and lot id are very long.

 

<img src="barcode:{{shortCode productProductIdConsolidate "cs 12/1" shipmentItemLotIdConsolidate}}">

formula

The formula directive evaluates a formula and inserts the results into the document. This example uses a formula to strip the initial Lot: or Mfg: from a formatted lot id:

 

{{#formula}} fiHtmlEntitiesEncode(fiJoin(fiSlice(fiSplit(v," "), 1), " ")) {{/formula}}

sectionBegin

The sectionBegin directive inserts content into the flow of the document before the current section of the report. The content appears before the column headers on the first page of the section. The sectionBegin templates is evaluated once per section of the document and can use variables from the report, but not page related variables from the formatting engine. The sectionBegin directive establishes a new containing block for the inserted content, therefore an absolutely positioned element inside the directive will be positioned relative to the left margin of the content region and the current vertical position of the flow. Example:

 

{{#sectionBegin}}
  <div style="position:absolute;left:0in;top:0pt;height:14pt;width:7.5in;
              border-width:.5pt ;border-color:#000;background-color:#eee;text-align:center;">
    SECTION BEGIN
  </div>
{{/sectionBegin}}

This places a light gray box with a black border and the words "SECTION BEGIN" before the first set of columns headers for each section.

sectionEnd

The sectionEnd directive is similar to the sectionBegin directive, except the contents are placed at the end of the section.

dataTableOptions

The dataTableOptions directive provide additional control for how the data for the report is output. Currently there is only one option. The option is filterColumnWidthZero controls how the data table is exported to Excel, CSV, and TSV formats. If the option has the value true, then any columns whose width is zero in the report settings are not included in the exported data. Example:

 

{{dataTableOptions filterColumnWidthZero="true"}}

dataTableHeader

The dataTableHeader directive adds additional data rows and columns to the top of each section in the report. The rows and columns are generated by the page template and inserted above the regular header row for the report. This is useful to generate formats that have important data placed at the top of the data above the main lines of the report (such as order ship to and ship from data above the lines on the order. The contents dataTableHeader directive must be an HTML table. Example:

 

{{#dataTableHeader}}
<table>
<tr><td>PlanName</td><td>{{parameter_000}}</td></tr>
<tr><td>ShipToCountry</td><td>US</td></tr>
<tr><td>AddressName</td><td>{{shipmentShipFromName}}</td></tr>
<tr><td>AddressPostalCode</td><td>{{shipmentShipFromPostalCode}}</td></tr>
<tr><td></td></tr>
</table>
{{/dataTableHeader}}

This generates an extra five rows at the top of section. The rows have a mix of static text defined in the page template, and dynamic content merged from variables .

 

Page template regions

Page templates can include named regions using the CSS property flow-from. The software will use the named regions to flow content into the page template.

 

Page number region

An element with flow-from identifier of pageNumber with have the content Page N of M flowed in. The value N is the current page number and the value M is the total number of pages printed.

 

Content region

An element with flow-from identifier of content will have the page content flowed into that region. The flowed page content includes any content that is not absolutely positioned by the template, including section begin/end content and the tabular content of the report. An element defining the content region can be placed inside of a pageTemplateFirst conditional directive to provide a different content region on the first page vs continuation pages of a section. If the content region is not defined, then the flowed content will be flowed into a box with 0.5in margins on the entire page.

Example:

<div style="position:absolute;left:0.5in;top:4in;height:3in;width:7.5in;flow-from:content;"></div>

 

Supported HTML elements

 

div

The div element only supports the style attribute with all supported CSS properties described below allowed. The default value for the display CSS property is block.

 

img (used to add barcode or QR Code) 

The img element only supports the src attribute and the style attribute (the width and height HTML attributes are not supported). The CSS property display must be specified and have the value block. The CSS properties width and height must both be specified.

The src attribute only supports the Finale-specific barcode URI scheme. This URI scheme creates a Code 128, EAN-13, or UPC-A barcode that fills the image. The structure of this scheme is: barcode:[quiet=<quietLength>][format=<formatEnum>],<data>. If both the quiet and format options are specified then they must be separated by the & character.

The format value is optional and defaults to CODE128. For CODE128, the supplied data values must contain valid Code 128 characters. 

The quiet value is optional and only supported for CODE128. If specified it must be a CSS length which is used as the quiet area drawn as white within the area of the img element. The quiet value may be specified as zero, in which case left most and right most bars of the bar code will be drawn at the edge of the img element. If the quiet value is not specified, then the minimum quiet area per the Code 128 specification will be drawn as white within the area of the image.

 

An example of the proper format is shown below:

 

<div style="position:absolute;top:0.22in;left:0.33in;width:1.965in;height:0.44in">
<img style="display:block;width:1.965in;height:0.44in;"
src="barcode:quiet=0,{{DATA}}">
</div>

 

Other popular valid format values are UPC and EAN. For UPC and EAN the supplied data must be a 12 or 13 digit number that is a valid code (ie. the check digit must be correct). If a 12 digit UPC code is formatted as EAN, then it is automatically prepended with a zero to become the equivalent EAN code. If a 13 digit EAN code that begins with a zero is formatted as UPC, the leading zero is automatically stripped to become the equivalent UPC code.

An example of the proper UPC format is

<div style="position:absolute;top:0.25in;left:0.45in;width:1.5in;height:0.44in">
<img style="display:block;width:1.5in;height:0.44in;"
src="barcode:format=UPC,{{DATA}}">
</div>

Another supported format are QR Codes.  To added a QR code image, an example of the proper format is shown below:

<div style="position:absolute;top:0.005in;left:0.005in;width:1in;height:1.0in">
<img style="display:block;width:1.0in;height:1.0in;"
src="qrcode:format=M,{{DATA}}">
</div>

 

hr

Inserts a horizontal rule. No styling supported.

 

br

Insert a line break. No styling supported.

 

Supported CSS properties

Page templates support an incomplete subset of the CSS specification to control the formatting of the page. Only the specific properties listed here are supported, and only with caveats and limitations described. For example, although the border-width and border-color properties are supported, the related border shorthand property is not supported. All properties are specified on the specific element they apply to. There is no way to specify a stylesheet with selectors, and the inherit value is not implemented for any property.

The initial positioning context for absolutely position items is the upper left hand corner of the page. The software uses the border-box box sizing model.

 

display

The only supported value is block.

 

position

The only supported value is absolute.

 

left

Both left and top must be specified for absolutely positioned elements. Must be a supported CSS distance as described below.

 

top

Both left and top must be specified for absolutely positioned elements. Must be a supported CSS distance as described below.

 

width

Must be a supported CSS distance as described below.

 

height

Defaults to zero if not specified (ie. box used for background and borders does not resize to fit content). Must be a supported CSS distance as described below.

 

background-color

Only applied to absolutely positioned elements. Must be a supported CSS color as described below.

 

border-width

Only applied to absolutely positioned elements. One to four values as described in the spec. Must be a supported CSS distance as described below.

 

border-color

Only applied to absolutely positioned elements. One to four values as described in the spec. Must be a supported CSS color as described below.

 

padding

Only applied to absolutely positioned elements. One to four values as described in the spec. Must be a supported CSS distance as described below.

 

color

Must be a supported CSS color as described below.

 

font-family

Valid values are serif and sans-serif. Default is sans-serif.

 

font-size

Must be supported CSS distance as described below.

 

font-weight

Valid values are normal, bold, and the numeric values between 100 and 900 as described in the spec. Default is normal.

 

font-style

Valid values are normal, oblique, and italic. Default is normal.

 

text-align

Valid values are left, center, and right. Default is left.

 

line-height

Valid values are normal or any number. As described in the spec, when specified as a number lines are spaced by the number multiple by the font size. The default is normal which spaces lines at a default distance specified by the font.

 

flow-from

Based on the draft CSS Regions module. Only valid on absolutely positioned elements. Content within an element that has flow-from specified is not rendered. See the description of page templates regions above for use of this CSS property.

 

Supported CSS data types

 

Color type

A subset of the color specification is supported. Colors may be the value of "transparent" or of the form "#RGB" or of the form "#RRGGBB". Named colors and the functional notation from the specification are not supported.

 

Distance type

A subset of the distance units specification is supported. Distances may be the value "0" or a number followed by in, cm, mm, pt, px, pt or pc for the absolute measurement. Relative measurements are not supported.