Retail:Developers Guide/New Javascript template engine for receipt printer and customer displays documents
New Javascript template engine for receipt printer and customer displays documents
 | The new template engine and the features presented throughout this document are supported starting from 3.0PR21Q2. |
Introduction
Print templates are xml files that support having pieces of javascript code. This is posible because the template function is used to evaluate and generate the result that eventually is sent for printing. This function is part of lodash javascript library.
Including javascript code into a template
Include javascript code into the XML templates is easy, just add it into this tags <%= javascript code here %>
<text align ="right" length="14"> <%= OB.App.PrintUtils.printAmount(payment.value) %> </text>
Looping an array of data
One of the most common task editing a template is iterate through an array of data. It can be done including a while/for/forEach javascript statement and then the line (in xml notation) that we would like to repeat.
Let's see an example.
<%
ticket.lines.forEach(line => {
%>
<line>
<text align ="left" length="21">
<%= line.product._identifier %>
</text>
<text align ="center" length="5">
<%= OB.App.PrintUtils.printQty(line.qty) %>
</text>
<text align ="left" length="8">
<%= OB.App.PrintUtils.printTicketLinePrice(line) %>
</text>
<text align ="left" length="8">
<%= OB.App.PrintUtils.printTicketLineAmount(line) %>
</text>
</line>
<%
}
%>
As you can see in this example, as the same manner than in javascript code, is possible to access to variables defined in other "javascript parts" of the document.
Data received by each template
Each template receives different data (plain javascript object) which include the information to be printed.
Bellow are listed some of the standard templates and which javascript object is received by each one:
- printreceipt.xml - ticket (Ticket Model)
- printreturn.xml - ticket (Ticket Model)
- printinvoice.xml - ticket (Ticket Model)
- printreturninvoice.xml - ticket (Ticket Model)
- printline.xml - ticketLine (Ticket Model)
- welcome.xml - No data is received
This data, comes from the models defined within the application state. See here to know more about state models.
Note that there exists some templates which have not been migrated (they are still supported through a backwards compatibility layer) and they still receive data from legacy models:
- printcashup.xml - JavascriptObject
- printcashmgmt.xml - Backbone collection
Special functions used in templates
Because the process of the template is done calling to the lodash template function, inside it (javascript code of the template) is possible to use all the functions defined in OB scope.
In the list bellow are the most common utility functions from the org.openbravo.mobile.core module that can be used in a template:
- OB.UTIL.encodeXMLComponent: Removes special XML character avoiding the construction of an invalid XML file.
- OB.I18N.getLabel: Give access (using the searchkey) to the messages defined in the application dictionary.
- OB.I18N.formatDate: Formats the passed Date into a string representing the date with the formats defined for the store.
- OB.I18N.formatHour: Formats the passed Date into a string representing the hour with the formats defined for the store.
Besides, the org.openbravo.retail.posterminal module provides some utilities to deal with ticket information:
- OB.App.PrintUtils.printAmount: formats a numeric amount into a string according to configuration defined for the store.
- OB.App.PrintUtils.printQty: formats a numeric quantity into a string according to configuration defined for the store.
- OB.App.PrintUtils.printTicketLineAmount: provides the amount of a ticket line tacking into account if the ticket amounts include taxes or not.
- OB.App.PrintUtils.printTicketLinePrice: provides the price of a ticket line tacking into account if the ticket prices include taxes or not.
- OB.App.PrintUtils.getChangeLabelFromTicket: gets the "change label" according to the payment status of the provided ticket.
Working with Ticket model in a template
properties of order model
Here are the main properties of the ticket model and their equivalence with the properties of the backbone Order model:
| TICKET MODEL PROPERTY | TYPE | ORDER MODEL EQUIVALENCE |
| id | string | id |
| client | string | client |
| organization | string | organization |
| orderType | numeric (0, 1, 2, 3) | orderType |
| priceList | string | priceList |
| currency | string | currency |
| warehouse | string | warehouse |
| salesRepresentative | string | salesRepresentative |
| posTerminal | string | posTerminal |
| orderDate | string | orderDate |
| documentNo | string | documentNo |
| businessPartner | object | bp |
| lines | array | lines |
| payments | array | payments |
| payment | numeric | payment |
| change | numeric | change |
| grossAmount | numeric | gross |
| netAmount | numeric | net |
| taxes | object | taxes |
main properties of ticket lines
Regarding ticket lines (ticket.lines property), the main properties are:
| TICKET LINE PROPERTY | TYPE | ORDER LINE MODEL EQUIVALENCE |
| id | string | id |
| product | object | product |
| uOM | string | uOM |
| qty | numeric | qty |
| baseGrossUnitAmount | numeric | gross |
| baseNetUnitAmount | numeric | net |
| netUnitPrice | numeric | unitPrice |
| netListPrice | numeric | listPrice |
| baseGrossUnitPrice | numeric | price (price includes tax) |
| baseNetUnitPrice | numeric | pricenet, price (price not includes tax) |
| taxRate | numeric | lineRate |
Print the content of a property
In this example, the value of property change is accessed and printed
<text align="right" length="20"> <%= OB.App.PrintUtils.printAmount(ticket.change) %> </text>
We can also access to "child" properties when dealing with objects
<text align="right" length="20"> <%= ticket.businessPartner.name %> </text>
Iterate through ticket lines
And as explained here we can also iterate array properties.
Adding QR codes to the template
A new tag has been created to indicate when a QR code must be printed. Here is an example of printing the document no as a QR Code.
<qr><%= OB.UTIL.encodeXMLComponent(ticket.documentNo)) %></qr>
Executing a report receipt
Web POS is also capable to print receipt reports using the Jasper Reports engine instead of the Receipt and Display document schema and even you can decide in the receipt template what engine to use depending for example on any order property.
In the case you want to print a receipt report the evaluated template must start with jrxml: followed by the definition of the receipt report that is a JSON object with the following schema:
{ "printer": <printer_number>, "report": "<main_report.jrxml>", "subreports": [ "subreport_1.jrxml", "subreport_2.jrxml" ] }
The fields to define in the JSON object are:
- printer: The number of the printer configured in the Hardware Manager used to print the report receipt.
- report: The report definition to send to the Hardware Manager.
- subreports: List of the subreports used by the main report.
This report receipt definition has to be create the same way of any other report receipt as explained in the How to create a receipt report document. But it is not needed to declare the report in the window POS Print Templates because all the information is already defined in the JSON object.
An example of a template that uses this functionality is:
<% if (ticket.hasbeenpaid === 'Y') { // here goes the check that decides whether to print the receipt report or not %> jrxml:{ "printer": 2, "report": "res/paidorderreport.jrxml", "subreports": [ "res/paidorderreport_subreport1.jrxml", "res/paidorderreport_subreport2.jrxml" ] } <% } else { %> <?xml version="1.0" encoding="UTF-8"?> <output> <ticket> (...)
This example will print depending whether the ticket has been fully paid or not the receipt report res/paidorderreport.jrxml or the receipt template defined after the <ticket> tag.
| | Receipt reports using the new printing engine should also take into account the new ticket properties that are now available to properly reference them inside the jrxml files. |
Migrating legacy templates
Legacy templates are those based on the old printing engine, making use of legacy technology (backbone models and functions that are not bundled as part of the business logic).
| | Legacy print templates are still supported by the new printing engine. But is strongly recommended to update their definition to use the new API. |
In order to turn a legacy print template into a print template fully supported by the new stack we have to update its Application Dictionary definition and, of course, its code.
Changing the AD definition
The POS Print Templates window which can be accessed as System Administrator, contains the definition of the different print templates. By default, the existing templates will have the Legacy flag set as true.
To make our template use the new print engine we must uncheck this field.
Update the template code
Once our print template is defined as a non legacy template in the Application Dictionary, we are able to refactor its code by using the features provided by the new print engine.
Below the table of equivalences between the old and new template APIs is presented. It should be used as a guide to know how to replace the code inside templates in order to adapt them to the new definition:
| LEGACY TEMPLATE API | REPLACED WITH | COMMENTS |
| order (backbone model) | ticket | see here to check the correspondence between properties. |
| line (backbone model) | ticketLine | see here to check the correspondence between properties. |
| OB.MobileApp.model.get('terminal') | OB.App.TerminalProperty.get('terminal') | |
| OB.MobileApp.model.hasPermission | OB.App.Security.hasPermission | |
| OB.I18N.formatCurrency | OB.App.PrintUtils.printAmount | see here to know more functions of the PrintUtils API. |
| OB.UTIL.isNullOrUndefined | == null | |
| OB.UTIL.getChangeLabelFromReceipt | OB.App.PrintUtils.getChangeLabelFromTicket | |
| 'property' + OB.Constants.FIELDSEPARATOR + OB.Constants.IDENTIFIER | 'property$_identifier' | |
| order.getScannableDocumentNo | ticket.documentNo | |
| OB.UTIL.isCrossStoreOrganization(line.get('organization')) | line.organization.id !== OB.App.TerminalProperty.get('terminal').organization |
An example of a migrated report can be seen here.
Deliver Documents
Using this infrastructure, it is possible also to send different templates (i.e. email, sms) to the BO using Deliver Documents
Back to Concepts