Skip to main content
Skip table of contents

ReceiptLayout

The ReceiptLayout document allows the definition of the format of a receipt.

The layout is used only when the receipt is printed on a “NO FISCAL” device, because fiscal devices usually have a strict layout defined by the device itself

Introduction

The Receipt Layout is an XML Document which describes:

  • The styles to be applied to the the text printed on receipts

  • The data mapping between the Receipt Object and the printed receipt

Styles are defined in a LayoutStyle Document but their properties can be overridden on each element

File extension for Receipt Layout is: .utdl

Basic Concepts

Constants

It is possible to define constant values to avoid the repetition of a value in the document body.

Constant names MUST start with the @ symbol.

Constants do not have a type. The type conversion will be implicitly performed according where the constant is used.

The following conventions are used:

Const type

Convention

string

any value

numeric

Dot as decimal Separator

date / datetime

ISO-8601 Standard:

  • Date: YYYY-MM-DD

  • DateTime: YYYY-MM-DDThh:mm:ss

Examples

@MyBirthDate=”1966-04-05T11:00:00”

@MyName=”Marco”

@MyTemperature=”36.5”

Binding Receipts to Layouts

The format to be used is specified in the parameter… [TODO]

Binding Receipt Parts to Formats

The receipt layout is divided into formats. Each format represents a different part of the receipt object

These are the formats and their sequence in the receipt itself

Receipt Parts

Format Name
(Sales Receipt)

Format Name
(Document)

Receipt Header

ReceiptH

NFReceiptH

Leader Messages Header

LeadMessagesH

NFLeadMessagesH

Leader Messages (iterate)

LeadMessage

NFLeadMessage

Leader Message Footer

LeadMessagesF

NFLeadMessagesF

Lines Header

LinesH

NFLinesH

Lines (iterate)

Line

NFLine

Lines Footer

LinesF

NFLinesF

Taxes Header

TaxesH

N/A

Taxes (iterate)

TaxLine

N/A

Taxes Footer

TaxesF

N/A

Payments Header

PaymentsH

N/A

Payments (iterate)

PaymentLine

N/A

Payments Footer

PaymentsF

N/A

Trailer Messages Header

TrailMessagesH

NFTrailMessagesH

Trailer Messages (iterate)

TrailMessage

NFTrailMessage

Trailer Messages Footer

TrailMessagesF

NFTrailMessagesF

Receipt Footer

ReceiptF

NFReceiptF

Line formats can also be differentiated by their type.

To differentiate them, the Format Name is composed by the Formate Name itself plus the XML node name.

Example: to specify a different format for ProductSale lines, you must create a format with the following name: Line.ProductSale

XML Document Structure

Level

Node Name

Attribute Name

Node Value(s)

Notes

1

DocumentLayout

 

Root Node 

2

Aspect

3

FontMaps

4

Font

Name

The name of the font as specified in the LayoutStyle Document

MapKey

<Protocol>[.<DeviceModel>]
The MapKey is first composed by the union of the protocol and the device model (separated by a dot). If there is no match the next attempt is done using only the protocol.

When and if a match is found the node value will be used to assign the font name

<string>

The font name to be used

3

Styles

<string>

Name of the Layout Style Document to be applied.

The name can be:

  • File name
    The style is stored on the filesystem.
    If a relative path is used, the directory of the Receipt Layout is the base directory from which the style document will be searched
    It is also possible to use an absolute path.

  • Resource Name
    The style is embedded in the driver
    Some UTD Drivers embed a style definition. Please refer to UTD Drivers docs for their names.

3

LineLength

<integer>

Number of characters per line (fixed spacing)
Default = 46

3

DefaultStyle

<string>

Name of the style that will be used if no style is specified at format or line level

3

Charset

<string>

ISO 369-1 Code of the language.
See “Charset Table” for details

2

Vars

Collection of variables

3

Var

Various

Variables are defined as an attribute tuple <Name>=<Value>

Variable names MUST start with @ symbol (eg: @MyVar=”myvalue”)

2

Formats

Collection of Formats

3

Format

Format definition

Name

<string>

Format Name

Style

<string>

Style Name

4

<Various>

This is a list of Nodes that represent the various data that will be printed.

The nodes be of different types. You can mix as many types as you want.

See Receipt Layout Format Items for details of each type

Receipt Layout Format Items

Format Items represent the data that will be printed. Each format item is composed by two different parts.

  • Attributes: they are represented as XML Node Attributes. Each type of Format Item has its own set of attributes (e.g. Keys for NVIMages, FontName for Texts, BarcodeType for Barcodes)

  • Values: represented as XML Node Values, they contain the data that will be printed. Data can be:

    • Receipt Data: enter the needed node name enclosed between double braces. The value contained is always related to the node that is being processed. If you need to access a value contained in child node, you should prefix the child node value with its node name, using a dot as separator between them.
      Some examples (referred to the receipt header) are:
      {{StoreCode}} - the Store Code
      {{References.OriginalReceipt.ReceiptDateTime}} - The Date/Time of the original receipt in a return receipt
      It is also possible to print a part of the data. This is performed using the following syntax:
      {{<data>:<StartPosition>:<Length>}}
      where
      <data> is the node name
      <StartPosition> is the position of the first character you want to extract
      <Length> is the number of characters you want to extract

    • Auto-calculated values: These values must be enclosed between double braces and are automatically calculated by the application. The following values are available:

      • {{TotalAmountNoTaxes}} - Total amount of the receipt (no tip, no taxes)

      • {{TotalAmountTaxes}} - Total amount of taxes

      • {{TotalAmountDue}} - Total amount due (tip and taxes included)

    • Costants: just enter the value needed

If you specify a Negative Number the string scanning will be performed from right to left.
For example, assuming the string ABCDEFGHI:

{{string:2:3}} = BCD
{{string:-4:3}} = FGH
{{string:5:-2}} = DE
{{string:-2:-3}} = FGH

All Format Items can specify a style name, if different from the Format style name. If no style name is specified at item level, the format style name will be used.

NvImage

Prints an Image stored in the memory of the printer.

Attributes

Name

Values

Notes

Mandatory

Key1

<integer>

The value of Key1

Yes

Key2

<integer>

The value of Key 2

Yes

Value

<none>

Text

Prints a Text

Attributes

Name

Values

Notes

Mandatory

Picture

<string>

Picture to be applied to the value.
Allowed Symbols:
Strings:
'UC' = Uppercase
'LC' = Lowercase

Numbers:
'.' = Decimal Separator
',' = Thousands Separator
'#' = Digit Placeholder
'0' = Digit Placeholder: if value is zero, a zero will be printed

Dates and DateTimes:
'-' = Date Separator
yyyy = Year
mm = Month
dd = Day
hh = Hour
nn = Minute
ss = Seconds

NewLine

<boolean>

True = a CR/LF will be added at the end of the string

False = no CR/LF added

Col

<string>

Defines a column. The definition must obey to the following format:
<startColumn>:<colLength>[:<alignment>]

Where:

  • startColumn is the column where the text will be printed

  • colLength is the length of the column

  • alignment can assume the following values:

    • L = Left aligned [Default]

    • R = Right aligned

    • C = Centered

Value

Value to be printed

Barcode

Print a barcode according to the symbology specified

Attributes

Name

Values

Notes

Mandatory

Type

CODE128
CODE39
EAN13
EAN8
QRCODE
UPCA
UPCE

The Barcode Symbology

Yes

HRI

<boolean>

True = The barcode text will be printed below the barcode
False = No text will be printed

Value

Value to be coded in the barcode

For EAN8, EAN13, UPCA, UPCE: if the checksum is not provided it will be automatically calculated

Line

Print an horizontal line

Attributes

Name

Values

Notes

Mandatory

Size

<integer>

Size of the pen used to draw the line

Value

<none>

If

Express a condition. Its children nodes are evaluated only if the condition is true.

Children nodes can be items of any type, “If” included

The “else” child node is logically treated as a sibling of the “if” node. We chose this option for the sake of simplicity and readability of the XML document. The below example should clarify the approach.

Attributes

Name

Values

Notes

Mandatory

Value1

<string>

First Value to compare

Yes

Cond


eq
ne
gt
ge
lt
le
in
ni

Conditional operator
equal
not equal
greater than
greater or equal
lower than
lower or equal
in
not in

Yes

Value2

<string>

Second Value to compare

Yes

Value

<none>

if conditions are simple. There is no option for complex logical expression like AND, OR.

If you need to check multiple Value2 against a single Value1 you can use the ”in” or “not in” operators

If you need to use “and” logical operator, just nidificate another “If” node

If you need to use “or” logical operator, you must repeat the whole “If” block

Example

SQL 
<If Value1="{{Type}}" Operator="eq" Value2="Sale">
  <Text>This is a Sale</Text>
  <Else/>   
  <If Value1="{{Type}}" Operator="eq" Value2="Return">
    <Text>This is a Return</Text>
    <Else/>
    <Text>This is neither a Return nor a Sale</Text>
  </If>
</If>

Else

Express a condition. Its sibling nodes (starting from the following node) are evaluated only if the parent “if” condition is false.

This node does have neither attributes nor node values

Charset Table

Charset

Language

Codepage

Encoding

el

Greek

1253

ISO-8859-7

gr

Greek

1253

ISO-8859-7

<other>

Multilingual

858

UTF-8

XML Document Sample

XML 
<DocumentLayout> 
  <Aspect>
    <Styles>StyleLayout</Styles>
    <DefaultStyle>Line_Default</DefaultStyle>
    <FontMaps>
      <Font Name="A" MapKey="ePOS">font_a</Font>
      <Font Name="B" MapKey="ePOS">font_b</Font>
      <Font Name="C" MapKey="ePOS">font_c</Font>
      <Font Name="D" MapKey="ePOS">font_d</Font>
      <Font Name="E" MapKey="ePOS">font_e</Font>
      <Font Name="A" MapKey="Image">Courier New</Font>
      <Font Name="B" MapKey="Image">Courier New</Font>
      <Font Name="C" MapKey="Image">Courier New</Font>
      <Font Name="D" MapKey="Image">Courier New</Font>
      <Font Name="E" MapKey="Image">Courier New</Font>
    </FontMaps>
  </Aspect>
  
  <!-- Constants Definition -->
  <Consts>
    <Const PicPrice="#,##0.00"/>
  </Consts>

  <Formats>
    <!--**********************-->
    <!--* Non fiscal Receipt *-->
    <!--**********************-->
  
    <!-- RECEIPT HEADER -->
    <Format Name="NFReceiptH" Style="Head">  
      <NVImage Key1="32" Key2="32"/>
    </Format>

    <!-- HEADER -->
    <Format Name="NFLeadMessagesH" Style="Head"/>
 
    <Format Name="NFLeadMessage" Style="Head">
      <Text>{{Value}}</Text>
    </Format>
   
    <Format Name="NFLeadMessage.Barcode" Style="Head">
      <Barcode Type="{{BarcodeType}}">{{Value}}</Barcode>
    </Format>

    <Format Name="NFLeadMessagesF" Style="Head"/>
    
    <!-- LINES -->
    <Format Name="NFLinesH" Style="Head"/>

    <Format Name="NFLine" Style="Head">
      <Text>{{Value}}</Text>
    </Format>

    <Format Name="NFLine.Barcode" Style="Head">
      <Barcode Type="{{BarcodeType}}">{{Value}}</Barcode>
    </Format>

    <Format Name="NFLinesF" Style="Head"/>

    <!-- FOOTER -->
    <Format Name="NFTrailMessagesH" Style="Head"/>

    <Format Name="NFTrailMessage" Style="Head">
      <Text>{{Value}}</Text>
    </Format>

    <Format Name="NFTrailMessage.Barcode" Style="Head">
      <Barcode Type="{{BarcodeType}}">{{Value}}</Barcode>
    </Format>

    <Format Name="NFTrailMessagesF" Style="Head"/>
    
    <!-- RECEIPT FOOTER -->
    <Format Name="NFReceiptF" Style="Head">
      <Text>{{ReceiptDateTime}}</Text>
    </Format>

    <!--******************-->
    <!--* Fiscal Receipt *-->
    <!--******************-->

    <!-- Receipt Header -->
    <Format Name="ReceiptH" Style="Head">
      <NVImage Key1="32" Key2="32"/>
    </Format>

    <!-- Header Messages -->
    <Format Name="LeadMessagesH" Style="Head"/>
    
    <Format Name="LeadMessage" Style="Head">
      <Text>{{Value}}</Text>
    </Format>
    
    <Format Name="LeadMessagesF" Style="Head"/>
    
    <!-- Default Line -->
    <Format Name="Line" Style="Line_Default">
      <Text>{{Description}}</Text>
    </Format>

    <!-- Footer Messages -->
    <Format Name="TrailMessageH" Style="Footer"/>
    
    <Format Name="TrailMessage.Barcode" Style="Footer">
      <Barcode Type="EAN13">{{Barcode}}</Barcode>
    </Format>
    
    <Format Name="TrailMessage" Style="Footer">
      <Text>{{Description}}</Text>
    </Format>
    
    <Format Name="TrailMessageF" Style="Footer"/>
    
    <!-- Receipt Footer -->
    <Format Name="ReceiptF" Style="Footer"/>
  </Formats>

</DocumentLayout>

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close