Návod k editaci JSON šablon pro štítky (labels)

Obsah

1. Úvod
2. Struktura JSON šablony
3. Layout — rozložení štítků
4. Data — zdroj dat
5. Calibration — kalibrace tiskárny
6. Content — obsah štítku
7. Textový blok
8. Čárový kód
9. Čára a obdélník 9a. Obrázek 9b. QR kód 9c. Rotace 9d. ShrinkFont — automatické zmenšení fontu
10. Placeholdery a formáty
11. Příklady kompletních šablon
12. Konverze z FoxPro LBX
13. FoxPro použití
14. Řešení problémů

1. Úvod

Label renderer generuje PDF se štítky ve dvou režimech:

• Sheet — arch s mřížkou štítků (typ Avery, A4 papír, 3×8 štítků apod.)
• Roll — pás pro termotiskárnu (každý štítek = 1 PDF stránka s přesnými rozměry)

Obsah štítku se definuje jako pole bloků s absolutní pozicí (v mm) uvnitř jednoho štítku. Podporované bloky: text, čárový kód, čára, obdélník, obrázek, QR kód.

⚠️ HTML = náhled, PDF = tisk. HTML preview slouží k rychlé kontrole rozložení při editaci šablony ve VS Code. Pro tisk vždy generujte PDF — HTML preview má odchylky v rozměrech způsobené scalingem prohlížeče a bitmapovými čárovými kódy. V HTML náhledu se zobrazuje vodoznak „NÁHLED — PRO TISK POUŽIJTE PDF".

Důležité: Všechny rozměry a pozice v JSON jsou v milimetrech. Počátek (0,0) je levý horní roh štítku.

2. Struktura JSON šablony

{
  "renderer": "label",
  "layout": { ... },
  "data": { ... },
  "calibration": { ... },
  "defaultFont": "Segoe UI",
  "content": [ ... ]
}

3. Layout — rozložení štítků

Sheet mód (arch)

{
  "layout": {
    "type": "sheet",
    "pageSize": "A4",
    "columns": 3,
    "rows": 8,
    "labelWidth": 63.5,
    "labelHeight": 33.9,
    "marginTop": 13,
    "marginLeft": 5,
    "gapX": 2.5,
    "gapY": 0,
    "startPosition": 1
  }
}

Roll mód (pás)

{
  "layout": {
    "type": "roll",
    "labelWidth": 100,
    "labelHeight": 80
  }
}

U pásu stačí zadat šířku a výšku. Každý štítek je samostatná PDF stránka — tiskárna kalibruje automaticky.

4. Data — zdroj dat

{
  "data": {
    "element": "zbozi",
    "copiesField": "pocet_stitku",
    "where": "typ=A"
  }
}

XML struktura dat

<root>
  <zbozi>
    <row nazev="Jablka" kod="JAB001" ean="8590123456789" cena="45.90" />
    <row nazev="Hrušky" kod="HRU002" ean="8590123456790" cena="62.50" />
  </zbozi>
</root>

5. Calibration — kalibrace tiskárny

{
  "calibration": {
    "xOffset": 0.5,
    "yOffset": -0.3,
    "showBorders": true
  }
}

• xOffset / yOffset — posun celého archu v mm. Každá tiskárna má drobný posun — tímto se kompenzuje bez změny souřadnic prvků.
• showBorders — debug mód:
  • 🔴 Červené tenké čáry kolem každého bloku
  • 🔵 Modré přerušované čáry kolem štítků
  • ⚪ Šedé okraje stránky

Tip: Zapněte showBorders: true, vytiskněte jeden arch a změřte odchylky. Pak nastavte xOffset/yOffset a vypněte debug.

Všechny tři hodnoty mohou být řízeny z XML dat přes placeholdery:

{
  "calibration": {
    "xOffset": "{parametr.cal_x}",
    "yOffset": "{parametr.cal_y}",
    "showBorders": "{parametr.debug}"
  }
}

6. Content — obsah štítku

{
  "content": [
    { "type": "rect", "x": 0, "y": 0, "width": 63.5, "height": 33.9, "fill": "#f8f8f8" },
    { "type": "text", "x": 2, "y": 2, "width": 59, "height": 8, "field": "nazev" },
    { "type": "barcode", "x": 5, "y": 14, "width": 53, "height": 10, "field": "ean" }
  ]
}

Pořadí bloků v poli = pořadí vykreslování (z-index). Obdélník s pozadím dejte na začátek (pod text), text na konec (navrch).

Všechny souřadnice jsou relativní k levému hornímu rohu štítku, ne k archu.

7. Textový blok

{
  "type": "text",
  "x": 2, "y": 1.5, "width": 59, "height": 7,
  "field": "nazev",
  "fontSize": 9,
  "style": "bold",
  "align": "center",
  "maxLines": 2
}

8. Čárový kód

{
  "type": "barcode",
  "x": 5, "y": 14, "width": 53, "height": 10,
  "field": "ean",
  "format": "EAN13",
  "showText": true,
  "quietZone": 2,
  "visibleWhen": "ean"
}

Důležité: Čárové kódy jsou vektorové (ne bitmapové) — ostré čáry na jakémkoli DPI. Pokud je pole prázdné, kód se automaticky přeskočí.

EAN-13 — automatické doplnění

EAN-13 vyžaduje 12 nebo 13 číslic. Kratší řetězec se automaticky doplní zleva nulami.

EAN-13 a EAN-8 mají automaticky delší guard bars (start, center, end čáry) — standardní vzhled.

Dynamický formát čárového kódu

Pokud data obsahují mix EAN-13 a Code128, formát lze řídit podmínkou:

{
  "type": "barcode",
  "field": "bar_kod",
  "format": "{ean=true?EAN13:Code128}",
  "showText": true,
  "visibleWhen": "bar_kod"
}

Ternární výraz {pole=hodnota?ano:ne} se vyhodnotí per řádek z XML dat.

9. Čára a obdélník

Čára

{ "type": "line", "x": 2, "y": 25, "width": 59, "style": "thin" }

• width > 0, height = 0 → horizontální čára
• width = 0, height > 0 → vertikální čára
• Styly: "thin" (0.3pt), "normal" (0.5pt), "thick" (1pt), "dashed"

Obdélník

{ "type": "rect", "x": 0, "y": 0, "width": 63.5, "height": 33.9, "border": "#000", "fill": "#f0f0f0", "rounded": 1 }

• border — barva rámečku (bez border = žádný rámeček)
• fill — barva výplně
• rounded — zaoblení rohů v mm

9a. Obrázek

{ "type": "image", "x": 50, "y": 2, "width": 12, "height": 12, "file": "{parametr.logo}", "fit": "contain" }

• Obrázek se vždy centruje v bounding boxu
• Podporované formáty: PNG, JPEG, GIF
• V PDF se obrázky cacheují (každý soubor se načte jen jednou)
• V HTML preview se konvertují na inline base64

Tip: contain je ideální pro loga (zachová proporce). stretch použijte pokud chcete vyplnit celý box (např. pozadí).

9b. QR kód

{ "type": "qr", "x": 70, "y": 55, "width": 20, "height": 20,
  "template": "https://example.com/{kod}", "quietZone": 1 }

• QR kód je v PDF vektorový (stejný princip jako čárový kód — ostré hrany na jakémkoli DPI)
• Error Correction Level M (15% opravitelnost)
• QR box by měl být čtvercový (width = height). Pokud není, QR se vykreslí do menšího rozměru a centruje.
• V HTML preview se zobrazí jako bitmap ve zvýšeném rozlišení

9c. Rotace

Bloky text, barcode, image a qr lze otočit o 90°, 180° nebo 270°:

{ "type": "text", "x": 55, "y": 14, "width": 5, "height": 20,
  "field": "popis", "fontSize": 7, "rotate": 90 }

Jak fungují souřadnice

Souřadnice x, y, width, height v JSON vždy popisují výsledný box — tak, jak ho vidíte na vytištěném štítku. Rotace se provádí kolem středu boxu. Interně se pro 90°/270° automaticky prohodí šířka a výška.

Příklad: x=55, y=5, width=5, height=25, rotate=90

Na štítku vidíte:             Interně (před rotací):
┌─────┐                      ┌─────────────────────────┐
│  T  │  5×25mm              │  T E X T                │  25×5mm
│  E  │  úzký box            │                         │  široký box
│  X  │  text rotovaný       └─────────────────────────┘  rotovaný CSS/PdfSharp
│  T  │  90° CW                                           kolem středu
└─────┘

Důležité: Bloky line a rect rotaci nepodporují. Pro otočenou čáru použijte vertikální/horizontální variantu (nastavením width/height).

Rotace funguje i na čárovém kódu — pro vertikální barcode na boku štítku:

{ "type": "barcode", "x": 55, "y": 2, "width": 5, "height": 30,
  "field": "ean", "format": "EAN13", "showText": true, "rotate": 90 }

9d. ShrinkFont — automatické zmenšení fontu

Pro texty s variabilní délkou — automaticky zmenší font pokud se text nevejde do boxu:

{ "type": "text", "x": 2, "y": 2, "width": 59, "height": 7,
  "field": "nazev", "fontSize": 14, "overflow": "shrinkFont" }

Jak to funguje:

1. Začne na fontSize z JSON (např. 14pt)
2. Změří text — pokud se nevejde, zmenší o 0.5pt
3. Opakuje dokud se text vejde nebo dosáhne minima 4pt
4. Funguje s jednořádkovým i víceřádkovým textem (wordWrap)

⚠️ ShrinkFont funguje pouze v PDF. HTML preview tuto funkci nepodporuje — slouží jen k orientační kontrole rozložení.

Typické použití: Dlouhé názvy produktů — nastavte velký fontSize (12–14pt) jako ideál a overflow: "shrinkFont". Krátké názvy se zobrazí velkým písmem, dlouhé se automaticky zmenší.

10. Placeholdery a formáty

V template i field fungují stejné placeholdery jako v tabulkových sestavách:

11. Příklady kompletních šablon

Ceníkový štítek 3×8 na A4

{
  "renderer": "label",
  "layout": {
    "type": "sheet", "pageSize": "A4",
    "columns": 3, "rows": 8,
    "labelWidth": 63.5, "labelHeight": 33.9,
    "marginTop": 13, "marginLeft": 5,
    "gapX": 2.5, "gapY": 0
  },
  "data": { "element": "zbozi" },
  "content": [
    { "type": "text", "x": 2, "y": 2, "width": 59, "height": 7,
      "field": "nazev", "fontSize": 9, "style": "bold", "align": "center", "maxLines": 2 },
    { "type": "text", "x": 2, "y": 10, "width": 35, "height": 4,
      "template": "Kód: {kod}", "fontSize": 7 },
    { "type": "barcode", "x": 5, "y": 15, "width": 53, "height": 10,
      "field": "ean", "format": "EAN13", "visibleWhen": "ean" },
    { "type": "line", "x": 2, "y": 26, "width": 59, "style": "thin" },
    { "type": "text", "x": 2, "y": 27, "width": 40, "height": 5,
      "template": "{cena:N2} Kč/{mj}", "fontSize": 12, "style": "bold" }
  ]
}

Akční štítek s barevným pozadím

{
  "renderer": "label",
  "layout": { "type": "sheet", "columns": 3, "rows": 4,
    "labelWidth": 63.5, "labelHeight": 60, "marginTop": 15, "marginLeft": 8, "gapX": 3 },
  "data": { "element": "zbozi", "where": "typ=A" },
  "content": [
    { "type": "rect", "x": 0, "y": 0, "width": 63.5, "height": 60, "fill": "#fff8e0" },
    { "type": "text", "x": 3, "y": 3, "width": 57, "height": 6,
      "template": "★ AKCE", "fontSize": 10, "style": "bold", "color": "red", "align": "center" },
    { "type": "text", "x": 3, "y": 12, "width": 57, "height": 10,
      "field": "nazev", "fontSize": 11, "style": "bold", "align": "center" },
    { "type": "text", "x": 3, "y": 30, "width": 57, "height": 12,
      "template": "{cena:N2} Kč", "fontSize": 18, "style": "bold", "align": "center" },
    { "type": "text", "x": 3, "y": 45, "width": 57, "height": 8,
      "template": "SLEVA {sleva}%", "fontSize": 12, "style": "bold", "color": "red",
      "align": "center", "visibleWhen": "sleva" }
  ]
}

Paletový štítek (roll 100×80mm)

{
  "renderer": "label",
  "layout": { "type": "roll", "labelWidth": 100, "labelHeight": 80 },
  "data": { "element": "palety" },
  "content": [
    { "type": "rect", "x": 1, "y": 1, "width": 98, "height": 78, "border": "#000" },
    { "type": "text", "x": 3, "y": 3, "width": 94, "height": 8,
      "field": "firma", "fontSize": 12, "style": "bold", "align": "center" },
    { "type": "barcode", "x": 8, "y": 15, "width": 84, "height": 22,
      "field": "sscc", "format": "Code128", "showText": true },
    { "type": "text", "x": 3, "y": 48, "width": 60, "height": 8,
      "template": "Množství: {mnozstvi} {mj}", "fontSize": 11, "style": "bold" }
  ]
}

12. Konverze z FoxPro LBX

Stávající FoxPro LBX štítky (CENK3X8.xml, ADR_2X6.xml, STITEK128.xml atd.) lze automaticky konvertovat na JSON:

*--- Konverze jednoho souboru ---
loBuilder.ConvertLbxToJsonFile("CENK3X8.xml", "cenk3x8.json")

*--- Do složky ---
loBuilder.ConvertLbxToAllFiles("CENK3X8.xml", "C:\output\")

*--- Nebo přes obecnou metodu (auto-detekce LBX z objcode=53) ---
loBuilder.ConvertFrxToJsonFile("CENK3X8.xml", "cenk3x8.json")

Konvertor automaticky rozpozná:

• Rozměry štítku a počet sloupců z LBX headeru
• Textová pole s fontem, stylem a zarovnáním
• Čárové kódy (z otiskserv.BarCodeImage) včetně formátu (Code128, EAN13)
• Loga (z logofile())
• Podmíněnou viditelnost z PrintWhen výrazů
• FoxPro výrazy: sl("label"), concatenace, str(), transform()

Tip: Po konverzi zkontrolujte JSON a upravte element (datový zdroj), případně layout rozměry.

13. FoxPro použití

Příprava XML dat

loBuilder = CREATEOBJECT("XmlStackBuilder.Core.XmlStackBuilder")
loBuilder.CreateRoot("root")

*--- Header s parametry ---
loBuilder.Push("parametr")
loBuilder.AddAttribute("firma", "EFES spol. s r.o.")
loBuilder.AddAttribute("logo", "C:\images\logo.png")
loBuilder.Pop()

*--- Datové řádky pro štítky ---
CURSORTOXML("tmpStitky", "lcXml", 3, 16)
loBuilder.AddElementWithXmlContent("zbozi", m.lcXml)

*--- Render ---
loBuilder.Render("stitky.pdf", "cenikove_stitky.json")

Tisk na načatý arch

*--- Pokud arch má spotřebovaných 4 štítků ---
* V JSON: "startPosition": 5
* Nebo dynamicky přes parametr:
loBuilder.Push("parametr")
loBuilder.AddAttribute("start", TRANSFORM(lnPocetSpotrebovanych + 1))
loBuilder.Pop()

* V JSON: "startPosition": "{parametr.start}"

Kopie per řádek

*--- Každý řádek má pole "pocet_stitku" ---
* V JSON: "copiesField": "pocet_stitku"
* Řádek s pocet_stitku=3 → 3 stejné štítky

14. Řešení problémů

Štítky jsou posunuté

1. Zapněte "showBorders": true v calibration
2. Vytiskněte arch a změřte odchylku
3. Nastavte "xOffset" a "yOffset" (kladné = posun doprava/dolů)
4. Vypněte showBorders

Čárový kód se nezobrazuje

• Zkontrolujte, že pole není prázdné (barcode s prázdnou hodnotou se přeskočí)
• EAN-13 potřebuje 12-13 číslic
• Přidejte "visibleWhen": "ean" aby se prázdný kód nepokusil vykreslit

Text je oříznutý

• Zvětšete height bloku
• Nastavte "maxLines": 2 pro dvouřádkový text
• Zvětšete width pro delší texty

PDF je prázdné

• Zkontrolujte, že XML obsahuje element uvedený v data.element
• Element musí obsahovat <row> potomky s atributy
• Zkontrolujte where filtr — nefiltruje všechny řádky?

Formát čísla je špatný

• "N2" → 2 desetinná místa (45,90)
• "N0" → celé číslo (46)
• "###.###" → textová maska (123.456)
• Kultura je cs-CZ (desetinná čárka)