View source | Discuss this page | Page history | Printable version   

Retail:Developers Guide/New Javascript template engine for receipt printer and customer displays documents

Contents

New Javascript template engine for receipt printer and customer displays documents

Bulbgraph.png   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:

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:

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:

Besides, the org.openbravo.retail.posterminal module provides some utilities to deal with ticket information:

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:

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.

Bulbgraph.png   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).

Bulbgraph.png   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.


LegacyPrintTemplate.png

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

Retrieved from "http://wiki.openbravo.com/wiki/Retail:Developers_Guide/New_Javascript_template_engine_for_receipt_printer_and_customer_displays_documents"

This page has been accessed 1,669 times. This page was last modified on 19 September 2022, at 08:40. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.