Contents EJS-code

EJS (Express.js) is a web application framework for Node.js. In BILLmanager EJS is implemented with the /usr/local/mgr5/etc/scripts/template_ejs.js script. For correct operation, the incoming XML-file is converted to a JSON file.

The EJS language describes document and message templates in BILLmanager. To add or edit templates, navigate to Settings → Document templates.

Information in an EJS-template can be represented with the following elements:

formatting block (sections);
tables;
lists;
links to images

Formatting sections

The <div> </div> tags define the formatting sections in a template code. The content inside these tags must meet general formatting rules. Normally, the formatting is set with style classes. Style classes can be defined in a template code or in an external style table. A base print template is used as an external style table in BILLmanager. See more Document EJS-templates.

The style class for the formatting section is set with the class or id attribute. The style class name is specified as an attribute purpose.

Style class

<div class="myStyle"> // The "myStyle" style class will be applied to the section
	Any content of the section. 
</div>


<div id="anotherStyle"> // The "anotherStyle" style class will be applied to the section. 
	Any content of the section. 
</div>

Example

The following example shows how to describe a document name in the invoice template:

<!-- Header -->
    <div class="header">
		Invoice <%= invoice.number %> for the provided services <% rusdate(invoice.cdate) %>
	</div>
<!-- Header -->

In the style table (the base template), the header class is described as follows:

#bill-ru .header { font-size:14pt; font-weight:bold; padding-bottom:30px; text-align:center; }

The rules from the "header" class will be applied to the text in the formatting section: font size - 14 pixels, a bold text, padding-bottom - 30 pixels, and a center-aligned text.

Tables

The <table> </table> tags define a table. <tr> </tr> and <td> </td> define a standard cell and row in the table.

<tr> </tr> define a row of cells in the table inside the tags <table> </table>;
<td> </td> tags define a row of cells in the table inside the tags <tr> </tr>. <th> </th> can be used instead of <td> </td>. A text inside the cell will be center-alligned and have bold style.

Table description syntax

<table>
  <tr>
    <th>Header1</th>
    <th>Header2</th>
    <th>Header3</th>
  </tr>
  <tr>
    <td>Value1</td>
    <td>Value2</td>
    <td>Value3</td>
  </tr>
</table>

EJS-templates support standard HTML-tags and table attributes. The style class can also be applied to tables.

Example

The service price is described in the invoice with the following code:

<!-- Items -->
<table class="items">
   	<!-- Head -->
   	<tr>
   		<th style="text-align: left;">Provided services</th>
   		<th style="width: 20%">Amount</th>
   	</tr>
   	<!-- Head -->
   	<!-- Items -->
   	<% for (var i = 0; i < invoice.items.item.length; i++) { %>
   		<tr class="item">
   			<% if (((invoice.items.item[i].name).indexOf("Additional", 0)) != -1) { %>
   				<td style="padding-left: 20px;">
   			<% } else { %>
   				<td>
   			<% } %>
   			<%= invoice.items.item[i].name %>
   			</td>
   			<td class="amount"><%= invoice.items.item[i].amount %></td>
   		</tr>
   	<% } %>
   	<!-- Items -->
</table>
<!-- Items -->

Lists

Two types of lists are supported: ordered and unordered. The <ul> </ul> tags represent an unordered list of items, each element included into the tags <li> </li>. The marker type can be specified using the type attribute value — disc, circle or square:

<ul type="disc | circle | square">
	<li> List element 1 </li>
	<li> List element  2 </li>
	<li> List element  3 </li>
</ul>

The <ol> </ol> tags define an ordered list. Use the <li> tag to define list items. The reversed attribute allows you to write a descending list of numbered items. The start attribute specifies the start value for numbering the individual list items. The numbering type of the list can be specified using the value of the type attribute — 1, A, a, I, or i.

<ol type="1 | A | a | I | i" reversed start="10">
	<li> List element 1 </li>
	<li> List element 2 </li>
	<li> List element 3 </li>
</ol>

Links to images

Use the <img src=image_URL/> tag to add images into your EJS-template. The width and height attributes specify the width and height of an image in pixels.

<img src="imageURL/image.png" width="100" height="75"/> //the width attribute sets the  the height of an image, the height attribute sets the  the height of an image,

Example

The message template can contain a user avatar. Add it with the following code:

<img src="https://<URL_BILLmanager>/manimg/userdata/avatar_files/<%= user.avatar_file %>"/>

Security

Prohibit execution of XHR and Fetch requests

For security reasons, XHR and Fetch queries are prohibited by default:

in document templates;
in email notification templates.

When rendering a template under a client or employee account, the platform applies CSP (Content Security Policy) for the browser. The policy is specified in BILLmanager in the response headers from the server or in the HTTP headers of the page. The Content-Security-Policy parameter is set to content-src 'none'.

If you need to change the default behavior, you can change the policy or disable it. If you change the behavior, the system may be vulnerable to CSRF (Cross-Site Request Forgery) attacks.

To disable the policy specification, add the Option DisableTemplateCSP to the /usr/local/mgr5/etc/billmgr.conf configuration file. For more information, see the Configuration file article.

To specify a different policy value, specify the value of the TemplateCSP parameter in the configuration file. For example, TemplateCSP some_value. For more information, see the MDN (Mozilla Developer Network) documentation: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src

Isolating the environment

Starting with version 6.124, templates are generated in an isolated environment to protect against vulnerabilities. When installing or upgrading BILLmanager, the billmanager-plugin-template-processor software package is installed. This package:

Sets up the containerization environment:
- in Ubuntu — Docker;
- in AlmaLinux — Podman.
Downloads an image with scripts to safely generate templates.

You can disable the use of the isolated environment. For example, if templates are not formed correctly. To do this:

Add the Option DisableTemplateProcessor to the /usr/local/mgr5/etc/billmgr.conf configuration file. For more information, see the Configuration file article.

Restart the platform:

/usr/local/mgr5/sbin/mgrctl -m billmgr -R

Useful tips