Customizing Template

A template is a zip file of code snippets needed to generate the output files. Template is fully customizable, you can customize the default template shipped with the product to suit your own needs in your web applications.

Customizing templates requires necessary knowledge in the related web technologies, HTML and JavaScript, and understanding on how template works. Please read the follows carefully before customizing the template.

The template engine is Node.js and the scripting language is JavaScript, to customize template you need to have basic knowledge of JavaScript.


Zipped Template, Unzipped Template and Template Cache

To generate output files, the code generator first unzips the template to the subfolder \<product name>\Templates\<template name> under your Documents folder, pre-processes the scripts in the template into template cache, then use the template cache to generate output files. If the unzipped template already exists, the code generator will skip the unzip process and reuse the template cache so the time required for generation is minimized.

If you want to customize a template, normally you customize the files in the zipped template, but you'll need to zip it back after customization, for example, by dragging the customized files back to the zipped template. The unzipped template under the Documents folder provides an optional way to customize the template without re-zipping the template. Either way, you should zip it back after all the customizations are done.

Note The Documents folder is your personal folder in which you can store your personal files. For example, in Windows 10, the actual location of the Documents folder is C:\Documents and Settings\<user name>\My Documents by default, where C is the drive in which Windows is installed, and <user name> is the currently logged-on user. In Windows Vista (or newer), the folder is C:\Users\<user Name>\Documents.

If you prefer to work with the unzipped template but you have not generated any files yet, do once first. Then you can modify the unzipped files under the subfolder named "Script". For example, if the template archive is named as "", it will be unzipped to the folder <document folder>\<product name>\Templates\\, you can modify files under the subfolder "Script" under it.

Note The customized files will not be zipped back to the template archive automatically. It you want to transfer or share your template, you need to zip the template files back to a template archive yourself. When you zip the template files, make sure you zip the files and subfolders in the unzipped folder, not the unzipped folder itself. Otherwise there will be one level different. Using above example, you should add the files and subfolders under <document folder>\<product name>\Templates\\ to the template archive, NOT the whole folder.

When changes in the zipped template is detected, the code generator will ask you to confirm overwriting the old unzipped version, you should answer carefully, especially if you've implemented some customizations previously. Always back up your customized template first!


Control File

The core of the template file is a control file named control.xml. It is an XML file containing all the necessary instructions for the generation process. During generation the code generator will parse the control.xml and follows the instructions to generate the output files one by one. If you want to add an output file, you need to add a <control> tag in the control file. If the file is to be included in other file(s), you may need to add <session> tags in control.xml also. See Control File for details.


Language Files

All the phrases in the template are separated into a single XML language file for easy translation to other languages and sharing. If you want to translate a template, this should be the only file you need to translate.

Language files are placed in the subfolder "languages" under the installed folder. The files are used for all templates.

See Multi-Language Project for more information on making a language file.

You can edit or even add your own phrases. Just open the language file with any text or XML editor, edit/add your <phrase> nodes. Make sure you provide an unique id to each phrase. The id must be alphanumerical only.

The phrases are not limited to text, you can also use HTML, e.g.

<phrase id="FieldRequiredIndicator" value="<span class="ewRequired"> *</span>"/> (see Note 1 below)

If you want to use an image instead of text for a phrase, you can use the "imageurl", "imagewidth" and "imageheight" attributes, e.g.

<phrase id="UnmatchedValue" value="Value does not exist" imageurl="{_images}/warn.gif" imagewidth="16" imageheight="15"/>

where {_images} is the image folder defined in control.xml, by default it is "rptimages", you should place your own images in the generated image subfolder. Alternatively, you can put your images in the "images" subfolder of the template.

Read Tools on how to select language file(s) for a multi-language project before generation.


  1. Language file is an XML file, when you edit the file, make sure that you keep it well-formed. If you use HTML tags or special characters in the attributes of the XML tags, you need to use entity references. For example, to insert the > symbol, you need to use &lt;. Make sure your characters are supported by the encoding of the XML file specified in the processing instruction node (the first line). You can load the file in your browser to check if the file is well-formed, if it is, the browsers should be able to load and display it without any errors.
  2. Only the English language file is provided by our products, you'll need to prepare the language files for other languages yourself. You may check our website and see if there are any user submitted language files. If you want to share your language files with others (without any conditions), you can submit your language file to us too.


Locale Files

Locale files containing locale settings for number, currency, date and time formatting. Each locale file has a language ID, which must match the corresponding language file.

Locale files are placed in the subfolder "locales" under the installed folder and they are used by all templates.

Many locale files are already provided in the "locales" folder, you can edit them or even add your own locale files. To edit a locale file, just open the locale file with any text editor supporting utf-8 file and then edit your locale settings. To add a locale file, just copy any existing locale file, and then edit it.

Note Make sure you name your locale file with an unique "id" (converted to lower case) which matches the language id of the corresponding language file.

A locale file is in JSON format, when you edit it, make sure you do not break the JSON format. Always save the file in utf-8 format without BOM.

The "time_zone" setting in the locale files are empty by default, which means the time zone will not be changed according to language, it will use the default time zone "GMT". If you want to set the time zone for a locale file, you need to edit the locale file before generating scripts. Read Tools on how to edit locale file.


File Encoding

The template files and output files are in ASCII encoding by default. Since the phrases are separated into XML language files in utf-8 encoding, ASCII encoding will suit most cases as the scripts contain code only. When you customize a template, it is recommended you use the language file also. If you have to put unicode characters directly in the template files, you must always use utf-8 and save the file in utf-8 encoding with the byte order mark (EF BB BF), and enable the Advanced Setting UTF-8 output Files (see Tools) to make the code generator output files in utf-8 encoding.


General Layout

To change the general layout, just modify the file "rpt-template.asp" in the template. This file will be generated as header and footer.


Images and Subfolders

If you want to add or change images, you can add to the "images" subfolder. The "images" folder will be copied to the destination folder by default. If you add new subfolders, you also need to add a <control> tag in the control file.


Template Tags and Object Properties

The code generator processes the Template Tags, assembles the output files using the code snippets from template files and generate code according to Object Properties. Template object properties are project settings either inputted from the user interface or restored from a project file. Template Tags are in the format of HTML comment, when you customize template you should use an editor that will not unexpectedly alter or remove the HTML comments, otherwise incorrect result may occur.


User Code File

Advanced users can customize the dynamically generated code by overriding an existing template tag using User Code. To override an existing template tag, you need to add your own function in the User Code File. (See Using User Code.) By default, the User Code File is named as "usercode.js" and can be found under the "src" subfolder of the installed directory.

You can use your own custom functions in the template. To use custom functions, write and put them in the User Code File. Then just use template tag to call them in the template. (See Using User Code)



Integrating third-party tools can be done by extensions. An extension is modification of template to make the template supports additional feature(s) implemented in the extension. An extension has the same structure as template and you can modify them in exactly the same way as modifying the main template. Extensions are processed after the main template, it may add or change some files in the template. Extension supports User Code also.

Extensions files (in zipped format) must be placed under the subfolder "extensions" of the installation folder. Each extension must have a XML description file so the product can load the available extensions in the user interface for selection. You can open an XML file in the "extensions" subfolder to see the content, which is self-explanatory.

Read Tools on how to select extensions for a project before generation.

Note An extension is NOT a template, do NOT select an extension as a template for generation.

Also see Third-party Tools for more information on the third-party tools.


Custom View Tags

Custom View Tags is same as extensions except that it is used to display a field in the List and View pages with your own code. A Custom View Tag has the same structure as extension and you can modify them in exactly the same way.

Custom View Tag files (in zipped format) must be placed under the subfolder "customviewtags" of the installation folder. Each Custom View Tag must have a XML description file so the product can load it in the Field Setup page for selection.. You can open an XML file in the "extensions" subfolder to see the content, which is self-explanatory. Unzip the extension and see how it is implemented.

Read Field Setup on how to select Custom View Tag for a field.

Note that all Custom View Tags are provided as examples how to customize and extend the template only, the third party tools used in them are not developed by the author of ASP Report Maker and are not part of ASP Report Maker, NO TECHNICAL SUPPORT WILL BE PROVIDED.


Also See:

Control File
Template Tags
Object Properties
Using User Code
Third-party Tools


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