Product Labels
A label template (Administration › Šablony, type štítek) prints labels for stock items: the name, the price, codes and a barcode, one label per page on a roll printer (Zebra) or several on an A4 sheet. It is a Twig text template rendered to HTML and then to a PDF at the template's size.
Variables
| Variable | Type | Description |
|---|---|---|
itemLabels | PrintedLabel[] | One label object per printed item, with how many copies (quantity) |
groupedProductLabels | PrintedLabel[] | One per product, the copies of its items summed |
sheet | LabelSheet | What the labels print on: the page's width and height in mm, the row and column an A4 sheet starts at, the printerType |
shop | Shop | The shop, as in other templates: shop.name, shop.url, shop.phone, … |
repository | The storefront's repositories, e.g. a product attribute: repository.attribute.findOneBy({id: 4}) |
A template prints each copy itself, e.g. {% for copy in 1..label.quantity %}…{% endfor %}. What a label object holds (name, variant, codes, barcode content, price, QR code) is in PrintedLabel. The price is there only when the shop prints prices on labels (its setting Typ ceny na štítky); print it with {{ label.price.current|price }}.
Barcodes and QR codes
Write a barcode as a tag; it becomes an image before the PDF is made:
| Tag | Code |
|---|---|
<img-code128 src="…" width="1" height="30"> | Code 128 (any text) |
<img-ean13 src="…" width="1" height="30"> | EAN-13 (13 digits) |
<img-codeI25 src="…" width="1" height="30"> | Interleaved 2 of 5 (digits) |
<img-qr src="https://…" width="80"> | QR code (width in px) |
width is the width of the narrowest bar (one module) in px (default 2), height the bars' height in px (default 30). The -png forms (<img-code128-png>, …) make a PNG instead of an SVG. A value the code cannot hold gives an empty image, not an error.
A barcode's width follows what it encodes; CSS sets only its height, and with it the bars' width. The image keeps its proportions, so a module is as wide as the CSS height divided by the tag's height: height="30" with height: 7.5mm makes it 0.25 mm, exactly two dots of a 203 dpi label printer, the narrowest it prints cleanly; height: 11.25mm makes it three dots (0.375 mm), for a printer or a reader that fails on two. A printer draws whole dots: a module between them (height: 8mm is 2.1 dots) prints two or three dots wide by where it falls, and under two dots a bar and its gap run together. For a lower barcode lower the tag's height with the CSS (height="24" and height: 6mm). Code 128 takes 11 modules per character plus 35, so at 0.25 mm 8 characters are about 31 mm and 12 about 42 mm; EAN-13 is always 95 modules, about 24 mm. A reader also needs some 3 mm of white on each side. max-width: 100% keeps a longer code inside the label by squeezing its bars, and the preview still looks fine while the printed code no longer scans. So when a code does not fit at its own width, give it the room, never a narrower image: the label's full width, the code turned along the label's longer side (transform: rotate(90deg)), a shorter value (the EAN instead of a long product code), or a QR code, which holds the same text in a square.
A QR code to the product is label.shortUrl, never the product's own URL: https://<shop>/_/ir/<item id>/<hash>, which redirects to the product's current address. It stays valid when the product is renamed or moves, and it is short, so the code has fewer modules and scans from a small label. <img-qr src="{{ label.shortUrl|e }}" width="80">, or the same code as a ready image: <img src="{{ label.qrDataUri({size: 100}) }}">.
Page size
The page is the template's width and height in mm, without margins. One label per page: make each label fill the page (html, body { height: 100% } and the label height: 100%; 100vh is not the page's height in the PDF) and break after it (break-after: page, except the last). An A4 sheet: lay out the grid yourself and start at sheet.row and sheet.column. The size is sheet.width × sheet.height (mm) when a layout needs it in numbers.
What a label may use
In the label studio a label renders in a restricted environment, and a text that renders there renders the same when printed. Before a render and before a save the studio checks the text as written, every branch of it, not only the one that renders:
- It reads only the variables above (
itemLabels,groupedProductLabels,sheet,shop,repository; the olderrada,sloupec,HOST) and names it sets itself (set,for, a macro's arguments). Notiterator, not_contextor_self(a template's own macros are called as_self.name(…), withoutimport), even behindis definedor??: printing has more in scope than the studio, and a name the studio lacks would read it only when printed. - An attribute is read by its name (
label.code,label['code']), never a computed one, and none starting with__. - Twig's own tags, filters and functions work as everywhere (
include,embedandsourcehave no other templates to load). Of the shop's own filters every one butndump,gravatarandsetAnalyticsName; of its own functions onlyQR,isPracovniDen,pristiPracovniDenandrand, also behind an{% if %}that is never true. No{% cache %}. - Objects' methods and properties as in other templates (no static methods). Output is not escaped automatically: escape product texts with
|e. An attribute that does not exist is an error with its line (printing would print nothing for it): test an optional one withis defined, or give it a default with??.
What shops ask for
| Ask | How |
|---|---|
| QR code for the customer | label.shortUrl (above) |
| The barcode does not scan, or is too wide for the label | Its width is its content's (above): never narrow it with width or max-width in CSS. Make room, rotate it, encode a shorter value, or print a QR code. One that has its width and still does not scan: modules of whole dots, three instead of two (height: 11.25mm at height="30") |
| White text on a dark field (a size in a black box) | the field's background with print-color-adjust: exact; -webkit-print-color-adjust: exact; on the same element: without them the PDF leaves a background out, and the light text is lost on the white paper |
| EAN as a barcode | <img-ean13 src="{{ label.item.code('ean')|e }}" width="1" height="30"> when label.item.code('ean') is set; an item without one prints no code |
| Price before and after the discount | label.price.beforeDiscount (null without a discount) struck through, then label.price.current: {% if label.price.beforeDiscount %}<s>{{ label.price.beforeDiscount|price }}</s> {% endif %}{{ label.price.current|price }}; label.price.discountPercent is the discount in % |
| Unit price (per kg, per l) | label.price.current.perUnit (null when the product has none): {{ label.price.current.perUnit.formatted }} |
| Unit of measure | label.product.unit.name (label.product.unit may be null) |
| A parameter's value | the product's attributes by name: {% for a in label.product.attributes %}{% if a.name == 'Materiál' %}{{ a.values|map(v => v.name)|join(', ')|e }}{% endif %}{% endfor %}; a value may have a unit |
| Bold, italic | CSS (font-weight: bold, font-style: italic) on the part |
| A symbol in a corner, to tell label types apart | a positioned element with a CSS shape or a character (● ▲ ■) at the template's corner: position: absolute in a label with position: relative. One per template, or by the product's flags (label.product.flagPromo, flagNew, …) or its labels (label.product.labels) |
A label is printed small: check each of these on the test items, at the real size.
Example
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
html, body { height: 100%; }
body { font-family: Arial, Helvetica, sans-serif; }
.label { height: 100%; padding: 1.5mm 2mm; display: flex; flex-direction: column; justify-content: space-between; break-after: page; }
.label:last-child { break-after: auto; }
.barcode img { height: 7.5mm; max-width: 100%; }
</style>
{% for label in itemLabels %}
{% for copy in 1..label.quantity %}
<div class="label">
<strong>{{ label.productName|e }}</strong>
{% if label.variantName is not empty %}<div>{{ label.variantName|e }}</div>{% endif %}
{% if label.price %}<div>{{ label.price.current|price }}</div>{% endif %}
<div class="barcode"><img-code128 src="{{ label.barcodeContent|e }}" width="1" height="30"></div>
<small>{{ label.visibleCode|e }}</small>
</div>
{% endfor %}
{% endfor %}