Create pdf documents from liquid templates.

This library uses LiquidJS, Symbology, Bz-Date, btrz-formatter and link them together while adding some helpers to easily generate PDFs from templates.

The vesion of PDFMake has been inlined and modified to allow for text rotation.

Install

npm i btrz-liquid-templates

Restrictions

The documents generated only uses Helvetica fonts.

Methods

• processToString

Async method that returns a string.

Parameters

• processToEscp(liquidTemplate, data)

Async method that returns a string and underastands ESCP language

Parameters

• returnToObj(liquidTemplate, data)

Async method that returns an object (the template should be an strinfiable object)

Parameters

Usage

  const tpl = require("btrz-liquid-templates");

  //Returns a string from the template and the data
  async getLiquid(req, res) {
    try {
      const document = await tpl.processToString(template, data);
      res.send(document);
    } catch (err) {
      res.status(500).send(error.message);
    }
  }

  const tpl = require("btrz-liquid-templates");

  //Returns an object from the template and the data
  async getLiquid(req, res) {
    try {
      const document = await tpl.processToObj(template, data);
      res.send(document);
    } catch (err) {
      res.status(500).send(error.message);
    }
  }

  const tpl = require("btrz-liquid-templates");

  //Returns an ESCP string from the template and the data
  async getLiquid(req, res) {
    try {
      const document = await tpl.processToEscp(template, data);
      res.send(document);
    } catch (err) {
      res.status(500).send(error.message);
    }
  }

Custom tags

ESCP language for Epson printers

• escInitQzTray

Initialize the printer Set printer to ESC/P mode and clear memory buffer.

 {% escInitQzTray %} 

• escBold

Start bold font.

 {% escBold %} 

• escCancelBold

Ends bold font.

 {% escCancelBold %} 

• fontSelection

Starts selected font

 {% fontSelection %} 

• escCondensed

Small condensed fonts

 {% escCondensed %} 

• lineSpacing

Line spacing to 1/6 of an inch

 {% lineSpacing %} 

• lineSpacing2

Line spacing to 1/9 of an inch

 {% lineSpacing2 %} 

• escNewLine

New line

 {% escNewLine %} 

• escCut

Paper cut

 {% escCut %} 

• escEject

Form feed (eject paper)

 {% escEject %} 

• escTab

Move to next horizontal tab

 {% escTab %} 

• escHPos

Set absolute horizontal print position

reference ESC $ command

 {% escHPos pos %} 

Parameters

Description

This command sets the absolute horizontal print position (in dots) for the next data that will be printed. It tells the printer exactly how many dots from the left margin to move the print head.

Units

The measurement is in dots. For example, if the printer is configured such that 1 dot equals 1/60 inch, then setting pos to 360 would move the print head to approximately 360 dots, which could correspond to about 60 characters (if one character is roughly 6 dots wide).

Example

Suppose you want to set the horizontal position to 360 dots

Usage in Template

{% escHPos 360 %}

This will move the print head so that the next printed data starts at 360 dots from the left margin.

Images, barcodes and QR codes

• barcode

Generates a barcode based on some data

Parameters

It will use the value of ticket.code to generate the barcode with all the defaults

 {% barcode ticket.code %} 

It will use the value given and use generate a ‘code11’ barcode with a height of 50 and a width of 300

 {% barcode 1234 code11 50 300 20,20,20,0 %}  

Supported types

It supports all types supported by https://symbology.dev/. While symbology supports QRCODE PDFMake also had support for QR natively and we recommend it.

• httpImg

Given a URL for an image will encode into base64 and return in a consumable way for makePDF, only supports png and jpeg

Parameters

 {%- httpImg brand.logos.default -%}  // data:image/png;base64,77+9UE5HDQoaCgAAAA1JSERSAAA...

Supported filters

• qrstr

Returns the proper str to transform into a QR code to be able to scan items with the drivers app

 {%- qrstr reservation -%}  //"https:///r/t/"

 {%- qrstr ticket -%}  //"https:///r/t/"

Parameters

Valid types

reservation, ticket, paid_in, parcel, flexpass, ssr, redeemableItem

Date and Time

• dateTime

Returns a date formatted by the given format from a property of an object given to the liquid template data.

 {%- dateTime ticket createdAt -%}  //"12/21/2021 11:38 AM"

 {%- dateTime ticket createdAt mm/dd/yyyy hh:MM:ss -%}  //"12/21/2021 11:38:00"

Parameters

Prerequisites

There are some prerequisites to use any of the Date helpers. The data given to the liquid template requires the following object to be present

{
  "providerPreferences": {
    "preferences": {
      "dateFormat": "mm/dd/yyyy", //any date format string will do
      "timeFormat": "h:MM TT", //any time format string will do
      "timeZone": {
        "name": "(UTC-5:00) New York (United States), Toronto (Canada)",
        "daylight": true,
        "tz": "America/Toronto"
      } //any timezone as defined in BzDate will do
    }
  }
}

• dateF

Convenience method that will default format to providerPreferenes.preferences.dateFormat

Parameters

 {%- dateF ticket createdAt -%}  //"12/21/2021"

• timeF

Convenience method that will default format to providerPreferenes.preferences.timeFormat

Parameters

 {%- timeF ticket createdAt -%}  //"11:38 AM"

• expDate

Convenience method that will calculate the expiration date for a reservation

Parameters

 {%- expDate reservation -%}  //"12/21/2021 11:38 AM"

• arrivalDate

Convenience method that will calculate the arrival date for a reservation and will apply the arrival station timeZone if available

Parameters

 {%- arrivalDate reservation -%}  //"12/21/2021"

• departureDate

Convenience method that will calculate the departure date for a reservation and will apply the departure station timeZone if available

Parameters

 {%- departureDate reservation -%}  //"12/21/2021"

• arrivalTime

Convenience method that will calculate the arrival time for a reservation and will apply the arrival station timeZone if available

Parameters

 {%- arrivalTime reservation -%}  //"11:38 AM"

• departureTime

Convenience method that will calculate the departure time for a reservation and will apply the departure station timeZone if available

Parameters

 {%- departureTime reservation -%}  //"11:38 AM"

• arrivalDateTime

Convenience method that will calculate the arrival date for a reservation and will apply the arrival station timeZone if available

Parameters

 {%- arrivalDateTime reservation -%}  //"12/21/2021 11:38 AM"

• departureDateTime

Convenience method that will calculate the departure date for a reservation and will apply the departure station timeZone if available

Parameters

 {%- departureDateTime reservation -%}  //"12/21/2021 11:38 AM"

• humanArrivalDate

Convenience method that will calculate the arrival date for a reservation and will apply the arrival station timeZone if available. It will format the date using the humanDate property given to the template. humanDate can be either ‘mm’ or ‘dd’, default to ‘mm’.

Parameters

 {%- humanArrivalDate reservation -%}  //"Tue Dec 21, 2021"

• humanDepartureDate

Convenience method that will calculate the departure date for a reservation and will apply the departure station timeZone if available. It will format the date using the humanDate property given to the template. humanDate can be either ‘mm’ or ‘dd’, default to ‘mm’.

Parameters

 {%- humanDepartureDate reservation -%}  //"Tue Dec 21, 2021"

• humanArrivalDateTime

Convenience method that will calculate the arrival date for a reservation and will apply the arrival station timeZone if available. It will format the date using the humanDate property given to the template. humanDate can be either ‘mm’ or ‘dd’, default to ‘mm’.

Parameters

 {%- humanArrivalDateTime reservation -%}  //"Tue Dec 21, 2021 11:38 AM"

• humanDepartureDateTime

Convenience method that will calculate the departure date for a reservation and will apply the departure station timeZone if available. It will format the date using the humanDate property given to the template. humanDate can be either ‘mm’ or ‘dd’, default to ‘mm’.

Parameters

 {%- humanDepartureDateTime reservation -%}  //"Tue Dec 21, 2021 11:38 AM"

• humanDate

Convenience method that will default format based on the humanDate property given to the template as part of the data object. humanDate can be either ‘mm’ or ‘dd’

(humanDate === "mm") ? "ddd mmm dd, yyyy" : "ddd dd mmm, yyyy"

Parameters

 {%- humanDate ticket createdAt -%}  //"Tue Dec 21, 2021"

• humanDateTime

Convenience method that will default format based on the humanDate property given to the template as part of the data object. humanDate can be either ‘mm’ or ‘dd’ plus the providerPreferenes.preferences.timeFormat

(humanDate === "mm") ? "ddd mmm dd, yyyy" : "ddd dd mmm, yyyy"

Parameters

 {%- humanDateTime ticket createdAt -%}  //"Tue Dec 21, 2021 11:38 AM"

Lines, HTML, Lexicons and text

• keys

Given an Object converts it to an array of keys.

For this object:

{
  "prop1": "value1",
  "prop2": "value2"
}

You can iterate over the object keys

 
{%- assign objectKeys = brand.logos.default -%} 
{%- for aKey in objectKeys -%} 
  Key number {%forloop.index%} : {{aKey}}
{%- endfor -%} 
 

//"Key number 1: prop1"
//"Key number 2: prop2"

• h

This tag will parse “some” HTML code and try to generate compatible PDFmake text objects.

Parameters

 {% h ticket.lexiconKeys.terms %}  //If will get the string in the property and parse it

Supported html tags

h1 - will generate a text node with “style”: “header” h2 - will generate a text node with “style”: “subheader” h3 - will generate a text node with “style”: “innerheader” b - will generate a text node with “bold”: true i - will generate a text node with “italics’”: true

• hline

This tag generates an horizontal line

Parameters

 {%- hline 475 2 255,112,0 - %}  //Generates an svg line with the width, weight and colour given

 {%- hline 475 2 providerPreferences.preferences.colors.brandBackground - %}  //Generates an svg line with the width, weight and colour given

{
  "svg": "<svg height='2' width='100'><line x1='0' y1='0' x2='1000' y2='0' style='stroke:rgb(255,112,0);stroke-width:2' /></svg>",
  "width": 475
}

• t

Returns a translation based on a key, it can use a string or variables from the data given to the liquid template

Prerequisites

There are some prerequisites to use the t tag. The data given to the liquid template requires a localizer object with a .get(key) method that can return the translation. The implementation is up to you.

Parameters

 {% t 'issued' %}  //Will return the value on the lexicon with the 'issued' key

 {% t fare.lexiconKeys.description %}  //Will return the value on the lexicon with the key stored in the `data.fare.lexiconKeys.description` property

• txt

Split lines or hardcoded text that may include carriage returns

Parameters

" {% txt operatingCompany.infoOnPrintedTicket small %} " //Given that ticket.total is 2800000 returns "28.00"

Money and currency

• money

Returns a money value

Parameters

" {%- money ticket total -%} " //Given that ticket.total is 2800000 returns "28.00"

• moneyReduce

Adds the values of a property in objects in a collection and returns the total as a money value

Parameters

" {%- moneyReduce ticket.fees subTotal -%} "

• curcyName

Returns the currency name based on the displayCurrency of the item provided and the account configuration. If the item provided is a currency, it will just use that currency,

Parameters

 {%- curcyName ticket -%} ",

• curcySymbol

Returns the currency symbol based on the currency used to paid the item or the default currency given in the providerPreferences.preferences.supportedCurrencies[0]

Parameters

 {%- curcySymbol ticket -%} ",

• curcyIso

Returns the currency ISO code based on the currency used to paid the item or the default currency given in the providerPreferences.preferences.supportedCurrencies[0]

Parameters

 {%- curcyIso ticket -%} 

• toLetters

Returns the amount in letters given in the property (amount should follow US notation, uses “.” for cents). It can translate values using the lang and localizer

Parameters

 {%- toLetters '100.50' -%}  // One hundred with fifty cents

 {%- toLetters '123' -%}  // One hundred and twenty three