Receipt documents
What you send to be printed: blocks of text, tables, codes and images, which Tillcast renders for the printer.
A job carries a document: the receipt, as an array of blocks in the order they print. A block is one visible unit, such as a line of text, a table, a rule or a QR code, and it says what it is in its type. You never write printer commands and you never write markup. Tillcast turns the blocks into the commands of the printer’s profile when it accepts the job, so the same document prints on a Star and on an Epson.
The text of a block prints as it is written. A |, a {, a _ or a line of dashes in a name is a character and not markup, so there is nothing to escape.
If you already have a document written for other ReceiptLine tools, you can send it as text in the field receiptline instead. See Advanced: ReceiptLine text.
Rendering happens when the job is accepted. A mistake in a document is therefore an answer to your request, not a job that fails later. The answer says how large the print is and lists what the renderer noticed, see Warnings. Tillcast does not keep the document: no call returns it and nothing logs it. To print it again, send it again.
A first document
This document has a title, a line with the table number and a table with two items and a total.
The examples on this page come with a text view, 32 characters wide, as a 58 mm printer would print it. The text view cannot show bold, underline or inverse, and it shows a line of double size with a space after every letter.
The paper is cut at the end of every document, unless the printer’s print_options say cutting: false. See Profiles and print options.
A job takes document or receiptline, exactly one of the two. Both, or neither, is 422 document_invalid. The SDKs cannot tell you before the call, because both fields are optional in their types.
Blocks
Every block is an object with a type. A field that a block does not have is refused, and so is a type that is not one of these nine.
Most fields can be left out. What a field does when it is not said is written below.
Text and style
text is a string, or a list of pieces. A piece is a string or an object with its own style, such as {"text": "7.60", "bold": true}. align is left (the default), center or right. A line break in the text is a line break on the paper. A text that is longer than the paper wraps at the edge, by characters and not by words, unless wrap is false: then it is cut at the edge. The renderer counts every character as one column, wide ones such as Chinese, Japanese, Korean and emoji too. A character that the printer’s code page lacks prints as ?, with the warning character_unmappable.
text, row and table take four style fields. They are independent, and any of them goes with any other.
A piece of a text, and a cell of a row or a table, can say its own style. What it does not say it takes from what is around it. A line is as high as its highest piece.
The third line shows what the blocks are for: a brace, a bar and underscores print as they are.
Rows and tables
A table declares its columns once and then has rows. A row is one line of cells with its own columns. Without columns, the cells of a row share the line equally.
A column is one of these:
- A width in characters, such as
9. A width is 1 to 96. "*": what the other columns leave.{"width": 9, "align": "right"}: a width, an alignment, or both. The text of a column sits on the left unless it says otherwise.
A cell is a string, or an object with its own style and alignment: {"text": "Total", "bold": true, "align": "right"}. A row has at most as many cells as there are columns. A shorter row leaves the last columns empty. A table has at most 16 columns.
border is space (one space between the columns, the default), none, or line (a ruled frame around every cell). A table with fixed widths only and no "*" column is narrower than the paper, and align says where it sits. With a "*" column it fills the paper.
A {"type": "rule"} among the rows is a horizontal rule. In a table with border: "line" it is a line between two rows, so it must stand between two rows.
A column counts characters of normal size. A cell of size 2 holds half as many in the same column, and a size whose characters are wider than the column is refused. A long cell wraps inside its column, by characters, unless wrap is false: then it is cut at the end of its column.
Rules, cuts and blank lines
{"type": "rule"} is a rule across the paper. {"type": "cut"} cuts the paper at that place. {"type": "feed", "lines": 2} makes 1 to 20 blank lines, and one if lines is left out.
Tillcast cuts at the end of every document anyway, so a cut as the last block cuts a second time. Use cut between two receipts that you send as one document.
Barcodes, QR codes and images
Each of these is a line of its own, with align (left by default). They cannot stand next to text. To put a code beside a text, print them one under the other.
barcode.symbologyiscode128(the default),upc,ean(or JAN),code39,itf,codabar(or NW-7) orcode93.hriprints the data under the bars.module_widthis the width of the thinnest bar in dots, 2 to 4 (2 by default).heightis the height of the bars in dots, 24 to 240 (72 by default).- The data of a barcode is held to what the symbology takes, up to 128 characters, and refused if the renderer would print nothing for it.
upctakes 11 or 12 digits, or 7 or 8 digits that start with 0.eantakes 12 or 13 digits, or 7 or 8.itftakes an even number of digits.code39takes digits, capital letters, the space and- . $ / + %.codabartakes digits,- $ : / . +, and a letter from A to D at the start and at the end.code93andcode128take printable ASCII. qr.datais text of 1 to 2,048 characters, with line feeds if you like and no other control character.cellis the size of one square in dots, 3 to 8 (3 by default).levelis the error correction,l,m,qorh(lby default).image.datais the PNG file in base64, up to 200,000 characters. A monochrome PNG gives the best result. An image is never scaled, and an image over the limits is skipped with a warning. The limits are in Limits and refusals.
The text view shows nothing for a code or an image, so these have no text view.
Build a document from your data
Put the text from your own data into a block as it is. Tillcast writes the escapes for you.
TypeScript
Python
Pass the result as document of client.jobs.create. A name such as Tom | {Bar} --- ~ _ prints as it is. Give the function a return type, as above: a document that is built in a variable without a type is read as plain strings and dicts, and the type checker refuses it as document.
Errors in a document
A block that cannot be printed as it is said is 422 document_invalid. param is the path of the first problem, in the order of the document. The message holds the path and the names of fields and numbers, and never a piece of your text.
- A block that is not an object, or has no
type, or atypethat is not one of the nine, and a field the block does not have: for exampledocument[2].colour is not a field of a text block. - A value out of its range or of the wrong kind:
document[1].align must be one of left, center, right,document[4].columns[1] must be at most 96. - Something the paper cannot show: a rule in a ruled table at the top, at the bottom or next to another rule, a size that does not fit its column, a row with more cells than columns, barcode data that its symbology does not take, a control character in a text. Each names the path of the thing. Control characters are refused and not removed.
- Both
documentandreceiptline, or neither:422 document_invalid, withdocumentorreceiptlineinparam. - A document with no block, or one that prints nothing, such as blocks of only blank lines (
feed) or atextblock of nothing (""):422 document_empty. Atextblock of spaces, or of a no-break space, is a text: it is accepted (201) and prints a line that looks blank. Areceiptlineof only white space, a no-break space included, is422 document_empty. documentthat is not an array, orreceiptlinethat is not a string:400 parameter_invalid. This includes an object such as the earlier{"type": "receiptline", "content": "..."}. The message says where the text goes now.
Two things in a text are not exactly as typed. The document is normalized to NFC, so a letter and the combining mark after it become one letter with the accent. A combining mark at the start of a line has nothing to attach to, and is not printed.
Warnings
The renderer follows the ReceiptLine library, which is lenient and silent. A column that does not fit is narrowed, and a character the printer cannot print becomes ?, all without a word. Tillcast prints what the library would, and tells you where it fell back.
The job always has a warnings list, empty when the renderer had nothing to say. It is kept with the job, so a replay and every later read return the same list.
codeis stable and written in snake_case. Branch on it. A new code can be added, so treat one you do not know as a warning in general.lineandcolumncount from 1.columnisnullwhere the document was rewritten at that place. For a document of blocks they count the same receipt written in ReceiptLine, and not the blocks, so a warning does not name a block.messageis a fixed sentence for a person. It holds no part of your document, so it is safe to show and to log. Do not parse it.- A warning never changes what prints. A job has at most 21 warnings: the first 20, and
too_many_warningswhen there were more.
Most of the codes below cannot happen for blocks: a stray brace, an unknown property and an invalid escape are mistakes in ReceiptLine text that a block cannot make. The ones that can are about the paper and the printer: column_shrunk, column_dropped_overflow and character_wider_than_column (the widths of the columns against the width of the paper, which the blocks do not know), character_unmappable, and the ones about an image, a barcode and a QR code.
Limits and refusals
A document that prints nothing is 422 document_empty: no block, blocks of only blank lines or a text of nothing, or a receiptline of only white space. A text block of spaces or of a no-break space is not empty: it is accepted and prints a blank-looking line. See Errors.
The command property of ReceiptLine, which would send raw printer commands, is not accepted from anyone, and a block cannot make one. A receiptline text that uses {command:...} is 422 document_command_not_allowed, with the line and the column in the message. The same code refuses a text in which a hexadecimal escape would put a control character into the printed text.
Advanced: ReceiptLine text
receiptline takes the document as text in ReceiptLine, a second format that Tillcast supports next to blocks. It is the form for documents that were written for other ReceiptLine tools, such as the ReceiptLine demo and designer, and for software of yours that already writes the language. Everything a block can say, the text can say. The one thing the text has and a block has not is the command property of the language, which sends raw printer commands, and which Tillcast refuses. In text the characters of the language are yours to escape, and a mistake is a line that prints differently, with a warning at best. Blocks are the way to write a receipt.
Send the text in the field receiptline of the job, instead of document. In JSON a line break is \n. A plain line of ReceiptLine is centred, while a text block is on the left unless it says center.
Written out as lines, the document is this.
The first document of A first document looks like this in ReceiptLine, with a property line for the columns of the table and the marks of the language for bold and size. For blocks you never write it.
Lines, columns and alignment
- A line of plain text is centred.
- A property line such as
{width:*,9}prints nothing. It applies to the lines after it. This one gives them two columns: the first takes what is left (*) and the second is 9 characters wide. - A bar
|separates columns. How a text sits in its column depends on the spaces beside the bars. A space between the text and the bar on its right pushes it to the left, a space on its left pushes it to the right, and a space on both sides centres it. Soitem | priceputs the item on the left and the price on the right.
A cell that is too long wraps inside its column, by characters and not by words. \n starts a new line inside a cell.
Bold, underline, inverse and size
These characters are marks. A mark switches a style on, and the same mark switches it off again. A mark applies to the column it stands in, and a style left on ends with the column.
So Pay "now" or _later_ has a bold word and an underlined word. In ^Total | 7.60 the label is in double width and the amount is not, because the mark stays in its own column.
Rules and cuts
- A line made only of
-is a rule across the paper, however many dashes it has. - A line made only of
=cuts the paper at that place. Tillcast cuts at the end of every document anyway, so use=only to split one document into several slips.
Tables with borders
{border:line} draws the columns with lines. A - line inside the table draws a line between rows. Turn the border off with {border:none} (or {border:space}) on its own line when the table ends. Without it the renderer closes the table for you and reports rule_state_closed_at_end.
Do not end the document with an empty line while a table is open: the empty line becomes an empty row.
Barcodes and QR codes
A barcode or a QR code is a property line with the data in code and the type and size in option.
- Barcode types are
upc,ean(orjan),code39,itf,codabar(ornw7),code93andcode128. Forupcandeanthe check digit can be left out. - Add
hrito print the digits under the barcode. Without it only the bars are printed. A number from 2 to 4 is the width of a bar in dots and a number from 24 to 240 is the height. qrcodemakes a QR code. A number from 3 to 8 is the size of a cell in dots, andl,m,qorhis the error correction level.- Inside the
codevalue, write\;for a semicolon, and\{,\},\|and\\for a brace, a bar and a backslash. Any other backslash sequence is dropped together with its character. - Data that does not fit the type is
barcode_data_invalid, and a QR code that cannot hold its data prints nothing, see Warnings. Control characters in barcode data are removed on purpose, because left in they would be commands to the printer.
Images
{image:...} takes a PNG as base64. A monochrome PNG gives the best result. Tillcast sets limits and reports an image it skips with a warning:
- A PNG header is read before anything is unpacked. An image may be at most 2,048 dots wide, 4,096 high and 4,000,000 pixels, and all images in one document together at most 4,000,000 pixels.
- An image is never scaled. One wider than the paper prints at its own size (
image_wider_than_paper), and one wider than a Star StarPRNT printer can take, 1,024 dots, is skipped (image_too_wide_for_printer).
Your own text: escape it
This part is for receiptline text. In document the blocks do it for you, and there is nothing to escape.
Plain text is a document, but the characters of the language are special in it: |, {, }, ~, _, ", `, ^ and \, and a line made only of - or only of =. A name, an item or a note that you did not write can contain any of them, and then it changes the document. This document has a table number in braces and a code with underscores:
The first line is gone, because a stray brace drops the whole line, and the answer lists line_dropped_stray_brace. The second lost its underscores, which switched underlining on and off, with no warning at all. Written with escapes, the same text prints as it is.
Escape every string that is not yours before it goes into a document. The rule:
These helpers do exactly this. They are for a text column: put the result beside the bars of a row, never inside the value of a property such as code. For an empty text they return an empty string, and an empty cell at the start or end of a row is no cell at all, because a bar with nothing beside it at the edge of a row is the language’s optional edge bar. row writes ~ for an empty cell, so the row keeps its columns.
TypeScript
Python
A table of items is then built like this, and JSON.stringify or your JSON library writes the quotes, backslashes and line breaks of the string for you.
Show a receipt in your own page
To see a document without a printer, draw it in a web page. The npm package @tillcast/preview takes the same blocks and draws the receipt in the browser, with no call to Tillcast and no key. See Preview a receipt in your app.
What is not available yet
- Templates. A template language and stored templates (ready-made documents with places for your data) are in development and not available. A job has no
templateordatafield: a request that sends one is refused with400 parameter_unknown. Blocks are plain objects, so build the document in your code, with a loop over your own data. - Other kinds of document. HTML, Markdown and converted plain text are not built.
- A cash drawer option and an image converter. A PNG goes inside the document as base64.
- Printer commands inside a document. Not offered to anyone.