Editing a print template can be a technically involved process. This page assumes that you are quite technically literate. If you are uncomfortable with the information presented on this page, it is recommended that you speak with your system implementor to adjust your print templates.

Note: Mistakes made in configuring a print template may cause disruption of the remainder of the same docket print, however will not affect other print templates.

Note: Syntax errors or runtime errors detected in the print template markup will be written to the server logs under the “error” log type.

Note: Missing templates are assumed to be a deliberate suppression of printing, and are not logged as an error.

 

Editing Print Templates

TBD

 

 

Available Print Templates

The following reserved template names are used automatically by the POS software. Templates with other names may be created, but are not automatically used by the POS software.

• receipt-user-request
• receipt-submit
• receipt-bill
• receipt
• submitted-item-summary
• submitted-item-details
• table-move
• user-request
• submit
• order-bill
• order-receipt
• petty-cash
• received-stock
• daily-report

 

Print Template Markup Language

The Print Template script uses a simple markup language to convert a number of input variables (including item arrays) into formatted text suitable for printing on a POS printer. The markup language is effectively a programming language with logic constructs to allow substantial customisation of the print output, but it is not intended for running complex programs.

Within the markup language, tokens are separated using whitespace or line breaks. Each token may represent a reserved function, a variable name, or a text literal. Each token is evaluated and the result is written to the print output.

 

Command Tokens

“” – Quotes are used to begin and end a literal string. A quote may be included into a literal string by escaping it with a slash ( \ ) character.

( value ) – Parentheses trigger the evaluation of the included tokens. This can be used to perform math or function evaluation. See the “Evaluation” section below for more details.

if ( booleancondition ) { statements } – Evaluates the specified condition as a boolean (true or false) value. If it is true, the statements are performed. If it is false, the statements are skipped.

if ( booleancondition ) { statements } else { statements } – Evaluates the specified condition as a boolean (true or false) value. If it is true, the first set of statements are performed and the second set are skipped. If it is false, the first set of statements are skipped, and the second are performed.

loop variablename { statements } – Loops through every item in the named array variable, performing the specified statements for each in turn. It is not recommended to modify the named variable array during iteration, as the results are undefined. The named variable must exist.

set variablename = value – Evaluates the value and stores the result into the specified named variable. The variable does not need to exist prior to this command. If it did exist, its old contents are erased and the new contents take their place. Built-in variables should not be overwritten in this fashion.

format (align:value, field-width:value, space-character:value, overflow:value, wrap-indent:value, bold, underline, large) { statements } – Assigns one or more formatting tags to any output produced by the specified statements. Format commands may be nested as desired, and any tags not specified in a given format statement are inherited from the parent state. The format tags are discussed in detail in the “Formatting” section below.

linebreak – Causes the current output line to end, and any new output to begin on the next line.

papercut – Causes a paper-cut instruction to be emitted to the printer. Most POS printers have a several-line gap between their print head and the paper cutter mechanism. Care must be taken with the placement of the papercut command to ensure that the cut lines up with the desired location in the print.

drawkick value – Value must evaluate to one of the following integers, each of which triggers a predefined behaviour. The behaviour may vary depending on the capabilities of the POS printer receiving this output and/or the devices connected to the printer. 0: activates the primary draw kick. 1: activated the secondary draw kick. 2: activates the primary integrated beeper. 3: activated the secondary integrated beeper.

logo – A single black-and-white logo image may be defined for the site. This command causes that logo to be printed inline.

 

Evaluation

Literal evaluation

Literal evaluation occurs in the grammar wherever the “value” term appears in this document. The literal may consist of one or more simple literals, where multiple literals are separated by appropriate operator tokens.

The first token of a literal evaluation sequence is always a simple literal or a function (see the “functions” section below.) This may optionally be followed by an operator and an additional simple literal. This process may be repeated as desired. Operators are evaluated using precedence ordering, as follows:

• “*”, “/”, “%” – Numeric multiplication, division, and remainder. Both input values must be numeric, or a runtime error results. These are the highest precedence and always evaluated first and in left-to-right order. The result is always numeric.
• “+”, “-” – Numeric addition and subtraction. Both input values must be numeric, or a runtime error results. The result is always numeric.
• “<=”, “<“, “>”, “>=” – Numeric comparison. Both input values must be numeric, or a runtime error results. The result is the literal “true” or “false” as appropriate.
• “==”, “!=” – Equality and inequality. Input values are interpreted as strings. This can be used for numeric comparison, but care must be taken as “1.0” and “1.00” are considered different values. User-entered values can be normalised by adding zero to force numeric conversion. The result is the literal “true” or “false” as appropriate.

If any other token is encountered where an operator token might be expected, literal evaluation ends and regular parsing continues. When parsing parentheses, the only acceptable ending token is the closed parenthesis; using any other token to end literal evaluation will cause a runtime error.

 

Boolean evaluation

Boolean evaluation occurs in the grammar wherever the “booleancondition” term appears in this document. Boolean evaluation simply consists of regular literal evaluation, followed by determining whether the result of that evaluation is true or false. Simply put:

• If the result of the literal evaluation is an empty string (“”), a zero value (“0”) or literally the string “false” (case insensitive) then the boolean is evaluated as false.
• Otherwise, the boolean is evaluated as true.

Functions

The following reserved tokens may be used within any literal evaluation:

• has variablename – Determines whether the named variable is set, and returns “true” if set, or the empty string (“”) if unset. This should be used before attempting to use a named variable if it is not known whether the variable is set, as attempting to use an unset variable will result in a runtime error.
• ! booleancondition – Evaluates the boolean condition, and negates the result. That is to say, this returns “false” if the boolean was true, or “true” if the boolean was false. The “!” is read as “not”.
• – value – Evaluates the value as a number, then returns the negated value of that number. A runtime error occurs if the specified value does not evaluate to a number.
• ( value ) – Performs a literal evaluation of the bracketed tokens.
• formatstr ( value, units ) – Evaluates “value” as a number, and “units” as a string, then uses the built-in formatters to express the value in a human-readable format for the requested units. A runtime error occurs if the specified value does not evaluate to a number. The units string is case sensitive and must exactly match one of the supported formatting units. See the “Units” section below for unit formatting rules.
• parsestr ( value, units ) – Evaluates “value” and “units” as strings, then uses the built-in formatters to convert the value from human-readable format for the given units into a number. If the value cannot be parsed for the given units format, a zero number is returned. See the “Units” section below for unit formatting rules.
• “” – Quotes are used to begin and end a literal string. A quote may be included into a literal string by escaping it with a slash ( \ ) character. The literal string is returned exactly as stated, with the surrounding quotes and any escaping processed out.
• number – Any integer number may be included without special markup.
• variablename – Any non-array named variable may be included without special markup. The contents of the variable are output. The named variable may be located from the current scope, or from an enclosing “loop” command.

 

Formatting

TBD.

 

Units

When formatting units, the following techniques are currently supported:

• Items – TBD.
• Serves – TBD.
• Milliliters – TBD.
• Grams – TBD.
• Dollars – TBD.
• Cents – TBD.
• Seconds – TBD.

All unsupported units are simply output as a raw (unformatted) number, however care should be taken as new formatting techniques may be supported in the future.

 

Built-in Variable Names

Our POS software provides a number of built-in variables which are used to display specific types of information in your print template.

Customer Loyalty

Customer loyalty variables are set whenever printing with “user-request”, “submit”, “order-bill”, or “order-receipt” templates. If no loyalty card is associated with the Order, these variables will be empty.

• loyalty-card-customer-name – The full name of the customer, as per their loyalty card.
• loyalty-card-customer-email – The email address of the customer, as per their loyalty card.
• loyalty-card-customer-phone – The contact phone number of the customer, as per their loyalty card.
• loyalty-card-customer-address – The street address of the customer, as per their loyalty card.

Order Data

Order data variables are set whenever printing with a template that relates to a specific Order. Some specific variables may only be set in specific occasions; this is noted in the description for that variable.

• items – A list of all items in the Order. For each item in the list:
  • item-count – A number representing the quantity of this item ordered.
  • item-number – The “item number” as per the menu.
  • item-name – The print name for this item. (TBD: print index)
  • item-name-english – The english name for this item, as per the menu.
  • item-name-alternate – The alternate-locale name for this item, as per the menu.
  • item-price – A currency value representing the base price for this item, without any modifiers. Does not take into account surcharges, discounts, etc. Does take into account item quantity.
  • item-price-with-modifiers – A currency value representing the base price for this item including any modifiers. Does not take into account surcharges, discounts, etc. Does take into account item quantity.
  • item-has-been-cancelled – A boolean value representing whether this item has been cancelled since being ordered.
  • item-custom-text – Any operator-entered custom text for this item.
  • item-seating-position-text – A text string representing “seating position” information for this item.
  • item-section-name – The name of the order section in which this item resides (not localised.)
  • modifiers
    • modifier-name – The print name of this modifier.
    • modifier-name-english – The english name of this modifier, as per the menu.
    • modifier-name-alternate – The alternate-locale name of this modifier, as per the menu.
    • modifier-price – A currency value representing the base price for this modifier. Does not take into account surcharges, discounts, etc. Does take into account item quantity.
  • item-printers – A list of all printers on which this item is assigned to print. Only set if this item has printers assigned.
    • printer-id – TBD.
    • printer-item-name – The print name of this item on this printer.
  • item-name-first-printer – One of the ‘printer-item-name’ values from the ‘item-printers’ list, chosen effectively at random. It is recommended that this is used only where there is exactly one printer assigned to the item. In the event that there is no ‘item-printers’ list, this matches the “item-name” variable (sort of; it’s complicated.)
• sections – A list of all Menu Sections listed in this Order. For each section in the list:
  • section-name – The name of this section (not localised.)
  • section-items – A subset of the above ‘items’ variable, listing only those items which are ordered in this section.
• selected-items – A subset of the above ‘items’ variable, which only includes those items which are selected. This variable is only present in templates where selection is relevant.
• order-printers – A list of all printers to which the items in this Order will print. For each printer in the list:
  • printer-id – TBD.
• takeaway-number – Where a takeaway number is assigned to the Order, this variable is set to that number.
• order-id – Where an Order ID is assigned to the Order, this variable is set to that number.
• operator-name – The name of the operator who triggered this print.
• terminal-name – The name of the terminal on which this print was triggered.
• customer-count – The number of customers assigned to the Order (as per the Table Info screen.)
• current-date – The date at the time of printing.
• current-time – The time of printing.
• order-outstanding-item-cost – A currency value indicating the total amount outstanding on the order. This is a raw value and does not include the effects of any discounts, surcharges, etc.
• expected-completion-date – The date of the expected completion of the order.
• expected-completion-time – The time of the expected completion of the order.
• order-status – If the order has an “order status item” associated, this is set to the name of that item.

Petty Cash

• amount – The amount of petty cash withdrawn, as entered by the operator.
• reason – A text string entered by the operator to indicate their reason for withdrawing petty cash.

Received Stock

• received-stock – A list of each received stock item.
  • received-stock-name – TBD.
  • received-amount – TBD.

Daily Report

• report-text – TBD.

Transaction Data

Print templates involving Order billing data include the following additional variables:

• transaction-amount – A currency value indicating the total payment amount for the selected items.
• transaction-surcharge-percentage – A numeric value indicating the percentage surcharge set for the order. Only set if the percentage surcharge is non-zero or if a surcharge is present for some other reason.
• transaction-surcharge – A currency value indicating the total surcharge for the selected items. Only set if the percentage surcharge is non-zero or if a surcharge is present for some other reason.
• transaction-surcharge-flat – A currency value indicating the flat surcharge for the active payment method. Only set if the percentage surcharge is non-zero or if a surcharge is present for some other reason.
• transaction-discount-percentage – A numeric value indicating the percentage discount set for the order. Only set if the percentage discount is non-zero or if a discount is present for some other reason.
• transaction-discount – A currency value indicating the total discount for the selected items. Only set if the percentage discount is non-zero or if a discount is present for some other reason.
• transaction-rounding – A currency value indicating the total rounding applied to the selected items. Only set if non-zero.
• transaction-tax – A currency value indicating the total tax component of the price of the selected items. Only set if non-zero.
• transaction-total – A currency value indicating the total payment required for the selected items, taking into account tax, discount, surcharge, etc.
• transaction-prepaid – A currency value indicating the total currency amount prepaid onto the Order. Items which have already been paid off do not contribute to this amount. Only set if non-zero.
• transaction-change – A currency value indicating the amount of change that will be given in this transaction. Only set if non-zero.
• loyalty-card-number – The number of the loyalty card assigned to this order. Only set if a loyalty card is assigned.
• loyalty-card-points-total – A numeric value indicating the number of loyalty points on the loyalty card assigned to this order. Only set if a loyalty card is assigned.
• loyalty-card-cash-total – A currency value indicating the amount of gift cash available on the loyalty card assigned to this order. Only set if a loyalty card is assigned and the currency value is non-zero.
• loyalty-card-customer-name – The name of the customer as per the loyalty card assigned to this order. Only set if a loyalty card is assigned.
• loyalty-card-customer-email – The email address of the customer as per the loyalty card assigned to this order. Only set if a loyalty card is assigned.
• loyalty-card-customer-phone – The phone number of the customer as per the loyalty card assigned to this order. Only set if a loyalty card is assigned.
• loyalty-card-point-credit – The number of loyalty points generated by this transaction. Only set if non-zero. Does not require a loyalty card to be assigned to this order, however if no loyalty card is assigned then these points are lost.