Asset Label Designer Design

Asset label designer - design (#229)

Status: slices 1 and 2 are built (4.8.0) - label designs, sizes, fonts, the exact-size PDF, and the designer; barcodes (slice 3) are next. Two things in section 2 were left out of the designer for now: a Print preview button (the label is already drawn as it prints, with a real asset) and a label background. For users: QR asset labels - Label designs and The label designer; for developers: QR asset labels - Developer Guide §6b and §6c. This page sets out how I plan to build issue #229, raised by @zemega. It is written before the code so the approach can be checked first. The open questions are in section 11.

The request, from the issue:

"The rigid layouts do not align properly with continuous-tape label makers, such as Brother TZe tape printers ... Logos cannot be displayed prominently, which is a key requirement for internal stakeholder and management satisfaction."

In plain words

Today every asset label has the same shape: the QR code, the asset tag and a list of fields, with the logo squeezed into the middle of the QR. It prints on four sizes of A4 sheet and nothing else.

This design adds a label designer, built to feel like the Report Pack designer - a ribbon, a toolbox, the label in the middle with rulers, and a properties pane - where you place things anywhere on the label, the way you place shapes in PowerPoint:

1. Any size of label. A 24 mm Brother tape, a 62 mm Dymo label, the A4 sheets you use today, or your own size.
2. Anything, anywhere. Your logo at any size, the QR code, any asset field, your own text, lines and boxes. Drag them, resize them, line them up.
3. Printed at exactly its size. A PDF the size of one label, one label per page for a tape printer, or laid out on a sheet - so the printer's driver gets exactly what it expects.
4. More than one design. "Laptop tape label", "Server sheet label" - each company keeps its own, with one as the default.

Nothing changes until you choose to. Today's layout becomes the first design, so labels print as they do now until somebody opens the designer.

---

1. What labels do today

From QR asset labels and its developer guide:

	Today
Layout	One fixed shape: an optional header, the QR, the asset tag, an ordered list of fields, an optional footer. Built with CSS; font sizes worked out from the label's height
Configured	Assets → Settings → Asset labels & QR (Cap::ASSETS_LABELS): which fields and in what order, header, footer, field names on or off, and a logo. Six settings, per company (tenant_settings, falling back to system_settings)
Fields	Asset tag (always, first), hostname, serial, manufacturer, model, company, location, type, and custom fields as cf_<key>
Logo	In the middle of the QR, at about 22%, which switches the code to error correction H. Small by design
Codes	QR only, drawn in the browser by the bundled qrcode.min.js. It encodes /a/<qr_token>
Printing	Four A4 sheets (65, 40, 24 or 12 per sheet), through the browser's print dialog. No tape printers, no other sizes, no PDF
Also	A CSV for a professional print house

When labels were last reviewed (PR #164), a full designer was set aside: "physical dimensions, browser print scaling and long values make a designer a project of its own. Nobody has asked for one." This design takes each of those three on directly: exact physical sizes (section 4), a PDF instead of browser printing (section 6), and rules for long values (section 3).

2. The designer

It is built to feel like the Report Pack designer, from the same patterns (Report Packs internals 1), so the two read as one product:

• A fixed application frame: title bar (name, Saved / Unsaved, undo, redo, Save, Print preview), a ribbon, the toolbox on the left, the label in the middle, the properties pane on the right, a status bar. The page never scrolls; the panes do.
• The ribbon: Home (clipboard, undo, delete), Insert (text, field, QR code, logo or picture, line, box - and barcode, section 9), Arrange (align left / centre / right / top / middle / bottom, distribute, bring forward, send back, rotate), Label (size and stock, background, preview with an asset).
• The label is drawn large on a pasteboard, with rulers in millimetres, zoom (Ctrl+wheel, Fit), a grid you can switch on, and snapping to the grid, the label's edges and centre lines, and other items' edges and centres - with the pink guide lines PowerPoint shows while you drag.
• Selection with handles to resize, Shift to keep proportions, marquee select, Shift-click to add, arrow keys to nudge (Shift for larger steps), Ctrl+D duplicate, Ctrl+C / V across designs, Delete, right-click menu. Undo and redo for everything.
• The properties pane shows exactly what the selected item can do - position and size in mm, font, size, bold, alignment, how long text is handled, the field it shows, the QR's options.
• Preview with a real asset: pick an asset (or "the longest names") and the label shows its real values, so you see whether a long model name fits before printing 200 of them.

What is different from Report Packs: a report flows down pages in rows of blocks; a label is small and every item has an exact position. So the canvas works like the free placement in the Process and Network Mappers, not like Report Packs' rows.

3. What can go on a label

Every item has a position and size in millimetres (to 0.1 mm), and a rotation of 0, 90, 180 or 270 degrees - tape labels often want a column of text turned on its side.

Item	What it shows	Options
Text	Your own words - "Property of ZHL Group", "IT helpdesk ext. 4000"	Font, size, bold / italic, alignment, colour (black or white on a filled box)
Field	One asset value: tag, hostname, serial, manufacturer, model, type, company, location, holder, a custom field	Its caption on or off ("Serial: ..."), plus Text's options. Text can also hold fields inline: S/N {serial}
QR code	The asset's code - the same /a/<qr_token> as today, so labels already printed keep working	Logo in the middle on or off (today's look), quiet zone
Logo / picture	The company logo, or any picture uploaded to the design	Keep proportions; black-and-white conversion for thermal printers
Line, Box	Separators and frames	Thickness, filled or not
Barcode	A 1D barcode of the tag or serial, for hand scanners that read only barcodes	Section 9 - a later slice

Long values - the third worry from PR #164. A field's box is a fixed size, so each field says what happens when its value does not fit: shrink to fit (down to a smallest size you set, default), wrap onto more lines, or cut off with "...". Nothing is ever printed outside its box or over another item. The preview's "longest names" asset shows the worst case.

4. Label sizes and stock

A design says what one label looks like. The stock says how labels come off the printer. A design is drawn for one label size; the stock is chosen when the design is made, and can be changed.

Stock	What it means	Examples (presets)
Tape or roll	One label per page, the page exactly the label's size	Brother TZe 12, 18, 24, 36 mm; Brother DK 29 x 90, 62 x 29; Dymo 89 x 36, 54 x 25; your own width and length
Sheet	Labels laid out in rows and columns on a page, with margins and gaps	Today's four A4 sheets, common Avery / Herma sheets, your own

A tape label's length is part of the design - a 24 mm tape can be 50 mm or 90 mm long. For sheets, a printer offset (a millimetre or two left / down) can be saved, because "check the alignment on plain paper first" is the advice today and an offset is how you act on it.

5. Designs: stored, shared, chosen

A new table, asset_label_designs:

Column
id, name	"Laptop tape label"
tenant_id	The company it belongs to; NULL = every company (only somebody who reaches every company can make one)
stock_json	The stock: tape (width, length) or sheet (page, rows, columns, pitch, margins, offset)
design_json	The items, as one JSON document - like Report Packs' design, checked and cleaned by the server on every save
is_default	The design Print label uses unless you pick another; one per company
version, updated_by, updated_datetime	Saving uses the version, so two people editing one design cannot silently overwrite each other (Report Packs' 409 rule)

Uploaded pictures are stored with the existing upload rules (uploadStoreFile(), images only, size-limited), as the logo is today.

Who can do what. Designing labels stays under the existing Asset labels permission (Cap::ASSETS_LABELS) - it is the same job. Printing stays with whoever can print labels today.

Printing a label. Print label and the batch Print labels use the company's default design, with a drop-down to pick another. The CSV for a print house is unchanged.

6. Printing: a PDF at the label's exact size

Browser printing is what makes custom sizes unreliable: the browser adds margins, scales to fit, and picks the paper itself. A tape printer's driver expects a page exactly the size of the label. So printing becomes a PDF, made in the browser by jsPDF (already bundled for Report Packs), at the stock's exact size:

• Tape: one page per label, each page the label's size. Printed through the label printer's own driver at actual size.
• Sheet: pages of the sheet's size, labels placed at the sheet's pitch and offset.

The same drawing code draws the designer's canvas and the PDF, from one list of positioned items in millimetres - the Report Packs approach, which is why its screen and its PDF match. Nothing is sent outside the install: the QR codes and the PDF are made in the browser, as the codes are today.

Every character prints (decided)

Report Packs use the three standard PDF fonts, which hold drawings only for Western European characters - a Chinese or Arabic name prints as "?". On a label every character must print (decided on review). Two things are needed for that, and the design does both:

• A font that has the characters. Unicode numbers every character; a font holds drawings for some of them, and no single font holds them all. FreeITSM bundles one free font, Noto Sans (Latin, Cyrillic, Greek, Vietnamese), and you can upload your own (section 6a) - one for Chinese, Arabic or Hindi names, or your company's brand font.
• Something that lays the text out correctly. Arabic letters join; Hindi, Bengali, Tamil and the other Indic scripts combine letters. jsPDF does not do that; the browser does. So text is drawn by the browser, exactly as the designer shows it, and placed in the PDF as an image at 600 dots per inch - twice what most label printers print. The QR code, lines and boxes stay vector. What prints is exactly what the designer showed, in any language and any font.

Each text item can also name a fallback font: a character the chosen font lacks is drawn from the fallback rather than missed, so a brand font for English and a Noto font for Chinese can share one label.

Black-only printers (4.9.0, decided)

The first real print (#229, a Brother D610BT on silver tape, the PDF printed from Firefox) showed the QR code sharp, the values readable, the field captions unreadable and the logo speckled. Cause: the captions were drawn at 55% of the field size in grey #444444, and the logo was dark grey. A thermal printer has no grey, so its driver halftones it into dots.

• Captions, universal: the item's own colour, 70% of the value's size, never below 5 pt (or the value's size, if smaller). linesFor() in render.js.
• mono, per design, in design_json: text, lines and boxes are drawn black, and the logo goes through monoImage() - enlarged to 1200 px, laid on white, black where darker than 160/255, clear elsewhere. Preview and PDF both honour it. Unset follows the stock (assetLabelMono() in PHP, monoFor() in JS): tape and roll on, sheets off - so every design made before 4.9.0 on a tape got the fix without anyone touching it. The settings modal only sends mono once the box has been touched; save_items keeps whatever was there.
• Considered and dropped: removing the soft edges from the 600 dpi text. The PDF is resampled before the printer sees it - Firefox's pdf.js prints at 150 dpi, then the driver resamples again - so grey edges come back whatever the PDF holds. The real lever there is the viewer: the user wiki says to print from a desktop reader or Chrome.
• Asked for, not built: one long strip of labels for chain printing, so a printer like the D610BT does not waste its fixed margin on every label. Waiting on how the reporter's driver handles a long custom page.

6a. Uploading fonts (decided)

Under the designer's Fonts list, somebody with the Asset labels permission uploads a font file - .ttf, .otf, .woff or .woff2, up to 20 MB (a full Chinese font is about 15). It is checked to be a real font (its header and tables are read, and anything else is refused), stored with the existing upload rules, and offered in every design for that company. The designer and the PDF both load it with the browser's own font loading, so it looks identical in both.

• Licences. Some commercial fonts may not be embedded in documents. The upload screen says so, and the person uploading confirms they may use it. Noto Sans is under the SIL Open Font License, which allows this.
• Deleting a font in use by a design is refused, naming the designs, so no label silently changes its look.

7. Upgrading: nothing changes until you choose

• Database Verification creates the table. The first time labels are printed or the designer is opened, each company's current settings - fields, order, header, footer, field names, logo - become a design called "Standard" on today's sheet sizes, drawn to look as today's label does. It is that company's default.
• The six settings stay readable for one release, then the settings tab points to the designer (decided). Nothing the tab does today is lost - each part has its place:

Today's tab	In the designer
Which fields, and their order	Field items, placed anywhere
Custom fields (cf_<key>)	The same, in the field list
Header and footer	Text items
Field names on or off	A caption option on each field
Logo upload (branding rules, 2 MB)	The logo item, same upload rules
Logo in the middle of the QR, error correction H	An option on the QR item, with the same rule
Asset tag always printed; "no tag" when blank	Kept in the Standard design, same wording
Live preview	Preview with a real asset
Per company (tenant_settings, then system_settings)	Designs per company, and designs for every company
The four A4 sheets	Sheet presets, same pitches and QR sizes
CSV for a print house	Unchanged, on the print screen

• The scan side does not change at all: the QR encodes the same address, and every label already on a laptop keeps working.

8. Ready-made designs

So nobody starts from a blank label:

1. Standard - today's layout (made from your settings, section 7).
2. Tape, logo left - the layout in the issue: logo on the left, title and three fields in the middle, QR on the right, on 24 mm tape.
3. Tape, small - QR and tag only, for 12 mm tape and small kit.
4. Sheet, large - for 63.5 x 72 mm labels: logo across the top, QR, several fields.

9. Slices

Each slice is useful on its own, and comes with its tests and write-up.

1. Designs, sizes and printing - the table, the stock presets (tape and sheet), the PDF printer with browser-drawn text, Noto Sans and uploaded fonts, today's layout as "Standard", the ready-made designs including logo left, QR right on 24 mm tape, and the design picker on Print label. This alone answers the issue's minimum request (the logo separate from the QR, prominent), and gets tape printers working.
2. The designer - the ribbon, canvas, rulers, snapping and guides, properties, undo, preview with a real asset, as section 2 describes.
3. More to place - 1D barcodes (Code 128, which every hand scanner reads; drawn by a small generator written for FreeITSM, as nothing in the install draws barcodes yet), and Data Matrix if anybody asks for it.

10. Deliberately out of scope

• Printing straight to a label printer over the network (Brother's and Zebra's own languages, ZPL / ESC-P). The PDF goes through the printer's normal driver, which every label printer has. A direct route can follow if the PDF is not enough.
• A design per asset type chosen automatically. You pick the design when printing; a default per type can come later.
• Editing the QR's contents. It stays the asset's own address, so a label can never point somewhere else.

11. Questions

For @zemega:

1. How do you print to the Brother? From a PDF through the Windows / macOS Brother driver (my assumption), or through P-touch Editor, or something else? And which models and tape widths?
2. Do you need a 1D barcode on the label, or is the QR enough? (Your settings screenshot had 1D Barcode unticked.)
3. Rotation: on your 24 mm tape, is the label read along the tape (as in your screenshot), or do you also print labels turned across it?

Decided on review (2 November 2026):

4. Fonts: every character must print. A free Unicode font is bundled, fonts can be uploaded, and text is laid out by the browser so every script is drawn correctly (section 6, 6a).
5. The old settings tab points to the designer after one release, and nothing it does is lost (section 7).

Related pages

• QR asset labels and its developer guide
• Report Packs and the designer's internals - the look and feel this follows
• Asset reconciliation, tags and labels - PR #164 review - where a designer was first discussed