Výrazy, podmínky a placeholdery — kompletní průvodce

Tento dokument popisuje všechny druhy výrazů, podmínek a placeholderů dostupných v JSON šablonách XmlStackBuilder. Funkce jsou společné pro všechny tři typy rendererů (tabulkové sestavy, dokumenty, štítky), pokud není uvedeno jinak.

Obsah

1. Placeholdery {pole}
2. Tečková notace {element.pole}
3. Aliasy
4. Formátování {pole:formát}
5. Coalesce {pole1|pole2|'literál'}
6. Textové modifikátory :UPPER, :LOWER, :PROPER
7. Textová maska ###.###
8. Zkrácení textu {pole:50}
9. Ternární výrazy {podmínka?ano:ne}
10. Podmínky (visibleWhen, where, when)
11. Aritmetické výrazy (expr)
12. Agregační funkce (SUM, AVG, ...)
13. Funkce v expr a šablonách
14. Datumové funkce
15. Funkce v groupExpression
16. Lookup tabulky
17. Kde co funguje — přehledová tabulka

1. Placeholdery {pole}

Základní mechanismus pro vložení hodnoty z XML dat do výstupního textu.

{ "label": "Faktura {cislo}" }

XML: <header cislo="FV2600001" /> → výstup: Faktura FV2600001

Placeholder {pole} se nahradí hodnotou atributu pole z aktuálního XML elementu. Pokud atribut neexistuje, placeholder se nahradí prázdným řetězcem.

Kde funguje

• label a sumLabel na skupinách
• template na sloupcích
• title, filter, company v metadatech sestavy
• text, label, value, signatureLeft, signatureRight ve footerRows
• template v info-grid položkách (dokumenty)
• lines v text-block (dokumenty)
• watermark v metadatech

2. Tečková notace {element.pole}

Přístup k hodnotám z jiných XML elementů než aktuálního kontextu.

{ "template": "{cena:N2} {parametr.mena}" }

XML:

<root>
  <parametr mena="CZK" />
  <data><row cena="1500" /></data>
</root>

Výstup: 1 500,00 CZK

Pravidla navigace

Navigace je case-insensitive — {Header.Mena} i {header.mena} fungují stejně.

Priorita hledání

1. Lookup tabulky — pokud element odpovídá registrovanému lookup aliasu
2. XML root — navigace přes ResolveElementByPath
3. Aktuální kontext — atribut přímo na aktuálním řádku

Důležité: Pokud je element registrovaný jako lookup alias a lookup nenajde záznam, vrátí se prázdný řetězec. Nikdy se nespadne na XML root — to by vrátilo první řádek místo aktuálního.

3. Aliasy

Zkratky pro opakované hluboké cesty. Definují se na úrovni celé šablony:

{
  "aliases": {
    "pol": "objednavka.polozky",
    "hlav": "objednavka.hlavicka"
  },
  "sections": [{
    "element": "pol",
    "columns": {
      "cena": { "label": "Cena {hlav.mena}", "format": "N2" }
    }
  }]
}

Aliasy se substituují před renderováním ve všech relevantních vlastnostech: element, visibleWhen, where, template placeholdery, expr.

4. Formátování {pole:formát}

Za dvojtečkou lze uvést formátovací řetězec:

{ "label": "Datum: {datum:dd.MM.yyyy}", "template": "Celkem: {castka:N2}" }

Číselné formáty

Datumové formáty

Textová maska

Viz sekce 7.

Zkrácení textu

Viz sekce 8.

5. Coalesce {pole1|pole2|'literál'}

První neprázdná hodnota ze seznamu. Literální fallback v jednoduchých uvozovkách:

{ "template": "{nazev_cz|nazev_en|'Bez názvu'}" }

Coalesce funguje i s tečkovou notací: {header.firma|parametr.firma|'Neuvedeno'}.

6. Textové modifikátory :UPPER, :LOWER, :PROPER

Transformace velikosti písmen. Uvádí se jako poslední modifikátor za formátem:

{ "format": "UPPER" }
{ "template": "{firma:UPPER}" }
{ "template": "{nazev:N2:PROPER}" }

Modifikátor se aplikuje po formátování čísla/data. U {cena:N2:UPPER} se nejdřív zformátuje číslo, pak převede na velká písmena (pro čísla nemá efekt, ale pro text-číslo kombinace ano).

7. Textová maska ###.###

Formát obsahující # se interpretuje jako textová maska — každý # představuje jeden znak ze vstupní hodnoty, ostatní znaky jsou literály:

{ "label": "Účet", "format": "###.###" }

Maska se aplikuje na textovou hodnotu (zleva doprava). Pokud je vstup kratší než počet #, přebytečné literály se vynechají.

8. Zkrácení textu {pole:50}

Pokud je formát celé číslo, funguje jako maximální délka textu:

{ "label": "Název", "format": "80" }
{ "template": "{text:50}" }

Hodnota se ořízne na zadaný počet znaků. Zkrácení se kontroluje před numerickým formátováním — {cislo:5} je oříznutí na 5 znaků, ne číselný formát.

9. Ternární výrazy {podmínka?ano:ne}

Inline podmíněný text v libovolné šabloně:

{
  "label": "Účet {ucet} {osnova.ap=A?AKTIVNÍ:PASIVNÍ}",
  "sumLabel": "Celkem {typ=P?příjem:výdej}",
  "template": "{stav=A?Aktivní:stav=P?Pasivní:Zrušený}"
}

Syntaxe

{podmínka?text_true:text_false}

Podmínka používá stejné operátory jako visibleWhen (viz sekce 10).

Apostrofové literály v ternárních výrazech

Výsledkové větve i podmínky mohou obsahovat apostrofové literály. Apostrofy jsou nutné pokud text obsahuje speciální znaky (:, ?, |) nebo když chcete explicitně odlišit literál od názvu pole:

{
  "template": "{stav='A'?'Aktivní: ano':'Neaktivní: ne'}",
  "sumLabel": "{typ='P'?'Příjem (kladný)':'Výdej (záporný)'}",
  "label": "{mena='CZK'?'Částka v Kč':'Amount in {mena}'}"
}

Bez apostrofů {stav=A?Aktivní:Neaktivní} funguje stejně — apostrofy jsou volitelné pro jednoduchý text bez speciálních znaků.

Numerické hodnoty v podmínkách

Čísla v podmínce (pravá strana =, >, < atd.) nemusí být v apostrofech:

{
  "label": "Skupina prodlení — {prodl_skup=0?'Zaplacené':prodl_skup=1?'Před splatností':prodl_skup=2?'1–30 dní':'Po splatnosti'}",
  "template": "{pocet>10?'Hromadná objednávka':'Kusový prodej'}"
}

Podmínka prodl_skup=0 se vyhodnotí jako číselné porovnání, bez apostrofů — XSB si všimne, že 0 není platný XML identifikátor (nezačíná písmenem), a bere ho jako literál.

Historická poznámka: Do XSB 1.1.7 byl parser přísnější a pravou stranu = zkoušel vždy nejdřív resolvovat jako pole → XElement.Attribute("0") padl na XmlException. Oprava v 1.1.8 přidala IsValidXmlName guard.

Nevnořujte {…} do větví ternary

Špatně:

{ "label": "{a=1?X:{b=2?Y:Z}}" }

Vnitřní {b=2?…} se interpretuje jako samostatný placeholder, ne jako vnořený ternary — regex parsovač si s tím neporadí.

Správně (řetězení přes :?):

{ "label": "{a=1?X:b=2?Y:Z}" }

Řetězení (else-if)

{a=1?První:a=2?Druhý:Ostatní}
{a='1'?'Výsledek: první':a='2'?'Výsledek: druhý':'Výsledek: ostatní'}

Ternární výrazy lze vnořovat — vyhodnocují se zleva doprava.

Kde funguje

• template na sloupcích
• label a sumLabel na skupinách
• sumLabel na sumRows
• format na barcode blocích (štítky): "{ean=true?EAN13:Code128}"
• expr v sumExpressions: "osnova.ap=A?SUM(md)-SUM(d):SUM(d)-SUM(md)"
• podmíněné barvy/fonty na štítcích: "color": "{stav='storno'?red:#000}"

10. Podmínky (visibleWhen, where, when)

Logické podmínky pro řízení viditelnosti, filtrování a stylování.

Operátory porovnání

Operátor NOT

Negace libovolné podmínky v závorkách:

"where": "NOT (stav='Z')"
"visibleWhen": "NOT (typ IN ('X', 'Y'))"
"when": "NOT (poznamka)"

NOT má vyšší prioritu než AND/OR.

Závorky v podmínkách

Závorky mění pořadí vyhodnocování AND/OR:

"where": "(typ='A' OR typ='B') AND stav='novy'"
"visibleWhen": "typ='X' OR (stav='novy' AND castka>1000)"

Bez závorek: A OR B AND C = A OR (B AND C). Se závorkami: (A OR B) AND C.

Závorky lze vnořovat do libovolné hloubky: ((a OR b) AND c) OR d.

Operátor LIKE — vzory

"where": "nazev LIKE 'FV%'"
"where": "kod LIKE '34_'"
"where": "text NOT LIKE '%test%'"

LIKE je case-insensitive.

Operátor BETWEEN

Číselný rozsah včetně obou hranic:

"where": "castka BETWEEN 1000 AND 5000"

Ekvivalent: castka>=1000 AND castka<=5000. Hodnoty se parsují jako čísla.

Poznámka: AND uvnitř BETWEEN se neparsuje jako logický operátor — castka BETWEEN 1000 AND 5000 AND stav='A' funguje správně (poslední AND je logický).

Funkce v levé straně podmínky

Levá strana operátoru může obsahovat funkci:

"where": "LEN(poznamka)>100"
"visibleWhen": "LEFT(ucet, 3)='343'"
"when": "UPPER(typ) IN ('A', 'B')"

Pokud levá strana obsahuje (, vyhodnotí se jako funkce přes výrazový engine.

Apostrofové literály v podmínkách

Hodnota na pravé straně operátoru může být v apostrofech — to ji označí jako literál (doslovný text), ne jako název jiného pole:

"where": "stav='A'"
"visibleWhen": "mena!='CZK'"
"when": "typ IN ('P', 'V', 'S')"

Bez apostrofů se pravá strana nejdřív zkusí resolvovat jako název pole (field-to-field porovnání). Pokud pole neexistuje, použije se jako literál. S apostrofy se vždy použije doslovně — bezpečnější a jednoznačnější.

Tip: Apostrofy doporučujeme pro hodnoty, které by se mohly shodovat s názvem existujícího XML pole.

Logické operátory AND / OR

Podmínky lze kombinovat:

"visibleWhen": "header.je_cizi_mena AND header.kurz>1"
"where": "typ=P OR typ=V"
"when": "stav=A AND castka>0 OR stav=P AND castka>5000"

Precedence: AND váže silněji než OR (stejně jako v SQL).

Výraz A OR B AND C se vyhodnotí jako A OR (B AND C).

Operátory musí být oddělené mezerami: stav=A AND castka>0 — ne stav=AANDcastka>0.

Co se považuje za prázdné/nulové

Test "pole" (neprázdné) a "!pole" (prázdné) považuje za nulové:

• Prázdný řetězec ""
• "0", "0,00", "0.00", "0,0000" (různé formáty nuly)
• Mezery a non-breaking spaces

Kde se podmínky používají

Dynamické where s placeholdery

Podmínka where na sumRow může obsahovat {pole} placeholder:

{
  "sumLabel": "KZ k m.{obdobi}",
  "scope": "ucet",
  "where": "obdobi<={obdobi}"
}

Při zpracování období 3 se {obdobi} resolvuje na 3 → podmínka "obdobi<=3" zahrne řádky za období 1, 2, 3.

11. Aritmetické výrazy (expr)

Počítané sloupce s aritmetickými výrazy vyhodnocovanými per-řádek:

{
  "columns": {
    "celkem": { "label": "Celkem", "expr": "cena * pocet", "format": "N2", "round": 2 },
    "s_dph": { "label": "S DPH", "expr": "cena * pocet * 1.21", "format": "N2" }
  }
}

Podporované operátory

Precedence: * a / mají vyšší prioritu než + a -.

Konstanty

Číselné konstanty lze použít přímo ve výrazech: "cena * 1.21", "pocet * 0.5".

Tečková notace ve výrazech

Cross-element přístup funguje i v expr:

{ "expr": "cena * header.kurz" }

Zaokrouhlení

Property round (celé číslo) zaokrouhlí výsledek na zadaný počet desetinných míst (matematické zaokrouhlení, AwayFromZero):

{ "expr": "cena * pocet * 1.21", "round": 2 }

Průběžný součet (running)

{
  "zustatek": {
    "label": "Zůstatek",
    "expr": "prijem - vydaj",
    "running": true,
    "runningInitial": "{prnobj.pz}",
    "resetAt": "ucet",
    "format": "N2"
  }
}

• running: true — sloupec zobrazuje kumulativní součet
• runningInitial — počáteční hodnota (default 0). Číslo ("5987") nebo {element.field} placeholder
• resetAt: "skupina" — reset při změně dané skupiny (resetuje na runningInitial nebo 0)

12. Agregační funkce (SUM, AVG, ...)

V sumExpressions na skupinách a sekcích:

{
  "sumExpressions": [
    { "field": "castka", "expr": "SUM(castka)", "format": "N2" },
    { "field": "prumer", "expr": "AVG(cena)", "format": "N2" },
    { "field": "pocet", "expr": "COUNT()", "format": "N0" }
  ]
}

Podporované funkce

Složené výrazy

Agregační funkce lze kombinovat aritmeticky:

{ "expr": "SUM(md) - SUM(d)" }
{ "expr": "SUM(castka) / COUNT()" }
{ "expr": "SUM(cena * pocet)" }

Ternární podmínka uvnitř agregace

Per-řádková podmínka uvnitř SUM:

{ "expr": "SUM(kcizi=1?mdcizi:0)" }

Pro každý řádek: pokud kcizi=1, přičte mdcizi, jinak přičte 0.

Ternární výraz na celém expr

Podmíněný výběr celého výpočtu:

{ "expr": "osnova.ap=A?SUM(md)-SUM(d):SUM(d)-SUM(md)" }

Podmínka osnova.ap=A se vyhodnotí z lookup tabulky. Podle výsledku se použije jeden nebo druhý výraz.

SUMBY — per-subgroup agregace

{ "expr": "SUMBY(ucet, osnova.ap=A?SUM(md)-SUM(d):SUM(d)-SUM(md))" }

Rozparticionuje řádky podle ucet, pro každou skupinu vyhodnotí ternární výraz zvlášť a výsledky sečte. Řeší situace kde podřízené položky mají různé vlastnosti (např. DPH syntetika s účty na A i P straně).

13. Funkce v expr a šablonách

Výrazový engine podporuje volání funkcí ve výrazech (expr), v šablonách (template, label, sumLabel) a v podmínkách (levá strana).

Numerické funkce

{ "expr": "ROUND(cena * 1.21, 2)", "format": "N2" }
{ "expr": "ABS(md - d)", "format": "N2" }

Řetězcové funkce

Řetězcové funkce v aritmetickém kontextu vrací 0 (jako číslo). V šablonovém kontextu vrací text.

Logické/utility funkce

NULLIF vrací prázdný řetězec pokud se oba argumenty rovnají (case-insensitive), jinak vrací první argument. Typické použití: potlačení výchozí hodnoty.

FORMAT aplikuje .NET formátovací vzor na číslo nebo datum. Pro čísla: 'N0', 'N2', '#,##0.00'. Pro datumy: 'dd.MM.yyyy', 'MMMM yyyy'.

CHRTRAN překládá po znacích — každý znak v expr nalezený v hledej se nahradí odpovídajícím znakem z nahraď. Pokud je nahraď kratší, znaky bez protějšku se odstraní. Kompatibilní s FoxPro CHRTRAN().

VAL převádí textový řetězec na číslo (decimal). Pokud text není číslo, vrací 0. Kompatibilní s FoxPro VAL().

{ "expr": "IIF(stav=A, cena, 0)", "format": "N2" }
{ "template": "{EVL(poznamka, '—')}" }
{ "template": "{NULLIF(mena, 'CZK')}" }
{ "template": "Cena: {FORMAT(castka, 'N0')} Kč" }
{ "template": "{CHRTRAN(telefon, '-/.', '')}" }
{ "expr": "VAL(pocet_text) * cena", "format": "N2" }

Vnořené funkce

Funkce lze vnořovat:

{ "expr": "ROUND(ABS(cena - sleva), 2)" }
{ "template": "{UPPER(LEFT(nazev, 3))}" }

Funkce v šablonách

V template, label, sumLabel lze použít funkce uvnitř {}:

{
  "template": "{LEFT(nazev, 20)} — {ROUND(cena * 1.21, 2):N2}",
  "label": "Skupina {LEFT(ucet, 3)}",
  "sumLabel": "Celkem za {UPPER(typ)}"
}

Funkce se vyhodnotí jako první krok, poté proběhne standardní formátování a coalesce.

Funkce v agregacích

Funkce uvnitř SUM() a dalších agregačních funkcí:

{ "expr": "SUM(ABS(castka))", "format": "N2" }
{ "expr": "SUM(ROUND(cena * 1.21, 2))", "format": "N2" }

14. Datumové funkce

Funkce pro práci s datumy. Vstupní datum se parsuje automaticky z formátů: yyyy-MM-dd, dd.MM.yyyy, yyyy-MM-ddTHH:mm:ss, ISO 8601.

{ "expr": "YEAR(datum)", "format": "N0" }
{ "where": "DATEDIFF(splatnost, TODAY())>30" }
{ "template": "Splatnost: {DATEADD(datum, 14)}" }

NOW() a TODAY() nemají argumenty — závorky musí být prázdné.

15. Funkce v groupExpression

Funkce lze použít přímo v groupExpression pro dynamické seskupování:

{
  "groups": [{
    "groupExpression": "LEFT(ucet, 3)",
    "label": "Syntetika {LEFT(ucet,3)}",
    "headerMode": "external",
    "tableBreak": true
  }]
}

Jak to funguje

1. GetGroupKey — při detekci ( ve výrazu se vyhodnotí přes výrazový engine místo čtení atributu
2. Virtuální element — výsledek funkce se uloží jako atribut na virtuální group element (klíč = výraz bez mezer, např. LEFT(ucet,3))
3. Label template — {LEFT(ucet,3)} v labelu se resolvuje z virtuálního elementu

Příklady

"groupExpression": "LEFT(ucet, 3)"
"groupExpression": "YEAR(datum)"
"groupExpression": "UPPER(stredisko)"

Compound klíče: "groupExpression": ["LEFT(ucet, 3)", "obdobi"] — funkce + prosté pole.

16. Lookup tabulky

Přidání doplňkových dat ze samostatných XML elementů ke skupinám:

{
  "groups": [{
    "groupExpression": "organizace",
    "label": "{organizace} — {adresy.firma}",
    "lookup": { "element": "adresy" }
  }]
}

Jednoduchý lookup

"lookup": { "element": "adresy" }

Při změně skupiny se v elementu adresy dohledá řádek se shodným klíčem (default = groupExpression).

Řetězený lookup (chained)

"lookup": [
  { "element": "hlavicky_dokladu" },
  { "element": "adresy", "key": "organizace" }
]

Sekvenční dohledání: nejdřív hlavičku dokladu, z ní organizace, pak adresu.

Vlastnosti lookup

Funkční výraz v key

Pokud skupinový klíč je funkce (např. LEFT(ucet, 3)), lookup key musí být ve složených závorkách:

{
  "groupExpression": "LEFT(ucet, 3)",
  "lookup": {
    "element": "syn_ucty",
    "key": "{LEFT(ucet,3)}",
    "foreignKey": "syn"
  }
}

• {LEFT(ucet,3)} se vyhodnotí per řádek přes výrazový engine → výsledek (např. "343") se použije jako klíč pro dohledání v lookup tabulce
• foreignKey musí být zadán explicitně — nezdědí se z funkčního výrazu
• Pokud key není zadán a groupExpression obsahuje funkci, auto-key se obalí {…} automaticky

Přístup k lookup polím

• V group headeru/labelu: přímo {firma}, {den:dd.MM.yyyy}
• V detailních sloupcích: tečková notace {adresy.firma}
• Ve výrazech: "expr": "cena * hlavicky.kurz"

17. Kde co funguje — přehledová tabulka

Tabulkové sestavy (renderer: "table")

Dokumenty (renderer: "document")

Štítky (renderer: "label")

Pořadí vyhodnocování

Při renderování jedné buňky/hodnoty je pořadí zpracování:

1. Alias substituce — nahrazení aliasů plnými cestami
2. Placeholder resolvování — {pole}, {el.pole}, coalesce, ternární výrazy
   • Apostrofy v ternárních výrazech se stripují: 'text' → text
   • Apostrofy v podmínkách označují literál: pole='hodnota'
   • Znaky uvnitř apostrofů (?, :, |) se neparsují jako operátory
3. Textový modifikátor — detekce a oddělení :UPPER/:LOWER/:PROPER
4. Formátování — číslo (N2), datum (dd.MM.yyyy), maska (###.###), zkrácení (50)
5. Aplikace modifikátoru — převod velikosti písmen na výsledný text
6. hideZero kontrola — skrytí nulových hodnot (pokud aktivní)

Locale a regionální nastavení

• Kultura se nastavuje v report.culture (default "cs-CZ")
• Číselné formáty respektují kulturu: N2 → 1 234,50 (cs-CZ) nebo 1,234.50 (en-US)
• Datumové formáty respektují kulturu: MMMM → březen (cs-CZ) nebo March (en-US)
• Porovnávání v podmínkách je case-insensitive (invariant culture)
• Numerické parsování v podmínkách (>, <) je flexibilní — akceptuje , i . jako oddělovač

Řešení problémů

Placeholder se nezobrazí

• Ověřte, že XML data obsahují odpovídající atribut: <header firma="Test" />
• Zkontrolujte správnost tečkové notace: {header.firma} (ne {header/firma})
• V debug módu ("debug": true) se nezobrazí [MISSING: field] žlutě

Podmínka nefunguje

• AND a OR musí být oddělené mezerami: stav=A AND castka>0
• IN vyžaduje závorky: typ IN (A, B) (ne typ IN A, B)
• LIKE vyžaduje apostrofy kolem vzoru: nazev LIKE 'Fakt%' (ne nazev LIKE Fakt%)
• BETWEEN vyžaduje AND mezi hranicemi: castka BETWEEN 1000 AND 5000
• NOT vyžaduje závorky u složených podmínek: NOT (typ='A' AND stav='B')
• Numerické porovnání vyžaduje číslo na pravé straně: castka>1000
• Pokud se hodnota shoduje s názvem XML pole, použijte apostrofy: stav='aktivni'
• Funkce v levé straně podmínky: LEN(text)>5 — závorky kolem funkce se nesmí zaměnit se závorkami podmínky

Ternární výraz se špatně parsuje

• Text obsahující dvojtečku musí být v apostrofech: {stav=A?'Ano: platí':'Ne: neplatí'}
• Text obsahující otazník musí být v apostrofech: {ok?'Hotovo?':'Čeká'}
• Vnořené ternáry fungují i s apostrofy: {a='1'?'X':b='2'?'Y':'Z'}

Formát se neaplikuje

• Ověřte, že hodnota je platné číslo/datum
• Textové modifikátory (:UPPER) musí být poslední: {pole:N2:UPPER} (ne {pole:UPPER:N2})
• Maska ###.### funguje jen na textové hodnoty, ne na čísla s formátem N2