ZPL how-to
Templates in ZPL: store a format with ^DF, fill it with ^XF
ZPL can keep a label layout on the printer and fill in only the values each time: ^DF stores the layout with numbered fields, and ^XF recalls it with the data.
Store the format: ^DF and ^FN
Send this once. It prints nothing; it saves the layout on the printer as BIN.ZPL:
^XA
^DFE:BIN.ZPL^FS
^CF0,50
^FO40,40^FN1^FS
^BY2^FO40,120^BCN,60,N,N^FN2^FS
^XZ^DFE:BIN.ZPLgoes straight after^XA. Everything up to^XZis saved, not printed.^FN1and^FN2stand where^FDwould: numbered holes for the data.E:is the printer's flash memory, which keeps the format when the printer is switched off.R:, the default, is its RAM, which does not.
Fill it: ^XF
Each label then needs only the format's name and the values. Two labels from the one format:
^XA
^XFE:BIN.ZPL
^FN1^FDRack 7, bay 1^FS
^FN2^FDR07-B01^FS
^XZ
^XA
^XFE:BIN.ZPL
^FN1^FDRack 7, bay 2^FS
^FN2^FDR07-B02^FS
^XZIn Labelary, each ^XA … ^XZ printed one label with the text and the barcode where the stored format put them.
It saves sending the layout each time, not printing time: Zebra's reference notes the printer still formats the stored text at print time.
What goes wrong
- A field you leave out prints nothing. Recalled without
^FN2, the label above printed its text and no barcode, with no error:zpl^XA ^XFE:BIN.ZPL ^FN1^FDRack 7, bay 1^FS ^XZ - A format that is not on the printer prints the values in the corner. In Labelary, with the name mistyped as
BINS.ZPL, both values printed at 0,0, on top of each other, in the small default font. On a printer, a font or label home left by an earlier label may change where and how they print. Expect the same from a format stored inR:once the printer has been switched off.zpl^XA ^XFE:BINS.ZPL ^FN1^FDRack 7, bay 1^FS ^FN2^FDR07-B01^FS ^XZ - Names longer than eight characters. Zebra's reference allows 16 characters for
^DFbut 8 for^XF. Labelary accepted a longer name, but keep names to eight characters for a real printer. - Default values in the stored format. Leave
^FDout of the stored fields. In Labelary, a stored field with its own^FDkept printing it, and the recalled value printed as a separate field at 0,0. - The same number twice. Two stored fields with the same
^FNboth print the one value, which is useful for a value that appears twice on a label. - A
^or~in the data. Recalled data is read the same way as any other field data, so a^in it cuts the field short. Use^FHin the recall, as in^FN1^FH_^FD2_5E10^FS, which printed "2^10". Printing ^, ~ and _ in ZPL explains the escapes.
The same idea with zeepler
Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.
1{2 "config": {3 "size": "4x2"4 },5 "data": {6 "location": "Rack 7, bay 1",7 "code": "R07-B01"8 },9 "templates": [10 {11 "type": "Text",12 "dataPath": "location",13 "coords": [40, 40],14 "font": "0,50"15 },16 {17 "type": "BarCode",18 "dataPath": "code",19 "coords": [40, 120]20 }21 ]22}And the ZPL that comes back, ready to send to the printer:
^XA^MCY^XZ
^XA
^SZ2
^MMT
^MNY
^LL406
^PW812
^LH0,0
^CF0,50^FO40,40^FDRack 7, bay 1^FS
^BY2,2,59^FO40,120^BCN,,N,N,N,A^FDR07-B01^FS
^XZzeepler does not store formats on the printer. The template is part of each request instead: each element names a dataPath in data, the way a stored field has an ^FN, and the response is the complete label, ready for a printer that has never seen it. Keep the templates array in your code, and send new data for each label.
- A
dataPaththat is not indatais refused with a400naming the element, instead of printing a blank field. - There is nothing stored to lose when the printer is switched off or replaced, and nothing to send to each printer first.
- zeepler escapes
^,~and_in the values for you. - The cost: every label sends the whole layout, which a stored format would save.
Sending it
- Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
- A successful call answers
200with the ZPL as plain text. A request the API cannot turn into a label answers400with every problem listed by field, and is not billed. - Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.
The API reference has every field and status code.
Before you go live
- Text does not wrap. A value longer than the space you left runs off the edge of the label, so set
maxLengthon any field whose length you do not control. - Coordinates are in dots from the top-left corner. Print one label, measure it, and adjust: there is no preview.
- Scan every barcode and QR code on a printed label before relying on it.
Related guides
- QR code size in ZPL: How ^BQ magnification sets the size of a QR code, and how to work out the size in dots.
- Printing ^, ~ and _ in ZPL: Why a caret or tilde in your data cuts the field short, and how ^FH prints them.
- Font size in ZPL: Setting text height with ^A and ^CF, converting points to dots, and why ^CF carries over.
- Send ZPL to a Zebra printer from C#: Send ZPL from .NET to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Code 128 barcodes in ZPL: Set a Code 128 barcode's width and height with ^BY and ^BC, work out its width in dots, and pick subsets A, B and C.
- Accented characters in ZPL (^CI28): Print é, ç, ô and € with ^CI28, switch the printer back with ^CI0, and what to do on older firmware.
- Send ZPL to a Zebra printer from Python: Send ZPL from Python to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Change a barcode to a QR code in ZPL: Swap ^BC for ^BQ, start the field data with QA, so the first characters scan, and reset the ^BY left over from the barcode.
- Send ZPL to a Zebra printer from Node.js: Send ZPL from Node.js to a network printer on port 9100 or to a USB printer through a Windows printer share, and print from a web page through your server.
- Label size and origin in ZPL (^PW, ^LL, ^LH): Set the label size in dots with ^PW and ^LL, move 0,0 with ^LH, and stop the last label's settings moving this one.
- Several labels in one ZPL job: Send several different labels in one job, stop each one inheriting the last one's font and barcode settings, and number a run with ^SN and ^PQ.
- EAN-13 and Code 93 barcodes in ZPL: Print EAN-13 with ^BE and Code 93 with ^BA, and the data each one changes: a replaced check digit, and characters Code 93 cannot hold.
- Print copies of a ZPL label with ^PQ: Print several copies of one label with ^PQ, why ^PQ after ^XZ prints only one, and each serial number twice with ^SN.
- Center text in ZPL with ^FB: Center text of any length with ^FB, why centered text sits a little left, and text too long for the block.
- Center or right-align a barcode in ZPL: Right-align a barcode with the third value of ^FO, center one by working out its width, and why ^FB does not move it.
- Wrap text and new lines in ZPL: Wrap long text with ^FB, start a new line with \&, and stop ^FB writing over its last line or cutting text off.
- Rotate text and barcodes in ZPL: Turn text and barcodes with N, R, I and B, where ^FO and ^FT put a turned field, ^FW and ^POI, and why both stay set.
Help with an integration
Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.