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.
Licencia
Plugin je licencovaný pre konkrétny workspace a vyžaduje, aby každý dátový zdroj voči tomuto pluginu mal 2 povinné parametre:
@WorkspaceID – musí mať v hodnote stĺpca vybranú systémovú voľbu WorkspaceID
@LicenseKey – musí byť vyplnený licenčný kľúč pre daný workspace. Kľúč získate od Vášho obchodného kontaktu, alebo píšte na sales@erpio.one.
Obsah:
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:
- Vyberte pole hromadnej korešpondencie, napríklad Company, ako je znázornené v tomto príklade.
- 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 }.
- 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).
- Znova stlačte [Alt] + F9.
- 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: