Ticket XML

A ticket is a small XML document. The root element must be <ticket>. Raven turns it into whatever the printer at the other end speaks, so the same ticket works on hardware with different command languages, widths and character sets.

The two render modes

The format field on a print request picks between them. Text mode ("Xml", the default) composes the ticket in the printer's native character grid: fastest, most compatible, and what you want for ordinary receipts. SVG mode ("Svg") renders the ticket as a graphic and sends it as an image: proportional type, exact rules, and layout that does not have to land on character boundaries. It prints more slowly and uses more paper feed.

Author the same Ticket XML either way. Reach for SVG mode when the layout matters more than the speed; stay on the default otherwise.

Text and layout

No attributes; nest them freely.

Structure

Void elements: write them self-closed.

Tables

A table has two different children, and mixing them up is the most common mistake in Ticket XML:

• <col> defines a column, in document order. Its own text is that column's header.
• <row> is a data row, holding one <val> per cell.

<table>
  <col s="3">Item</col>
  <col s="1" a="r">Qty</col>
  <col s="2" a="r">Price</col>

  <row>
    <val>Espresso</val>
    <val>2</val>
    <val>5.00</val>
  </row>
  <row>
    <val>Croque-monsieur</val>
    <val>1</val>
    <val>9.50</val>
  </row>
</table>

These are the format's only attributes:

Rules worth knowing

• Cells are plain text. Style tags inside a <val> are not supported: the text comes through, the formatting does not. If a total has to be bold, give it its own <p> line instead.
• A header row appears only if some <col> carries text. For a headerless block such as a totals table, write self-closing <col s="4"/> elements that carry weights and nothing else.
• No <col> at all is legal. The column count is then inferred from the widest row: equal widths, left aligned, no header.
• Short and long rows are tolerated. Missing cells pad blank; cells past the last column are dropped.
• One font per table. A table inside <small> renders wholly in that font and fits proportionally more columns. Mixed fonts would break the alignment, so they are not offered.
• A table is always full width. Wrapping one in <c> does nothing.

Media and symbology

Worked examples

A receipt

<ticket>
  <c><bold><big>LE COMPTOIR</big></bold></c>
  <c><small>12 rue des Halles · Brussels</small></c>
  <br/>
  <hr/>
  <table>
    <col s="3">Item</col>
    <col s="1" a="r">Qty</col>
    <col s="2" a="r">Price</col>
    <row><val>Espresso</val><val>2</val><val>5.00</val></row>
    <row><val>Croque-monsieur</val><val>1</val><val>9.50</val></row>
  </table>

  <hr/>

  <table>
    <col s="4"/>
    <col s="2" a="r"/>
    <row><val>TOTAL</val><val>14.50</val></row>
  </table>
  <br/>
  <c><qr>https://le-comptoir.example/receipt/42</qr></c>
  <br/>
  <cut/>
</ticket>

A kitchen order

Large, no prices, no logo. It is read across a hot kitchen at arm's length.

<ticket>
  <c><bold><big><wide>TABLE 7</wide></big></bold></c>
  <hr/>
  <big><p>2x Steak - rare</p></big>
  <big><p>1x Frites</p></big>
  <br/>
  <cut/>
</ticket>

Preview before you print

POST /printers/{id}/render returns the ticket as it would come out of that printer: its width, its character grid. Use it in your own tooling so you are not debugging layout by burning paper in a live venue.

Before you send

• Root element is <ticket>.
• There is a <cut/> at the end.
• Text that must be read across a room is <big>, not just <bold>.
• Money columns use a="r".
• You sent an idempotencyKey. See Printing a ticket.