XmlStackBuilder — API Reference

Kompletní seznam veřejných metod a properties třídy XmlStackBuilder. Většina metod je volatelná z FoxPro přes wwDotnetBridge — výjimky (Stream, IDataReader, interfacy, out parametry, eventy) jsou v tabulkách označené ❌ a mají FoxPro alternativy.

Tip pro AI-asistovaný vývoj sestav: XSB je navržen tak, aby kombinace generátorů (CursorSchemaGenerator, DocumentTemplateGenerator)

• AI nástroj (Claude Code / GPT) + Live Preview ve VS Code nahradila ruční editaci JSON šablon. Detaily a praktické příklady v AI_WORKFLOW.md.

Properties

Obecné

HTML generování

Batch, tisk a průběh

ShowProgress zobrazí WinForms dialog s progress barem, číslem řádku a tlačítkem "Storno" pro přerušení. Dialog běží na samostatném STA threadu — renderování zůstává synchronní. Při zrušení se nastaví HtmlErrorMessage a Render() vrátí false. Property přežívá Reset() i EndBatch().

XML Builder

Výstup XML

Round-trip — úprava existujícího XML

Načtení existujícího XML a nahrazení / doplnění / odebrání opakujících se kolekcí na správné pozici dle XSD, poté uložení zpět (SaveToFile / ToXmlString). Hlavní use-case: doplnit do rozpracovaného přiznání k DPPO věty účetních výkazů (rozvaha VetaUA/VetaUB, výsledovka VetaUD) bez generování celého dokumentu znovu.

Pravidla:

• parentPath — lomítková cesta k rodiči (case-insensitive, ignoruje namespace), např. "DPPDP9" nebo "Pisemnost/DPPDP9". Prázdné = root. První segment může (ale nemusí) být jméno rootu.
• rowsXml — libovolně pojmenované řádky (typicky <row> z CURSORTOXML, vč. <?xml?> deklarace a <VFPData> wrapperu — obojí se automaticky strhne). Každý řádek se přejmenuje na elementName a zkopírují se jeho atributy i child obsah. Namespace se převezme od existujících sourozenců, jinak od rodiče.
• S RoundTripSchemaPath: nové elementy se vloží na správné místo dle XSD sekvence (i když dosud v dokumentu nebyly). Bez schématu: ReplaceCollection vloží na pozici původních elementů, jinak na konec.
• Statický helper XmlRoundTrip (ResolveParent, GetChildOrderFromXsd, ReplaceCollection, AppendCollection, RemoveCollection) je k dispozici i bez instance builderu (pracuje nad XElement).

Příklad (FoxPro) — doplnění účetních výkazů do přiznání k DPPO:

loBuilder.LoadXml("priznani_rozpracovane.xml")          && načte existující dokument
loBuilder.RoundTripSchemaPath = "xsd\dppdp9_epo2.xsd"   && (volitelně) pro správné řazení dle XSD

*--- rozvaha aktiva: cursor tmpUA → každý řádek se vloží jako <VetaUA> ---
CURSORTOXML("tmpUA", "lcUA", 3, 16)
loBuilder.ReplaceCollection("DPPDP9", "VetaUA", m.lcUA)  && smaže staré, vloží nové na správné místo

*--- rozvaha pasiva ---
CURSORTOXML("tmpUB", "lcUB", 3, 16)
loBuilder.ReplaceCollection("DPPDP9", "VetaUB", m.lcUB)

*--- výsledovka ---
CURSORTOXML("tmpUD", "lcUD", 3, 16)
loBuilder.ReplaceCollection("DPPDP9", "VetaUD", m.lcUD)

IF loBuilder.ReplaceCollection("DPPDP9", "VetaUA", m.lcUA) = -1
    ? "Chyba: " + loBuilder.LastRoundTripError
ENDIF

loBuilder.SaveToFile("priznani_doplnene.xml")

Příklad (.NET) — statický helper nad XElement:

var doc = XDocument.Load("priznani.xml");
var dppdp9 = doc.Root.Element("DPPDP9");
var order = XmlRoundTrip.GetChildOrderFromXsd("xsd/dppdp9_epo2.xsd", "DPPDP9");

XmlRoundTrip.ReplaceCollection(dppdp9, "VetaUA", rowsXmlUA, order);
XmlRoundTrip.ReplaceCollection(dppdp9, "VetaUB", rowsXmlUB, order);
XmlRoundTrip.ReplaceCollection(dppdp9, "VetaUD", rowsXmlUD, order);
doc.Save("priznani_doplnene.xml");

Deserializace XML → DTO

Čtení XML do XSD-generovaných modelů (Models.Accounting/Payroll/Erp) přes XmlSerializer — opačný směr k builderu. Use-case: čtení potvrzenek / chybových protokolů z EPO či datové schránky, validační smyčka „vygeneruj → deserializuj → porovnej". FoxPro neumí .NET generika ani objektový graf → fasáda DeserializeXml + GetDtoField(path).

IF loBuilder.DeserializeXml("odpoved.xml", "Dphdp3Epo2.Pisemnost")
    ? loBuilder.GetDtoField("verzeSW")
ELSE
    ? loBuilder.LastDeserializeError
ENDIF

var p = XmlStackBuilder.Core.DtoDeserializer.Deserialize<Dphdp3Epo2.Pisemnost>("odpoved.xml");

Pozn.: DTO assembly (model) musí být přítomná vedle XmlStackBuilder.Core.dll. Decimal/čísla se formátují invariantně (zachová koncovou nulu, např. 1000.50).

Datová schránka (ISDS) — odeslání podání

Přepravní vrstva pro podání datovou schránkou (ČSSZ REGZEC/JMHZ apod.) — nevyžaduje el. podpis. XSB poskytuje bezstavový SOAP klient + kodek zpráv; stav podání / perzistenci / polling / UI řeší aplikace (viz NAVRH_DATOVA_SCHRANKA_CSSZ.md). Stažené odpovědi ČSSZ se čtou přes deserializaci výše.

loBuilder.IsdsConfigure("test", "login", "heslo", "")
loBuilder.IsdsSenderBoxId = "abc1234"
lcDmId = loBuilder.IsdsSendFile("ID_schranky_CSSZ", "e-Podání REGZEC", "REGZEC.xml", "REGZEC.xml")
IF EMPTY(lcDmId)
    ? loBuilder.LastIsdsError
ENDIF
*--- později: stáhnout odpověď a přečíst přes deserializaci ---
IF loBuilder.IsdsDownloadResponse(lcOdpovedDmId, "C:\tmp\odp")
    loBuilder.DeserializeXml("C:\tmp\odp\protokol.xml", "<TYP_ODPOVEDI>")
ENDIF

⚠️ Endpointy a přesné názvy polí ISDS jsou označeny k ověření proti czebox testu; síťové metody nejsou unit-testované (offline je jen kodek). Před produkčním nasazením otestovat proti czebox.cz.

Validace XML

HTML z XML (opis XML s popisky z XSD)

Režim „jeden prvek = jeden řádek" (SingleRowMode)

Varianta HTML opisu XML, kde je každý atribut nebo leaf element na samostatném řádku se třemi sloupci: název | popis z XSD | hodnota. Popis elementu (pokud je v XSD) se navíc zobrazuje vedle nadpisu sekce kurzívou. Opakující se sekce (více záznamů stejného jména) se rozpadnou na samostatné karty s číslováním #1, #2…

Zapnout lze buď jednorázovou metodou SaveToHtmlFileSingleRow, nebo propertou HtmlSingleRowMode = .T. (režim pak platí i pro SaveToHtmlFileWithValidation a SaveXmlFileToHtmlWithValidation).

Property:

Použití z FoxPro:

*--- Varianta 1: jednorázová metoda (režim se po zavolání vrátí zpět) ---
loBuilder.SaveToHtmlFileSingleRow("out.html", "C:\xsd\REGZEC")

*--- Varianta 2: property + existující metody (včetně validace) ---
loBuilder.HtmlSingleRowMode = .T.
loBuilder.SaveToHtmlFileWithValidation("out.html", "C:\xsd\REGZEC")

*--- Z XML souboru (bez interního builderu) ---
loBuilder.HtmlSingleRowMode = .T.
loBuilder.SaveXmlFileToHtmlWithValidation("data.xml", "out.html", "C:\xsd\REGZEC")

Použití v C# (HtmlDataRenderer přímo):

var renderer = new HtmlDataRenderer
{
    SingleRowMode = true,
    XsdValidationPath = @"C:\xsd\REGZEC"  // volitelně inline validace
};
renderer.LoadDescriptionsFromXsd(@"C:\xsd\REGZEC");
var doc = XDocument.Load(xmlPath, LoadOptions.SetLineInfo);
renderer.RenderToFile(doc, htmlPath);

CSS třídy výstupu: .single-row-table, .sr-name, .sr-desc, .sr-val, .section-desc, .single-row-card. | ValidateTableReportJson(jsonMetadata) | string | Validuje JSON šablonu tabulkové sestavy | | ValidateDocumentJson(jsonMetadata) | string | Validuje JSON šablonu dokumentu |

Tabulkové sestavy (HTML)

Dokumenty — faktury, dodací listy (HTML)

DOCX — editovatelný Word dokument

Ze stejných JSON šablon + XML dat vytvoří editovatelný .docx (přes DocumentFormat.OpenXml) — vedle HTML/PDF/XLSX. Funguje pro dokumentové šablony (renderer "document" → DocxDocumentRenderer) i pro tabulkové sestavy (renderer "table" → DocxTableReportRenderer). Label šablony do DOCX nejdou. Word si layout/styly řídí sám → konzistentní výstup, ne pixel-shoda s HTML/PDF.

loBuilder.Render("faktura.docx", "faktura.json")        && dokument → Word (auto-detekce)
loBuilder.Render("prehled.docx", "prehled.json")        && tabulková sestava → Word (auto-detekce)
loBuilder.SaveDocumentToDocx("faktura.docx", lcJson)     && explicitně dokument
loBuilder.SaveTableReportToDocx("prehled.docx", lcJson)  && explicitně tabulka

Dokumentové bloky: text-block, info-grid, table (+sumExpressions), header-two-column, total-amount, signature, separator, spacer, page-break, columns, image, qr-code, barcode. repeatElement + pageBreakBetween; form-table zatím fallback (text).

Tabulkové sestavy (DocxTableReportRenderer) mají paritu s ostatními renderery: sekce, sloupce (formáty/zarovnání/šířky/expr/template/running totals/hideZero/visibleWhen/negativeRed/suppressRepeat), skupiny (element-based i groupExpression, inline/external záhlaví, tableBreak, reprintHeader, forceNewPage, barvy/headerValues, lookupy), součtové řádky (sumExpressions/sumRows vč. where/labelField/per-cell stylů), footerRows, víceřádkové záhlaví headerRows (colspan/rowspan), rowStyles, alternateRowBackground, dictionary překlad, kontingenční tabulka pivot (→ Word tabulka) i graf chart (→ vložený PNG). Word si stránkuje sám (žádné virtuální pageLayout).

Sdílí šablonový engine ({field}, {element.field}, formáty, coalesce, ternár, funkce) i výrazy s ostatními renderery — jedna šablona = stejný výstup do HTML / PDF / XLSX / DOCX.

Layoutové vlastnosti (jedna šablona → stejný výstup HTML/PDF/DOCX): minHeightMm (header-two-column left/right — vyrovná výšku orámovaných boxů), rowHeightMm (table — min. výška řádku), border/borderFullWidth (rámeček sloupce v columns — podpisové boxy), gap/gapPx (mezera mezi sloupci v px, default 15 — shodná sémantika napříč renderery), { "type": "spacer", "heightMm": N } jako pole v header-two-column (volný řádek).

Kompatibilita s MS Word (proč se .docx otevírá bez „nečitelného obsahu"). DocumentFormat.OpenXml na .NET Frameworku používá System.IO.Packaging z WindowsBase, který zapisuje balíček způsobem, jenž Word sice přijme, ale „opraví" (dialog Nečitelný obsah). Renderer to po sestavení automaticky normalizuje, takže výstup je strukturně shodný s tím, co generuje sám Word:

• relativní relationship targety místo absolutních /word/... (Word absolutní cesty repairuje),
• standardní [Content_Types].xml (Default xml=application/xml + Override pro /word/document.xml), zapsané jako první entry v ZIP,
• obrázky ve word/media/ s odpovídajícím content-typem (JPG/PNG dle obsahu),
• strukturně validní tabulky: každá buňka končí odstavcem, dvě sousední tabulky odděluje odstavec, tělo nekončí tabulkou,
• settings.xml s compatibilityMode=15 (žádný „režim kompatibility").

Tyto problémy OpenXmlValidator nehlásí (kontroluje jen schéma, ne fyzické URI/umístění/strukturu).

Unified Render API

Univerzální metody — auto-detekce typu šablony (tabulka/dokument) a formátu výstupu (HTML/PDF/XLSX/DOCX) z přípony souboru (.docx jen pro dokumentové šablony).

Pravidla pro FoxPro-volatelná API

FoxPro přes wwDotnetBridge přes COM nezvládá:

• Overloady na typu parametru — bridge si vybere první match podle typů, což nemusí být správné
• out / ref parametry — COM je předává nespolehlivě
• Stream, IDataReader — FoxPro nemá protějšek, nelze předat
• .NET interfacy (IDictionaryTranslator) — FoxPro je neimplementuje
• Eventy — události přes COM jsou křehké

Proto má XSB dvě varianty kde to dává smysl:

• FoxPro-friendly: RenderWithDictionary(Hashtable), ValidateAndRender (warning v property)
• .NET-only: RenderWithTranslator(IDictionaryTranslator), ValidateAndRenderWithWarnings(out warnings), RenderToStream(Stream)

Sloupec „FoxPro" v tabulce ukazuje, co si může FoxPro klient zavolat. ❌ neznamená, že je metoda špatná — jen že má smysl jen v .NET kontextu. Pojmenování zůstává unikátní (ne overloady), aby se při budoucích úpravách FoxPro klienti neporanili při náhodném loBuilder.Render(...) se 3+ parametry, kdy by wwDotnetBridge mohl resolvovat na .NET-only overload.

outputPath: přípona určuje formát — .html, .pdf, .xlsx, PRINTER: (tisk) jsonOrFile: začíná { → JSON string, jinak → cesta k souboru xmlOrFile: začíná < → XML string, jinak → cesta k souboru format (pro Stream): "pdf", "html", "xlsx"

Statické pomocné metody

Properties pro mezivrstvu

PDF generování

Přes WebView2 (HTML → PDF)

Přímé PDF (MigraDoc) — bez WebView2, vysoký výkon

XLSX generování (ClosedXML)

E-mailové HTML

Pro rozesílání sestav/faktur e-mailem je potřeba HTML, které snesou e-mailoví klienti — inline CSS (mnozí klienti strhávají <style>), bez <script>/@media/@page, vše v jednom souboru (obrázky base64). Toho dosáhneš dvěma způsoby:

1. Property EmailMode — přepne HTML výstup Render() na e-mailovou variantu:

loBuilder.EmailMode = .T.
loBuilder.Render("faktura_email.html", "sablona.json")   && inline CSS, single-file
loBuilder.EmailMode = .F.

2. Metoda ToEmailHtml(html) — převede libovolné hotové HTML:

lcHtml = loBuilder.ToTableReportHtml(lcJson)     && nebo jakékoliv HTML
lcEmail = loBuilder.ToEmailHtml(lcHtml)

Co konverze dělá: posbírá pravidla z <style>, inlinuje je na elementy (cascade: tag → třídy → existující inline), odstraní <script>, @media, @page, složené selektory (table.dt th) ponechá v slim <style> v <head> (webmail je ctí).

Nejlépe funguje na tabulkové sestavy (jsou <table>-based → korektní i v desktopovém Outlooku). Dokumenty s flex layoutem (faktury) se ve webmailu (Gmail, Apple Mail, web Outlook) zobrazí správně; v desktopovém Outlooku se flex zjednoduší — pro e-mail volte jednodušší šablony.

FRX konvertor

Auto-detekce typu (table/document) z FRX někdy klasifikuje špatně. Varianty s vynuceným typem (TableReport/Document v názvu) toto obcházejí.

Generování JSON šablon z cursor schema

Generování JSON šablon pro tabulkové sestavy přímo z definice FoxPro kurzoru (cursor schema). Vstupem je string se schématem tabulky a volitelné parametry — výstupem je JSON s odhadnutými šířkami sloupců v mm.

cursorSchema: Dva podporované formáty:

• CREATE TABLE: "CREATE TABLE U (Den D, Rada C(2), Castka N(15,2))"
• Plain: "Den D,Rada C(2),Castka N(15,2)"

options: Řetězec "key1:value1,key2:value2,..." s konfigurací:

Escape sekvence v options stringu

Options string používá : a , jako oddělovače. Pro hodnoty obsahující tyto znaky použijte zpětné lomítko:

Příklady:

title:Přehled faktur\, Q1 2026,orientation:landscape
tfiltr:Datum\: 2026-01-01..2026-03-31
sumLabel:Celkem\, netto,lang:cs

Lokalizační defaulty

Individuální sumLabel/groupSumPrefix/pageLabel/printedLabel v options vždy přebijí default z lang.

Tisk

Jednorázový tisk

Utility

Batch tisk / PDF

Batch se řídí přes property BatchOutput — viz sekce Properties.

Generování dokumentových šablon z XML dat

Automatické generování JSON šablon pro dokumentový renderer ("renderer": "document") z XML dat. Heuristická analýza XML struktury — detekce archetypu (faktura/dopis/protokol), klasifikace elementů, generování bloků.

options: Řetězec "key1:value1,key2:value2,..." s konfigurací (nebo "" pro výchozí):

Auto-detekce archetypu (pokud type není zadán):

Příklad:

*--- Vrátí JSON string ---
lcJson = loBuilder.GenerateDocumentFromXml("type:faktura,title:Faktura")

*--- Uloží přímo do souboru (řeší cp1250/UTF-8) ---
loBuilder.GenerateDocumentFromXmlToFile("C:\json\faktura.json", "type:faktura,title:Faktura")

*--- Z externího XML souboru ---
loBuilder.GenerateDocumentFromXmlFile("C:\json\faktura.json", "C:\data\data.xml", "")

VS Code editor

OpenReportEditorNew — pre-fill + editor v jednom kroku:

Pokud JSON soubor existuje a není prázdný, otevře se bez přegenerování (existující práce se nepřepisuje).

Příklad:

*--- Nový dokument (faktura) ---
loBuilder.OpenReportEditorNew("C:\json\nova_faktura.json", "C:\data\sample.xml", "document")

*--- Nová tabulková sestava ---
loBuilder.OpenReportEditorNew("C:\json\nova_sestava.json", "C:\data\sample.xml", "table")

VS Code snippety: Při otevření editoru se automaticky generuje .vscode/blocks.code-snippets s 26 snippety. Prefix doc- pro dokumentové bloky (header, info-grid, table, total, text, signature, separator, spacer, image, qr, columns, form-table, page-break), prefix rep- pro tabulkové struktury (column, column-expr, column-template, group, sum, sumrows, footer-row, lookup, row-style, header-rows, page-header, page-footer, section).

Markdown → HTML

Přímý export XML → JSON / CSV / XML (bez šablony)

Třída DataExporter — statická utilita pro rychlý export XML dat do běžných formátů bez nutnosti JSON šablony. Ideální pro User Reports, kde uživatel chce data rovnou do Excelu nebo systému třetí strany.

Export z XML stringu

Export z XML souboru

Chování

• JSON: Opakované sourozenecké elementy (≥ 2 elementů se stejným jménem) se emitují jako pole. Hodnoty vypadající jako číslo nebo true/false se emitují bez uvozovek. Ostatní jako JSON string s escapováním.
• CSV: Hledá první opakovanou kolekci (BFS — ≥ 2 elementů se stejným jménem) a emituje ji jako tabulku. První řádek = header (názvy elementů prvního výskytu), další řádky = data. Hodnoty se escapují dle RFC 4180 (obalí uvozovkami, pokud obsahují ;, ", \r nebo \n; vnitřní " se zdvojí). UTF-8 BOM pro správné rozpoznání diakritiky v Excelu.
• XML: Načte, zvaliduje a uloží s UTF-8 deklarací a " " odsazením.
• Všechny metody vrací bool a chybu přes out string errorMessage (prázdný string při úspěchu).

Příklad

string err;
bool ok = DataExporter.ExportToCsv(@"C:\export\faktury.csv", xmlString, out err);
if (!ok) MessageBox.Show(err);

*-- Z FoxPro přes wwDotnetBridge
LOCAL lcErr
lcErr = ""
llOk = loBridge.InvokeStaticMethod("XmlStackBuilder.Core.DataExporter", "ExportFileToCsv", ;
    "C:\export\faktury.csv", "C:\data\faktury.xml", @lcErr)

Poznámky

• Chybové hlášení: Většina metod vrací bool. Při false viz HtmlErrorMessage.
• JSON parametry: jsonOrFile — začíná { → JSON string, jinak cesta k souboru.
• XML parametry: xmlOrFile — začíná < → XML string, jinak cesta k souboru.
• FoxPro: Žádné přetěžování metod (overloading) — každá metoda má unikátní název.
• Reset() vymaže XML, zachová batch stav a tiskové properties.
• EndBatch() vyčistí batch stav, zachová tiskové properties.
• ResetPrint() vyčistí tiskové properties, netkne se XML ani batch stavu.