Plugin na generovanie výstupov pomocou šablón v Microsoft Word (Mail merge – Hromadná korešpondencia) a v Microsoft Excel (marker symbol). Výstup je možné vygenerovať aj ako PDF.

Obsah:

Microsoft Word

Microsoft Excel

Microsoft Word

Na tvorbu reportu sa používajú polia z hromadnej korešpondencie, tzv. MERGEFIELD. Hodnoty v nich su nahradené buď podľa poskytnutých údajov alebo podľa pravidiel v MERGEFILED-och.

Pridanie MERGEFIELD-u: vo Worde -> Vložiť -> Rýchle časti -> Pole, v kategórii si vyberieme Hromadná korešpondencia a v Názvy polí vyberieme MergeField. Vedľa v Názov poľa dáme systémový názov a dáme OK.

Parametre dátového zdroja:

Názov parametra	Popis
@Template	Word súbor, ktorý obsahuje šablónu, môže tento parameter buď obsahovať cestu na súbor (z pohľadu brány) alebo binary data takéhoto súboru (získané napr. SELECT-om cez getter)
@ReturnPDF	true/false – či sa má výsledný report vrátiť ako PDF súbor. Default hodnota false
@Filename	Názov výsledného súboru
@Data	Údaje pre jednoduchý mail merge. Môže byť buď vo forme JSON objektu poľa názvom a poľa hodnôt (pozri príklady) alebo SELECT, ktorý sa má vykonať voči SQL pripojeniu brány. Názvy stĺpcov sa následne používajú v MERGEFIELD-och. Tento parameter môže byť použitý viackrát s tým, že sa pridá jedinečný identifikátor za jeho názov napr. @DataZamestnanec, @DataVlastnaFirma atď.
@GroupData<GroupName>	Údaje pre mail merge so skupinou. Môže byť buď vo forme JSON objektu tabuľky (pozri príklady) alebo SELECT, ktorý sa má vykonať voči SQL pripojeniu brány. Názvy stĺpcov sa následne používajú v MERGEFIELD-och
@NestedGroupData<GroupName>	Údaje pre mail merge s vnorenými skupinami, kde sa podriadená filtruje pomocou podmienky na základe údaju z nadriadenej. Môže byť buď vo forme JSON objektu tabuľky (pozri príklady) alebo SELECT, ktorý sa má vykonať voči SQL pripojeniu brány. Názvy stĺpcov sa následne používajú v MERGEFIELD-och
@NestedGroupCondition<GroupName>	Podmienka, ktorá slúži na vytvorenie väzby s nadriadenou skupinou. V hlavnej skupine alebo ak nepoužívate vnorené skupiny, sa necháva prázdne
@NestedGroupStartAtNewPage	true/false – či sa má skupina záznamov začínať na novej strane. Default hodnota false
@ClearFields	true/false – či sa majú vymazať z výsledného reportu nepoužité MERGEFIELD-y. Default hodnota true (POZOR – v prípade, že máte viacero skupín, tak je potrebné nastaviť na false, inak pri použití prvej skupiny sa vymažú prípadné polia pre ďalšiu skupinu)
@RemoveEmptyGroup	true/false – či sa majú vymazať prázdne skupiny, ktoré obsahujú nezlúčené MERGEFIELD-y
@RemoveEmptyParagraphs	true/false – či sa majú vymazať odstavce, ktoré obsahujú nezlúčené MERGEFIELD-y
@ReturnDataResults	true/false – či sa majú vo výslednej tabuľke vrátiť aj hodnoty z jednotlivých dátových zdrojov (@Data a @NestedGroupData). Default hodnota false
@Culture	Miestne nastavenie, ktoré sa má použiť pri formátovaní údajov – 2 znaková skratka, napr. cs, sk, en, de atď.
@VerboseLog	true/false – zapnutie/vypnutie podrobného logovania. Logovanie sa deje do internej databázy, do tabuľky pe1_msreports_log

Kódy polí

Stlačením Alt + F9 zobrazia polia namiesto kódov polí a opačne.

Jednoduchý príklad

Dokument so šablónou môže vyzerať napr. nasledovne:

Plugin nahradí MERGEFIELD-y poskytnutými údajmi z parametra @Data. V parametri @Data je možné použiť buď SELECT z tabuľky s údajmi

Príklad SELECT-u pre zobrazenú šablónu:

SELECT TabCisZam.Cislo AS [EmployeeID], TabCisZam.PrijmeniJmeno AS [Name], Mobil.Spojeni AS [Phone], TabCisZam.AdrTrvMisto AS [City]
FROM TabCisZam
LEFT OUTER JOIN TabKontakty Mobil WHERE TabCisZam.ID=Mobil.IDCisZam AND Mobil.Prednastaveno=1 AND Mobil.Druh = 2
WHERE TabCisZam.ID = @ID

alebo JSON zápis objektu s poľom názovou polí a poľom hodnôt:

{    
    "FieldNames": ["EmployeeID","Name","Phone", "City"],
    "FieldData": ["1","Mrkvička Ferko","<b>090X XXX XXX</b> <br/> <span style=\"color: red;\">Nevolať medzi 8-16</span>", "Bratislava"]
}

Vytvorenie šablóny pre vnorené skupiny

Oblasť, kde bude použítá Mail merge musí byť označená dvomi MERGERFIELD s nasledujúcimi názvami:

• «BeginGroup:GroupName» – pre začiatok oblasti
• «EndGroup:GroupName» – pre koniec oblasti

Príklad šablóny:

Príklad parametrov pre zobrazenú šablónu:

Máme v šablóne 2 skupiny Customers a Orders, takže potrebujeme 2 dvojice parametrov.

@NestedGroupDataCustomers – v hodnote môže byť napísaný napr. takýto SELECT:

SELECT ID AS CustomerID, ContactName, CompanyName, City, Country FROM TabCustomers

alebo JSON zápis objektu tabuľky:

{     
    "Customers": [
        {"CustomerID": "1", "ContactName": "Mrkvička Ferko", "CompanyName": "Moja s.r.o.", "City": "Bratislava", "Country": "Slovensko"},
        {"CustomerID": "2", "ContactName": "Hraško Janko", "CompanyName": "Tvoja s.r.o.", "City": "Bratislava", "Country": "Slovensko"}
    ]
}

@NestedGroupConditionCustomers – prázdny

@NestedGroupDataOrders – hodnote zapísaný SELECT:

SELECT CustomerID, OrderID, OrderDate, ShippedDate, RequiredData FROM TabOrders

@NestedGroupConditionOrders – zadajte podmienku napr. CustomerID = %Customers.CustomerID%

Výsledný report bude vyzerať nasledovne:

Vloženie obrázku

{ MERGEFIELD Image:Signature \* MERGEFORMAT } – Signature je názov poľa zo zdroju údajov.

Nastavenie šírky, výšky a pomeru strán (width\height\keep aspect ratio):

{ MERGEFIELD Image:Signature \*w(100) \*h(200) \*a(true) }

Obrázok ak hodnota poľa je URL adresa:

{ MERGEFIELD Image:Signature \*url \*w(100) \*h(200) \*a(true) }

Formátovanie hodnoty poľa

Ak chcete použiť vlastné formátovanie na pole dátumu, číslo alebo text v mail merge, pridajte \* a kód prepínača formátovania:

1. Vyberte pole hromadnej korešpondencie, napríklad Company, ako je znázornené v tomto príklade.
2. Stlačením [Alt] + F9 zobrazíte kódovanie poľa. Alebo kliknite pravým tlačidlom myši na pole a vyberte možnosť Prepnúť kód poľa (Toggle Field Code). Teraz by ste mali vidieť skutočný kód poľa pre pole, ktorý by mal vyzerať ako { MERGEFIELD Company }.
3. Upravte pole vložením kódu prepínača na koniec poľa. Napríklad, ak chcete použiť formát textu na zmenu na veľké písmená, upravte pole tak, aby sa zobrazovalo ako { MERGEFIELD Company \*Upper } (pozrite si ďalšie príklady formátovania textu a dátumu nižšie).
4. Znova stlačte [Alt] + F9.
5. Umiestnite kurzor kdekoľvek v tomto poli a stlačením funkčného klávesu [F9] aktualizujte ho. Alebo kliknite pravým tlačidlom myši na pole a vyberte možnosť Aktualizovať pole (Update Field).

Možnosti pre prepínač poľa textovej hromadnej korešpondencie

Ak chcete použiť formátovanie textu, použite prepínač formátu textu \* nasledovaný požadovanými výrazmi pre daný prípad.

Word Result	Kód poľa	Požadovaný výsledok	Zobrazený výsledok
UPPER CASE	{ MERGEFIELD Name \*Upper }	Všetky písmená sú veľké	MICROSOFT WORD JE ÚŽASNÝ!
lower case	{ MERGEFIELD Name \*Lower }	Transformuje všetky písmená na malé	microsoft word je úžasný!
Title Case	{ MERGEFIELD Name \*Caps }	Napíše prvé písmeno každého slova na veľké	Microsoft Word je úžasný!
Sentence case	{ MERGEFIELD Name \*Lower \*FirstCap }	Veľké iba prvé písmeno prvého slova (použite oba zobrazené prepínače)	Microsoft Word je úžasný!

Poznámka: Prepínače nerozlišujú veľké a malé písmená.

Možnosti prepínača poľa Dátum hromadnej korešpondencie

Ak chcete použiť vlastné formátovanie dátumu na pole hromadnej korešpondencie dátumu, použite prepínač formátu dátumu a času \@ a pridajte požadované výrazy pre deň, mesiac a rok v úvodzovkách (pozrite si príklady nižšie).

Switch	Popis
yyyy	Rok. Použite yy na zobrazenie posledných dvoch číslic ktoréhokoľvek roku. Použite rrrr na zobrazenie všetkých štyroch číslic ktoréhokoľvek roku.
M	Mesiac. Použite MMMM na úplné vyjadrenie mesiaca (napríklad september alebo október). Použite MMM na zobrazenie trojpísmenovej skratky mesiaca (napríklad Sep, Oct). Použite MM na zobrazenie mesiaca v dvoch čísliciach s nulou na začiatku pre jednociferné mesiace (napríklad 09, 10). Použite M na zobrazenie mesiaca v čísliciach (napríklad 9, 10).
d	Day. Use dddd to spell out the day of the week (such as Sunday or Monday). Use ddd to display the three-letter abbreviation of the day ( such as Sun, Mon). Use dd to display the day in two digits with a leading zero for single-digit days ( such as 09, 10). Use d to display the day in digits ( such as 9, 10).
h	Hour. Use hh for 24 hour format
m	Minute. Use mm for 2-character format

Poznámka: Výrazy d, M, y, h, m môžu byť usporiadané v rôznom poradí, ale použitie veľkého písmena „M“ pre mesiace je dôležité, pretože malé písmeno „m“ sa používa pre minúty. Je tiež možné pridať text (napríklad /, -, …) a medzery; len sa uistite, že pridaný text zostáva v dvojitých úvodzovkách.

Príklady formátovania dátumu

Kód poľa	Zobrazené výsledky
{ MERGEFIELD Date \@ “dddd, MMMM d, yyyy” }	Sobota 9. júla 2022
{ MERGEFIELD Date \@ “MM/dd/yyyy” }	07/09/2022
{ MERGEFIELD Date \@ “M-d-yy” }	7-9-22
{ MERGEFIELD Date \@ “MMMM d, yyyy” }	júla 2022
{ MERGEFIELD Date \@ “dd.MM.yyyy HH:mm” }	09.07.2022 14:15

Príklady formátovania číselných polí

Nasledujú príklady číselných polí hromadnej korešpondencie formátovaných pomocou prepínačov. Prepínače čísel predvolene používajú zaokrúhľovanie.

Na zmenu formátovania číselného poľa na formát zobrazenia znaku dolára a vloženia čiarky ako oddeľovača tisícok sme použili nasledujúci prepínač:

{MERGEFIELD Salary \# $#,##0}

Na zmenu formátovania číselného poľa na zobrazenie čiarky ako oddeľovača tisícov a dvoch desatinných miest sme použili nasledujúci prepínač:

{MERGEFIELD SalesAmount \# #,##0.00}

Na zmenu formátovania číselného poľa tak, aby sa zobrazovalo číslo do tisíc s dvomi desatinnými miestami a číslo tisíc alebo viac s čiarkou ako oddeľovač tisícok, sme použili nasledujúci prepínač (výhodou tohto prepínača je, že Word nebude obsahovať medzeru pre chýbajúce číslice):

{MERGEFIELD AmountOwing \# ,#.00}

Nasledujúci prepínač možno použiť so zápornými číslami (ak bola pôvodná hodnota 1 500,57 alebo -1 500,57, zobrazí sa 1 500,57 USD pre kladné číslo a (1 500,57 USD) pre záporné číslo):

{MERGEFIELD AmountOwing \# “$,#.00;($,#.00)”}

Nasledujúci prepínač je podobný vyššie uvedenému prepínaču, ale formátuje nuly ako pomlčku (pomlčka sa považuje za text, takže musí byť uzavretá v jednoduchých úvodzovkách):

{MERGEFIELD AmountOwing \# “$,#.00;($,#.00);’-‘”}

Nulové hodnoty je možné potlačiť pridaním koncovej bodkočiarky (;) do prepínača, ale nič za ním. Toto potlačí nuly z prázdnych polí až k poliam obsahujúcim nuly.

Vo vyššie uvedených príkladoch by sa čiarky vložili iba vtedy, ak by číslo bolo tisíc alebo viac. Názov poľa na zlúčenie čísel vo vyššie uvedených príkladoch pochádza zo zdrojového súboru programu Excel. Zložené zátvorky nie je možné zadať.

Nakonfigurovanie riadkov nadpisov tabuľky Microsoft Word tak, aby sa opakoval na každej stránke

Prvý riadok ako nadpis tabuľky. Toto je riadok, ktorý by sa mal objaviť na každej stránke, na ktorej sa nachádza tabuľka.

Ak chcete nakonfigurovať, aby sa prvý riadok tabuľky opakoval na každej stránke, postupujte takto:

• Kliknite pravým tlačidlom myši do prvého riadka tabuľky a vyberte položku Vlastnosti tabuľky

• Na obrazovke Vlastnosti tabuľky kliknite na kartu Riadok, ak ešte nie je vybratá.
• Vyberte možnosť Opakovať ako riadok hlavičky v hornej časti každej stránky

• Kliknutím na tlačidlo OK potvrďte svoj výber.

Skrytie časti reportu v závislosti od vybranej hodnoty

Používa sa pravidlo If Then Else, napr.

{ IF { MERGEFIELD Age } > 18 “Over 18” “Under 18” }

POZOR zátvorky {} je potrebné pridať pomocou klávesovej skratky CTRL+F9!

Je možné takto skryť aj celý odsek, príp. tabuľku, ktorú nechcem zobraziť ak nemá žiadne riadky (musím si v niektorom sete spočítať počet riadkov a podľa podľa daného počtu cez IF bud skryť alebo zobraziť)

Príklad:

Definícia vo Worde

Microsoft Excel

Pre Microsoft Excel sa používajú špeciálne označenia (marker) pre napárovanie údajov na šablónu dokumentu.

Parametre dátového zdroja:

Názov parametra	Popis
@Template	Excel súbor, ktorý obsahuje šablónu, môže tento parameter buď obsahovať cestu na súbor (z pohľadu brány) alebo binary data takéhoto súboru (získané napr. SELECT-om cez getter)
@ReturnPDF	true/false – či sa má výsledný report vrátiť ako PDF súbor. Default hodnota false
@Filename	Názov výsledného súboru
@TableData<TableName>	Údaje pre jednoduchý mail merge. Môže byť buď vo forme JSON objektu tabuľky (pozri príklady) alebo SELECT, ktorý sa má vykonať voči SQL pripojeniu brány
@ReturnDataResults	true/false – či sa majú vo výslednej tabuľke vrátiť aj hodnoty z jednotlivých dátových zdrojov (@TableData). Default hodnota false

Syntax markerov šablóny

Každá značka začína znakom prefixu (štandardne je to znak „%“). Za značkou nasleduje názov premennej a vlastnosti/argumenty, ktoré sú oddelené znakom (štandardne je to bodkočiarka „;“.)

%<DataSource>.<FieldName> Napríklad: %TableDataCustomers.CompanyName Kde, “TableDataCustomers” je názov dátového zdroja podľa parametra @TableDataCustomers a CompanyName je názov poľa/stĺpca z daného dátového zdroja

Príklad šablóny:

Príklad parametrov pre zobrazenú šablónu:

@TableData – zapísané ako JSON objekt tabuľky:

{     
    "TableData": [
         {"ColName1": "Hodnota Riadku 1 stĺpca 1","ColName2": "Hodnota Riadku 1 stĺpca 2","ColName3": "Hodnota Riadku 1 stĺpca 3"},
         {"ColName1": "Hodnota Riadku 2 stĺpca 1","ColName2": "Hodnota Riadku 2 stĺpca 2","ColName3": "Hodnota Riadku 2 stĺpca 3"},
         {"ColName1": "Hodnota Riadku 3 stĺpca 1","ColName2": "Hodnota Riadku 3 stĺpca 2","ColName3": "Hodnota Riadku 3 stĺpca 3"}
    ]
}

alebo SELECT z tabuľky:

SELECT ColName1, ColName2, Colname3 FROM TabExample

Výsledný report bude vyzerať nasledovne:

Výsledok ako PDF (Generovanie PDF reflektuje všetky nastavenia strany v Excel šablóne, čiže napr. jednu tabuľku môžem mať na výšku a inú na šírku a pod.):

Šablóna môže obsahovať viacero tabuliek s vlastnými dátovými zdrojmi, napr. na každom zošite môžem mať úplné inú tabuľku, ale môžu byť aj v rámci jedného zošitu.

Argumenty

Ak chcete prispôsobiť pracovný hárok, môžete pomocou značky zadať nasledujúce argumenty:

Horizontal-Tento argument určuje horizontálny smer vypĺňania údajov pre premenné.

Syntax: %<DataSource>.<FieldName>;horizontal

Vertical-Tento argument určuje vertikálny smer vypĺňania údajov pre premenné. Štandardne sa údaje vypĺňajú vo vertikálnom smere

Syntax: %<DataSource>.<FieldName>;vertical

insert-Tento argument vloží nový riadok alebo stĺpec v závislosti od argumentu smeru pre každú novú bunku. Všimnite si, že štandardne sa riadky nevložia.

Syntax: %<DataSource>.<FieldName>;insert

• copystyles – kopírovanie aktuálneho štýlu riadka/stĺpca do novo vloženého riadka/stĺpca

Syntax: %<DataSource>.<FieldName>;insert:copystyles

• copymerges – kopírovanie zlúčených buniek do novo vloženého riadku/stĺpca

Syntax: %<DataSource>.<FieldName>;insert:copymerges

• copystyles a copymerges – na skopírovanie štýlov aj zlúčených buniek z aktuálneho riadka/stĺpca do novo vloženého riadka/stĺpca

Syntax: %<DataSource>.<FieldName>;insert:copystyles,copymerges

jump:[cell reference in R1C1 notation]-Tento argument spája údaje s bunkou v zadanom odkaze. Referenčné adresy buniek môžu byť relatívne alebo absolútne.

Syntax: %<DataSource>.<FieldName>;jump:R2C2

copyrange:[top-left cell reference in R1C1]:[bottom-right cell reference in R1C1]-Skopíruje zadané bunky po každom importe buniek.

Syntax: %<DataSource>.<FieldName>;copyrange:R2C2:R4C4

default-Tento argument pridáva hodnotu vlastnosti raz za objekt pre zodpovedajúce záznamy v stĺpci pri importovaní vnorených objektov kolekcie.

Syntax: %<DataSource>.<FieldName>default

merge-Tento argument zlúči bunky v stĺpci pre každú množinu objektov pri importovaní vnorených objektov kolekcie.

Syntax: %<DataSource>.<FieldName>merge

repeat-Tento argument opakuje hodnotu vlastnosti pre zodpovedajúce záznamy v stĺpci pri importovaní vnorených objektov kolekcie.

Syntax: %<DataSource>.<FieldName>repeat

collapsegroup-Tento argument zoskupuje bunky v stĺpci pre každú množinu objektov a zbalí údaje pri importovaní vnorených objektov kolekcie.

Syntax: %<DataSource>.<FieldName>collapsegroup

expandgroup-Tento argument zoskupuje bunky v stĺpci pre každú množinu objektov a rozširuje údaje pri importovaní vnorených objektov kolekcie.

Syntax: %<DataSource>.<FieldName>expandgroup

Vkladanie obrázkov

Podporované sú obrázky v nasledovných formátoch:

• GIF
• JPEG
• PNG
• BMP
• TIFF

Vlastnosť je detekovaná ako obrázok ak je typu System.Drawing.Image alebo byte[] z dátového zdroja (napr. varbinary z MS SQL). Obrázok môže byť formátovaný pomocou nasledujúcich argumentov:

Argumenty	Popis
Žiadny argument Príklad: %Reports.Image;	Obrázok je vložený vo východzej veľkosti (50×50 pixelov) a východzej pozícii (Top-Left).
fittocell Príklad: %Reports.Image;fittocell	Veľkosť obrázka je nastavená podľa veľkosti danej bunky.
size:width,height Príklad: %Reports.Image;size:60 (alebo) %Reports.Image;size:60,60 (alebo) %Reports.Image;size:60,auto (alebo) %Reports.Image;size:auto,60 (alebo) %Reports.Image;size:auto,auto	Obrázok je vložený v špecifikovanej veľkosti (width – šírka, height – výška). Parameter Height (výška) je voliteľný. Hodnota width (šírka) sa použije, ak nie je parameter height špecifikovaný. Možete zadať hodnoty width alebo height aj ako “auto”, aby sa dodržiaval pomer strán obrázka. Ak sú obidne hodnoty nastavené ako “auto”, tak je obrázok vložený vo svojej originálnej veľkosti.
position:position Príklad: %Reports.Image;position:middle-center (alebo) %Reports.Image;position:right	Pozícia obrázka Image is positioned (top-left, top-center, etc.,) v rámci danej bunky.

In the following example, a marker is added for merging images. Data source and property name is specified (%Reports.Image;) for image also.

Východzie zobrazenie obrázka

Príklad šablóny

Výsledný report

Obrázok s argumentom FitToCell

Príklad šablóny

Výsledný report

Obrázok s nastavenou veľkosťou

Príklad šablóny

Výsledný report

Obrázok s nastavenou pozíciou

Príklad šablóny

Výsledný report

Obrázok s nastavenou pozíciou a veľkosťou

Príklad šablóny

Výsledný report

FAQ

• Ak by ste chceli, aby sa SELECT-y v parametroch vykonali voči internej databáze brány namiesto voči SQL pripojeniu brány, stačí pridať parameter s názvom __gwsqlinternal

UPOZORNENIE

• Word – pri Merge fieldoch si treba dat pozor na to, že Word ma pre pole jeden text ako popis (nemá vplyv na funkčnosť, je len pre lepšiu orientáciu) a iný text je kód poľa, podľa ktorého sa mail merge vykonáva. Takže si treba dávať pozor, že ktorý text upravujem! Priklad z editora Wordu priamo v ERPIO App: