Custom Templates

By default reports are exported in tabular format. Custom Template enables you to re-arrange data in the report in your own way for better printing with browsers or exporting to other format.

Notes

  1. Custom Template currently supports Simple reports and Detail and Summary reports only. (Crosstab reports are NOT supported.)
  2. Do not confuse Custom Template (which is a table level setting within a project) with customizing the whole template zip file. If you want to customize the general layout of the generated site or customize something for all tables and all projects, you should customize the template zip file, see Customizing Template.

 

How it Works

If a Custom Template is provided, ASP Report Maker splits the original code in many small client side templates. A client side template is HTML code enclosed by <script type="text/html"> and </script>. Since browsers do not know how to execute "text/html" scripts, they simply ignore it. So it is possible to re-assemble HTML from the small client side templates by JavaScript based on your provided Custom Template. In other words, it is simply re-arrangement of existing HTML parts in browser.

During script generation, ASP Report Maker converts your Custom Template to a client side template and outputs JavaScript to render the template. The client side template is rendered by JsRender (see Third-Party Tools) which is a third-party JavaScript template engine optimized for high-performance pure string-based rendering. The generated scripts only use its "template composition" feature to render HTML from other external templates, your Custom Template can however make use of its JsRender API to do a lot of other things. (Note that JsRender is still in beta, if you use its features directly, be aware that there may be some breaking changes in the future.)

 

Custom Template Tags

To let you create your Custom Template easily, ASP Report Maker supports the following Custom Template Tags. Since JsRender supports tags enclosed by {{ and }} (double curly brackets, see below), in order to let you use them in your Custom Template, ASP Report Maker Custom Template Tags uses {{{ and }}} (triple curly brackets) to differentiate. Note that Custom Template Tags will be converted to JsRender tags during script generation, they can only be used in ASP Report Maker user interface, they cannot be used elsewhere such as template (zip file) or generated scripts.

In the following table, field represents the field variable name. In general, if the field name is alphanumeric, field variable name is same as the field name. Otherwise, spaces are replaced by underscores, and other non alphanumeric characters are replaced by their hexadecimal string representation of their unicode value. If the variable is a reserved word or starts with a digit, it will be prepended with an underscore. If you are not sure, drag a field from the database pane to the editor instead of typing {{{field}}}.

{{{field}}} Field value
{{{caption field}}} Field caption
{{{value field}}} Field value (same as {{{field}}})
{{{sum|avg|min|max|cnt field}}} Field group level summary value (Sum/Average/Minimum/Maximum/Count)
{{{count}}} Number of detail records in the group
{{{row_cnt}}} The row index (1-based) of the detail record in the group
{{{pagesum|pageavg|pagemin|pagemax|pagecnt field}}} Field page summary value (Sum/Average/Minimum/Maximum/Count)
{{{grandsum|grandavg|grandmin|grandmax|grandcnt field}}} Field grand summary value (Sum/Average/Minimum/Maximum/Count)
Note In simple report, there is no grouping fields, use this tag instead of above tags for summary values.
{{{current_filters}}}

Current filters of the report

Note The advanced setting "Show current filters" or "Show drill down filters" must be enabled for this tag to work, see Advanced Settings.

 

JsRender Tags

The FIRST ROW of the data for the report will also be passed to the Custom Template, you can use JsRender tags enclosed by {{ and }} (double curly brackets) to show them in your Custom Template. Remember that ASP Report Maker Custom Template Tags uses {{{ and }}} (triple curly brackets) while JsRender tags use double curly brackets. Custom Template Tags will be converted to JsRender tags during script generation, while JsRender tags will be kept intact. In the following table, field represents the field variable name similar to Custom Template Tags.

{{:field}} Field value
{{>field}} HTML-encoded field value

Notes

  1. The first row data is unformatted raw data from the database. If you want to format the data, you can use Client Script of the page (see Server Events and Client Scripts) to subscribe the "rendertemplate" event and format the data.
  2. See JsRender API for complete information of JsRender tags.

 

How to Use

To enter your Custom Template for a table, follow the following steps:

  1. Select the table in the database pane,
  2. Select the Code tab (which contains Server Events, Client Scripts and Templates),
  3. Scroll down the treeview or collapse the Server Events and Client Scripts node, select a template node under Custom Templates,

    Template Name Description
    CustomTemplateHeader

    This is the custom template header. You can put report header (such as company name and/or logo) in this section of the custom template.

    CustomTemplateGroupHeader<n>

    This is the group header for the nth group (where n = 1-6). You can put report group level information (such as group caption and value) in this section of the custom template. If you have two grouping fields in your reports, enter the custom templates for the two groups only. This section is not used in simple reports.

    CustomTemplateBody

    This is the custom template body. You can put report details in this section of the custom template.

    CustomTemplateGroupFooter<n>

    This is the group footer for the nth group (where n = 1-6). This section is not used in simple reports.

    CustomTemplateFooter

    This is the custom template footer.

    Note Custom Template let you customize the layout of the data originally placed in the main HTML table of the page, it cannot customize other parts of the page.
    For example, if the report has 2 grouping levels, the custom templates are:

  4. Enter your Custom Template in the editor.

    Note You can enter the first character of a field name and then press Ctrl + Space to open the completion list of the editor and select a {{{field}}} tag.

Then just generate and run your scripts in your browser as usual.

 

Important Notes
  1. Keep your Custom Template as simple as possible. For printer friendly version, the outputted HTML is rendered by the browser itself, browser can understand complex HTML. However, for other export format, the outputted HTML is to be rendered by other applications such as Word, Excel, DOMPDF and email client, they may not be able to render your complex HTML properly, so always keep your template simple.
  2. Remember that Custom Template is rearrangement of existing some HTML fragments in the page, all other code is still the same, the fields in the Custom Template should be the same as the original script. The available fields are same as the original script, if you try to include other fields in the table or from other table by Custom Template, it will NOT work without writing your own code.
  3. Custom Template is HTML, if you want to embed ASP code, you need to use <% and %> to enclose your code, if you want to use JavaScript, you need to use <script type="text/javascript"> and </script>.
  4. You can use CurrentPage to get the current page object, and use CurrentTable to get the current table object.
  5. Avoid using JavaScript in the template. If you need to use JavaScript, try to put your JavaScripts in Client Scripts and Startup Scripts of the page (see Server Events and Client Scripts). If you have to use JavaScript in the template, DO NOT using document.write() because the script will be extracted from the template and be executed at the end of the template, you can however use a DIV with unique id and write to its innerHTML.
  6. CustomTemplateBody is the template for a record. Your Custom Template needs NOT to be a HTML table, but if it is, then CustomTemplateHeader and CustomTemplateFooter must at least contains <table> and </table> respectively, and you need to provide the <tr> and <td> tags in these templates.
  7. If you use images in your Custom Template, you must put your images under the project's File folder (see ASP Settings > General Options -> File Folder).
  8. Before the Custom Template is applied, the jQuery event "rendertemplate" will be fired, you can use Client Script of the page (see Server Events and Client Scripts) to subscribe this event and pass additional data to the Custom Template.
  9. If you want to use Custom Template for export only, disable the advanced setting Use Custom Template for viewing, see Advanced Settings.

 

Also See:

Tutorial - Custom Template

 

 ©2006-2017 e.World Technology Ltd. All rights reserved.