CS

Print templates

Home / Documentation / Administrator guide /

Print templates

CS

1. General information

  • Printing to a print template is triggered by buttons placed in an edit form or on a view page.
  • Supported print template formats include files “xls”, “xlsx”, “doc”, “docx”, “html”, “txt”, “csv”, and “pdf”.
  • NET Genium also processes templates “htm”, “xlsm”, “ods”, “docm” and “odt”.
  • Microsoft Excel, Microsoft Word and “html” print templates support automatic conversion to “pdf” with the “Save as PDF” option of the button.
  • If the template file is missing, “txt”, “csv” and “html” templates print an empty document; for other formats printing ends with an error.

2. Location and management of print templates

  • Print templates must be stored in the directory “NETGenium\Templates”.
  • Files can be copied into this directory directly on the server or via the NET Genium settings dialog on the Print templates tab.
  • From this directory, print templates can be selected directly in the properties of the button that triggers printing.

3. Identifiers and variables in print templates

  • Identifiers of database controls and script variables are used in print templates. In “txt”, “csv” and “html” templates, server functions and system variables are evaluated as well; in Microsoft Excel and Microsoft Word templates they are not. Only functions and variables written in the template itself are evaluated – values substituted from records and variables are not evaluated as functions or variables, even if they contain such text. A function written in the template receives such a value as its argument; the result of the function is not evaluated as a function or a variable either.
  • Script variables can be populated before printing using a script.
  • At the position in the template where values are to be inserted, identifiers of database controls or variable names are used.
  • NET Genium opens the print template, searches for all identifier occurrences, and replaces them with the corresponding values.
  • A detailed description of variables used in print templates and control formatting options is given in the separate guide Variables.

3.1. Printing from an edit form

  • Inserting values of database controls into a print template from the currently opened record in an edit form uses identifiers in the shortened format “#ng_control#”.
  • A print button always saves the record before printing; it does not save it only in an edit form without save buttons or in a read-only form.

3.2. Printing from view pages and tables

  • All records matching the conditions of the view table and the search, filters and time period entered by the user are printed, in the user's sort order – not only the currently displayed page. Marked records are not taken into account when printing. The number of printed records is limited only by the “Load only first” option of the database query.
  • Printing records from a view table requires the use of identifiers in full form, in the following possible formats:

3.2.1. First format (recommended)

  • “#DG10#.#ng_control#”, “#DG11#.#ng_control#”, etc.
  • Intended and most suitable for datagrids, using notation based on the datagrid ID (JavaScript element name).
  • This approach is more stable when additional datagrids are added to a form and their order changes, which would cause identifier changes when using the second format.
  • Identifier lookup

3.2.2. Second format

  • “#datagrid1#.#ng_control#”, “#datagrid2#.#ng_control#”, etc.
  • This full identifier format, including the visual control type name and its sequence number, reflects scenarios where multiple view tables with the same data source but different filtering conditions are placed in an edit form or on a view page.
  • Additional examples: ** “#calendar1#.#ng_control#”, “#calendar2#.#ng_control#”, etc. ** “#timetable1#.#ng_control#”, “#timetable2#.#ng_control#”, etc. ** “#planner1#.#ng_control#”, “#planner2#.#ng_control#”, etc.

3.2.3. Third format

  • “#ng_form#.#ng_control#”.
  • Microsoft Word templates do not recognize this format – they use only the first and second formats.

3.3. Print behavior when using full identifiers

  • NET Genium detects the use of full identifiers and automatically inserts values of individual records one below another.
  • If identifiers are placed next to each other on a single line, the print output is a table where each record occupies one row in the print template.
  • If identifiers are placed next to each other on two lines, the print output is a table where each record consists of two lines in the print template.
  • The repeated section differs by template format:
    • “html” – only the table row (“<tr>”) containing the identifiers is repeated; identifiers outside a table row are not repeated,
    • “txt” and “csv” – a section of consecutive lines with identifiers is repeated,
    • Microsoft Excel – a section of consecutive sheet rows is repeated,
    • Microsoft Word – records are not repeated one below another. When printing from an edit form, the values of all records of the view table are inserted into one field separated by commas; when printing from a view page, each record is printed to a separate document and the documents are downloaded as a ZIP archive.

3.4. Specific printing scenarios

  • Printing from a view page that contains only a single view table does not require full identifiers; simplified identifiers are sufficient.
  • Printing from a view page to “pdf” and Microsoft Word prints each record of the first view table to a separate file; the files are downloaded as a ZIP archive.
  • If a view page contains two or more view tables over the same edit form and a Microsoft Excel template does not use identifiers of the first or second format (“#DG...#.”, “#datagrid...#.”), each table is printed to a separate copy of the sheet.
  • Printing a statistical view table with aggregated columns uses column identifiers “c0”, “c1”, “c2”, etc., according to their order in the table header, numbered from zero.

3.5. Formatting values in print templates

  • Print templates created in Microsoft Word must have identifiers placed in fields of type “MergeField”.
  • Values in print templates can be formatted using the syntax “#identifier@format#”.

4. Images in print templates in the “html” format

  • Print templates in the “html” format can contain images (typically a logo) inserted using the “<img>” tag, in one of the following three ways:
    • Image embedded directly in the template as a base64-encoded “data URI”, e.g. <img src="data:image/png;base64,..."> — the template is self-contained and the image is printed both when printing to “html” and when converting to “pdf”. This is the recommended approach.
    • Reference to a NET Genium attachment — the image is uploaded to NET Genium as an attachment, and the relative attachment address in the form <img src="Download.aspx?..."> (without the server address) is inserted into the template. When converting to “pdf”, NET Genium embeds the image into the document automatically; when printing to “html”, the image is loaded by the browser of the logged-in user.
    • Absolute URL of a publicly available image, e.g. <img src="https://www.example.com/logo.png">.
  • Relative references to files in the “NETGenium\Templates” directory, e.g. <img src="Templates/logo.png">, are not resolved when converting to “pdf”, and in NET Genium Online they do not work even when printing to “html”, because the “Templates” directory is not accessible via the browser in the cloud. Therefore, use only the three approaches listed above.

5. Post-print events

  • After successful generation of a print output, the external function “NETGenium.OnAfterPrint” is automatically executed, allowing modification of the output file name as well as its content or format.
  • If each record is printed to a separate file, the function is called for each record separately. An error in the function interrupts printing.

5.1. Rights and content of the printed document

  • A print template prints every identifier it contains – including the value of a control the printing user has no right to, or whose value the user would not see because the “Show value” setting is “Only to the owner or co-owner of the record”. The content of the printed document is therefore determined by the author of the template, not by the rights of the printing user.
  • Value formatting (conversion to the displayed text, number and date format) is applied only to controls the user has rights to; other identifiers are filled in with the value stored in the database.

5.2. Encoding of text templates

  • “txt” and “csv” templates saved in UTF-8 with BOM are also printed in UTF-8 with BOM. Templates without BOM are read and printed in the character set of the server (typically Windows-1250).

6. Troubleshooting

6.1. Multiple blank pages printed from “xls” and “xlsx” templates

  • If printing with an “xls” or “xlsx” print template produces multiple blank pages, it means the template content does not fit the page width and the overflowing columns are printed on separate pages.
  • Solution: in the print template, set the print scale to 100% and reduce the page margins so that the print fits the width of a single page. If needed, also reduce the font size and column widths.

7. Relation to other documentation

  • A detailed description of variables used in print templates and control formatting options is given in the separate guide Variables.
  • A detailed description of programming print templates in “pdf” format is provided in the separate guide Programming of print templates in PDF format.