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

Velké kurzory: data přímo z DBF (AddElementFromDbf, od 1.1.190)

CURSORTOXML + AddElementWithXmlContent u velkých kurzorů (desítky tisíc řádků, XML desítky MB) ve 32bitovém FoxPro padá na paměti: řetězec se přes wwDotnetBridge převádí do .NET a znovu parsuje. AddElementFromDbf čte tabulku (DBF + FPT memo) přímo ze souboru:

• řádky <row …/> jsou shodné s CURSORTOXML(alias, …, 3, 16) — názvy polí malými písmeny, čísla jak leží v souboru (3048.02), datum yyyy-MM-dd, prázdné datum "", logické true/false, NULL = atribut chybí;
• soubor se otevírá sdíleně (může zůstat otevřený ve FoxPro), čte se do konce souboru i při zastaralém počtu vět v hlavičce (od 1.1.191);
• návrat = počet řádků; -1 = chyba, text v LastDbfError, do dokumentu se nic nevloží.

Doporučený postup (ověřený ve FoxPro): COPY TO do dočasné tabulky. Ctí aktivní pořadí, filtr, SET DELETED i klauzule FOR / FIELDS a zapíše i věty, které FoxPro drží jen v paměti — výsledek tak odpovídá tomu, co by vydal CURSORTOXML. Aktuální větu kurzoru COPY TO posune, proto se před ním uloží a po něm vrátí:

Select (lcAlias)
lnRecno = RECNO()
lcTmp = jmenos(ALIAS(), 1)          && dočasný název tabulky i s příponou .dbf

Copy To (m.lcTmp)                   && případně &tcKlauzule. &tcPole.

If Between(m.lnRecno, 1, Reccount())
	Go m.lnRecno
Else
	Locate                          && byl EOF / prázdný kurzor / nová věta v bufferu -> první věta
Endif

lnRows = loBuilder.AddElementFromDbf("data", m.lcTmp)
* surový export: lnRows = loBuilder.ExportDbfToXlsx(m.lcTmp, lcXlsx, "sheet:Data,bool:Ano;Ne")

Erase (m.lcTmp)
If File(Forceext(m.lcTmp, "fpt"))
	Erase (Forceext(m.lcTmp, "fpt"))
Endif

IF m.lnRows < 0                     && chyba (LastDbfError / LastXlsxError) -> postaru přes CURSORTOXML
	CURSORTOXML(lcAlias, "lcXml", 3, 16)
	loBuilder.AddElementWithXmlContent("data", m.lcXml)
ENDIF

Přímé čtení DBF(alias) bez kopie (kurzor READWRITE, bez ORDER()/FILTER(), FLUSH IN … FORCE) je možné, ale závisí na stavu kurzoru; tisková třída používá kopii výše.

Surový export do XLSX z DBF (od 1.1.192): ExportDbfToXlsx(dbfPath, xlsxPath, options) — místo CURSORTOXML(…, 512+…) + ExportCursorXmlToXlsxWithOptions. Typy sloupců bere z hlavičky DBF (stejné jako inline XSD), volby stejné (sheet:, autofilter:0, freeze:0, bool:Ano;Ne), návrat = počet řádků, -1 = chyba v LastXlsxError. S ShowProgress = .T. ukáže dialog „Export do XLSX“ (od 1.1.193; Storno = -1, soubor nevznikne). Saldokonto 135 tisíc řádků ve 32bitovém procesu: 26 s, 220 MB.

Render pak (od 1.1.191) předá data rendererům tabulek přímo, bez převodu na text: saldokonto 135 tisíc řádků ve 32bitovém procesu ~0,8 GB, PDF ~6 minut (viz CHANGELOG 1.1.190–1.1.193).

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).

Tabulková šablona může obsahovat sekci "flatten" — deklarativní zploštění hlubokého XML (elektronická podání JMHZ/HOZ/PPPZ/REGZEC/DPH) na ploché tabulky přímo při renderování, vč. filtru na jeden záznam přes SetRenderParam (karta pracovníka) a formátování hodnot. Popis viz TABLE_REPORT_RENDERER_JSON.md → „flatten", hotové šablony v docs/priklady/. Jména osob (JMHZ je neobsahuje) čte flatten ze souboru <xml>.labels vedle datového XML.

Šablona může dědit (od 1.1.144): "extends": "_base/table.json" na kořeni a { "$include": "x.json" } kdekoli v objektu; cesty se řeší relativně k souboru šablony (RenderContext.TemplateDir, nastaví se při předání cesty), u šablony předané jako řetězec relativně k aktuální složce; když soubor vedle šablony není, hledá se v záložní složce TemplateFallbackDir (od 1.1.177 — uživatelská kopie v json_local dědí ze základu v repo_json). Pravidla slučování a konverze složek (xsb factor) viz TABLE_REPORT_RENDERER_JSON.md → „Dědičnost šablon".

If !loBuilder.CheckTemplate("repo_json\frx_saldo07.json", "c:\temp\saldo.xml")
   Messagebox(loBuilder.LastCheckReport)
Endif

Akce „zkontrolovat šablonu“ v tiskové třídě (programátor; v tiskall je to nAkce = 90, nasazeno 25. 9. 2026): projde stejná cesta jako tisk (data, výběr šablony vč. json_local a záložní složky), na konci místo renderu kontrola nad skutečnými daty:

This.jfrx_builder.SaveToFile(This.jfrx_builder.FrxXmlDataPath)
This.jfrx_builder.CheckTemplate(This.jfrx_jsonFile, This.jfrx_builder.FrxXmlDataPath)   && JSON i .md
lcHtml = Forceext(This.jfrx_builder.FrxXmlDataPath, "check.html")
If This.jfrx_builder.WriteCheckReportHtml(m.lcHtml)
	gourl(m.lcHtml)
Else
	Messagebox(This.jfrx_builder.LastCheckReport, 48, Transform(This.jfrx_builder.LastCheckErrors) + " chyb", 3000)
Endif

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)

XLSX šablona — plnění existujícího sešitu

Naplní data do existující XLSX šablony (zachová hlavičky a formátování) — na rozdíl od XLSX generování, které vytváří nový sešit z JSON definice. Typické použití: portálové import-šablony (např. objednávky stravenek), kde řádky 1–2 jsou hlavičky/popisky a data se vkládají od řádku 3.

Chování:

• Plní se kopie šablony do outputPath — originál zůstává nedotčený.
• Mapování sloupců podle pořadí (1. pole řádku → A, 2. → B …) — pole kurzoru musí být ve stejném pořadí jako sloupce šablony.
• Staré datové řádky od startRow dolů se vyčistí (obsah, formátování zůstává).
• Typování buněk: číslo → reálné Excel číslo, ISO datum (YYYY-MM-DD) → datum, jinak text; kódy s vedoucí nulou zůstanou textem.
• Řádky se v XML hledají robustně — funguje tvar <rows>/<row> i přímý CURSORTOXML() výstup (řádky pojmenované dle aliasu kurzoru).

* kurzor -> XML (element-centric: nFormat = 1), pole v pořadí sloupců šablony
SELECT objednavky
CURSORTOXML("objednavky", "lcXml", 1, 0, 0, "")

loXsb = loBridge.CreateInstance("XmlStackBuilder.Core.XmlStackBuilder")
loXsb.CreateRoot("objednavka")                    && NEJDŘÍV root (Push ho nezakládá)
loXsb.AddElementWithXmlContent("radky", lcXml)    && strhne <?xml?> i <VFPData>

IF !loXsb.FillXlsxTemplate("sablona.xlsx", "vystup.xlsx", 3, "")
    MESSAGEBOX("Chyba: " + loXsb.LastXlsxError, 16)
ENDIF

Pozor: root dokumentu musí existovat před AddElementWithXmlContent — použij CreateRoot("...") nebo konstruktor CreateInstance("...XmlStackBuilder", "root"). Samotný Push root nezakládá.

Personalizace šablony (statické metody)

Pro šablony určené k vyplnění a návratu (sběrové formuláře — např. výkazy firem skupiny v programu Konsolidace): zápis jednotlivých buněk, výměna bloku řádků (číselník), doplnění hodnot podle klíče a zamknutí listů heslem. Všechny metody jsou statické na XmlStackBuilder.Core.XlsxTemplateFiller, pracují přímo nad zadaným souborem (kopii šablony si předem vyrobí volající, např. COPY FILE), datové vstupy jsou XML z CURSORTOXML(…, 1, 0) s poli po řadě.

* personalizace kopie sablony (FoxPro pres wwDotnetBridge)
COPY FILE (lcSablona) TO (lcVystup)

SELECT Alltrim(kod) + " | " + Alltrim(nazev) AS comb, kod, nazev, ico ;
    FROM firmy WHERE rok = lcRok INTO CURSOR curfir
CURSORTOXML("curfir", "lcXml", 1, 0)
lnN = loBridge.InvokeStaticMethod("XmlStackBuilder.Core.XlsxTemplateFiller", ;
    "FillSheetRowsFromXml", lcVystup, "Číselníky", 2, 1, lcXml)
lcErr = loBridge.GetStaticProperty("XmlStackBuilder.Core.XlsxTemplateFiller", "LastError")

loBridge.InvokeStaticMethod("XmlStackBuilder.Core.XlsxTemplateFiller", ;
    "ProtectAllSheets", lcVystup, lcHeslo)

Reálné nasazení: GEN_XLSX.PRG programu Konsolidace (titulní strana, číselník firem, minulé období z deníku roku−1 podle klíče, zámek heslem z parametru).

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.ToTableReportWithMetadata(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

Od 1.1.148 konvertor překládá „Print When" (supexpr) do visibleWhen (FrxConditionTranslator: .and./.or./.not., empty(), inlist() → IN, .t./.f., $ → LIKE, aliasy hlava.x → header.x, otiskserv.otiskobjekt.x → header.x); co nejde přeložit (m. proměnné, _pageno, recno()), zůstává jen v anotaci _printWhen. U sloupců sestavy vzniká visibleWhen pouze z hlavičkové podmínky (řádková by skryla celý sloupec). Dědičnost: existuje-li v cílové složce _base\<typ>.json, zapíše se šablona jako potomek s "extends" a jen odlišnostmi (vzorové XML a PRG z úplné šablony). | ExtractLiteralsFromJson(jsonTemplate) | string | Extrahuje přeložitelné texty jako XML | | ExtractLiteralsFromJsonFile(jsonFilePath) | string | Totéž ze souboru |

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

Přímé čtení FRX/LBX souboru (bez FoxPro) — od 1.1.120

Všechna souborová API konvertoru (ConvertFrxToJsonFile, ConvertFrxToAllFiles, ConvertLbxToJsonFile, …) přijímají kromě XML exportu i rovnou cestu k .frx/.lbx souboru — mezikrok „otevři FRX ve FoxPro a exportuj CURSORTOXML" odpadá:

*-- Dřív (tiskserver, jfrx_convertfrxtojson):
*   USE report.frx ALIAS tmpReport SHARED AGAIN
*   CURSORTOXML("tmpReport", "lcXml", 3, 16) + STRCONV + STRTOFILE do temp XML
*   loBuilder.ConvertFrxToJsonFile(m.lcXmlFile, m.lcJsonFile)
*-- Teď stačí:
loBuilder.ConvertFrxToJsonFile("repo\saldo11.frx", "repo_json\frx_saldo11.json")
loBuilder.ConvertFrxToAllFiles("c:\reporty\CENIK.FRX", "c:\vystup\")   && json + sample.xml + prg

Jak to funguje:

• Detekce podle obsahu souboru (textový soubor začínající < = XML export jako dřív, cokoli jiného = VFP tabulka) — stará XML cesta funguje beze změny.
• FRX/LBX je obyčejná VFP tabulka (DBF + FRT/LBT memo). XSB ji čte vlastním minimálním DBF parserem (FrxNativeReader) — před čtením se frx+frt zkopírují do tempu a čte se kopie (FileShare.ReadWrite), takže nevadí, že soubor drží běžící FoxPro nebo otevřený report designer. FRT/LBT musí ležet vedle tabulky.
• Smazané záznamy (0x2A) se přeskakují — report designer jimi značí odstraněné objekty, VFP report engine je ignoruje taky. XML export přes CURSORTOXML je naopak zahrne, pokud FoxPro nemá SET DELETED ON — přímé čtení je tedy o chlup věrnější.
• Kódová stránka dle LDID bajtu hlavičky (0xC8 = windows-1250 atd.), memo pointer VFP (int32) i dBase (ASCII) tvar, kumulativní offsety polí.
• Pro diagnostiku je k dispozici FrxConverter.ReadFrxFileToXml(frxPath) (.NET) — vrátí atributové XML ve tvaru CURSORTOXML(…, 3, …).

Volba typu (od 1.1.121): štítek se konvertuje VÝHRADNĚ podle přípony .lbx (u souborového vstupu) nebo přes ConvertLbx* metody. Dřívější auto-detekce „header objcode=53 = label" byla chybná — hlavičkový záznam objtype=1/objcode=53 má každý FRX i LBX (ověřeno na 1 636 FRX + 79 LBX z MANW/repo), takže auto API konvertovalo od 3/2026 všechno včetně faktur jako štítek. U XML stringu bez přípony se auto-detekuje jen table/document.

Výjimka — obálky a štítky uložené jako .frx (1.1.131): adresa na obálku se v tabulkovém ani dokumentovém rendereru nedá vysázet správně, potřebuje absolutní pozicování. Takové reporty se proto poznají podle geometrie a jdou do label rendereru: všechny bandy kromě detailu prázdné, detail band nad 60 mm, do 12 objektů, žádné kreslené čáry. Kritérium bylo změřeno na 2 012 FRX — vybere 58 souborů a rozlišuje i uvnitř jedné rodiny názvů (AOBALDLL = obálka → štítek, AOBALDL = poštovní arch → tabulka). Nejde o návrat k chybě z 1.1.121: rozhoduje geometrie celého reportu, ne příznak v hlavičce. MLINE(pole, n) se převede na formát MLn:šířka, par.get_par("x") na {parametr.x}.

Kvalita dokumentové konverze (1.1.122–1.1.132, viz docs/navrhy/NAVRH_FRX_DOKUMENTY_2026-08.md): hlavička faktury z PageHeader/Title bandu se už nezahazuje (popiskový pruh = spodní řádkový cluster), popisky sloupců se párují překryvem x-intervalů (popisek PŘED hodnotou se správně nepáruje jako záhlaví sloupce), hranice a poměr dvousloupcového layoutu se počítají z reálných souřadnic (největší vodorovná mezera; ratio z naměřených rozsahů, ne „50:50").

Od 1.1.129 dál:

⚠️ Výstup je startovací bod, ne hotová šablona. Konvertor nemůže odvodit lookupy na číselníky ({osnova.nazev} u čísla účtu), nadpisy stran hlavičky („DODAVATEL"/„ODBĚRATEL" ve FRX nejsou), sloupce, které ve starém reportu chyběly, ani rozdělení rekapitulací do samostatných tabulek.

Pozn.: nejde o obecné čtení DBF dat (to zůstává v ComsysNetSupportLib — mezi knihovnami se závislost nezavádí; tady je jen minimální interní kopie čtecí logiky pro FRX/LBX).

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

Bloky ```mermaid se v HTML vykreslí jako diagramy (Mermaid runtime se injektuje jen když dokument diagram obsahuje; zdroj lze přepnout na lokální mermaid.min.js env proměnnou XSB_MERMAID_SRC — offline prostředí). Od 1.1.101, platí i pro xsb md a net48 Cli.exe --md.

Přímý export XML → JSON / CSV / XML / XLSX (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

Surový export do XLSX (ExportToXlsx / fasáda ExportCursorXmlToXlsx)

Náhrada za COPY TO … TYPE XL5 a exporty přes Excel COM: jeden list, první řádek = názvy sloupců (tučně, zmrazený, autofiltr), typované buňky (datum jako datum, čísla jako čísla, logické jako boolean), šířky sloupců podle obsahu. Bez JSON šablony — formátované sestavy dělá XlsxTableReportRenderer.

FoxPro fasáda (instanční, wwDotnetBridge-friendly):

xmlOrFile — začíná < → XML string, jinak cesta k souboru. options — "klíč:hodnota" oddělené čárkou:

Logické hodnoty: bez volby se zapíše nativní boolean buňka — Excel ji zobrazí jako PRAVDA/NEPRAVDA (dle jazyka Office) a filtruje ji jako logickou hodnotu. Volba bool: zapíše místo toho text ve stejné konvenci "trueText;falseText", jakou používá format sloupce v JSON šablonách (TableReportModel.ApplyBoolFormat): bool:Ano;Ne, bool:A;N, bool:x; (true = „x", false = prázdno), bool:[✓];[–]. Formát bez ; je chyba (ne tiché ignorování). Ostatní typy sloupců volba neovlivní.

Proč XML z CURSORTOXML (a ne DBF/CSV): XSB záměrně neumí číst DBF (DbfReader je v ComsysNetSupportLib — závislost mezi knihovnami se nezavádí) a CSV cestou by se ztratily datové typy (vše by byl text, nebo by se muselo hádat).

Do proměnné, nebo do souboru? Fasáda pozná obojí (xmlOrFile — začíná < → XML string, jinak cesta k souboru):

Pro běžné sestavy je proměnná lepší volba; na soubor sáhněte u opravdu velkých kurzorů.

Inline XSD schéma zapíná 6. parametr cSchemaName = "1" (ne flag — viz VFP help _5wn12pq2w). V XML je pak přesný popis sloupců: typ (xsd:date, xsd:decimal, xsd:boolean, xsd:int, xsd:string), počet desetinných míst (fractionDigits → formát buňky, např. 0.00) i pořadí sloupců kurzoru. Čte se z obou tvarů — atributového (nOutputFormat 3) i element-centrického (1). Hodnoty jsou v invariantním tvaru (ISO datum, desetinná tečka), takže nezáleží na SET POINT.

Bez schématu export funguje taky, ale typy se odhadují konzervativní heuristikou po sloupcích — sloupec je typovaný, jen když VŠECHNY neprázdné hodnoty odpovídají stejnému typu; kódy s vedoucí nulou („0123", VS, kód obce) zůstanou textem. Schéma je proto doporučené: jen s ním se do výstupu dostanou i sloupce prázdné ve všech řádcích a logická pole s hodnotami 1/0 (bez schématu je heuristika nechá číslem — příznak od čísla nelze poznat).

⚠️ Kódovací past CURSORTOXML — týká se JEN výstupu do souboru: bez encoding flagů (bity 16/32 = 0) VFP zapíše bajty v ANSI kódové stránce stroje (v ČR windows-1250), ale do deklarace dá encoding="Windows-1252" — č se pak přečte jako è, ř jako ø. Od 1.1.111 to ExportFileToXlsx řeší samo (deklarace „Windows-1252" → dekóduje ANSI stránkou stroje), přesto do souboru vždy přidávejte +48 (UTF-8 s překladem) nebo +16 (deklarovaná stránka kurzoru), ať je soubor korektní i pro jiné konzumenty.

*-- Běžný případ: přes proměnnou (konvence tiskserveru — atributové XML + inline schéma)
LOCAL lcXml, lnRows
lcXml = ""
CURSORTOXML(Alias(), "lcXml", 3, 16, 0, "1")
lnRows = loBuilder.ExportCursorXmlToXlsxWithOptions(m.lcXml, "C:\export\prehled.xlsx", "bool:Ano;Ne")
IF m.lnRows < 0
    ? loBuilder.LastXlsxError
ENDIF

*-- Velký kurzor: přes soubor (bez 16MB limitu stringu)
LOCAL lcTmp
lcTmp = Addbs(Sys(2023)) + Sys(2015) + ".xml"
CURSORTOXML(Alias(), m.lcTmp, 3, 512 + 48, 0, "1")
lnRows = loBuilder.ExportCursorXmlToXlsx(m.lcTmp, "C:\export\prehled.xlsx")
ERASE (m.lcTmp)

Poznámky: NULL (vynechaný element) → prázdná buňka; formát čísel dle fractionDigits bez tisícového oddělovače (roky a kódy se nezobrazí jako „2 026"); datum dd.mm.yyyy; šířky sloupců se měří z prvních 1000 řádků, strop 60 znaků; název listu se ořeže na 31 znaků.

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.