Dokumentum-összeszerelés (1. rész)

Folytatom a kalandozást az Open XML világában: ezúttal a jó öreg Mail Merge huszonegyedik századi verzióját mutatom be. A mai feladat: nagytömegű dokumentum automatikus (kiszolgáló oldali) előállítása a Word használata nélkül, egy relációs adatbázis alapján.

A megoldás első részében elkészítem azt a dokumentumot, amely a későbbi tömeggyártás alapjául szolgál majd. A második részben pedig írok egy konzolalkalmazást, azzal állítom elő a dokumentumok hadát.

Dokumentum

Nos, ez legyen egy ügyfélértesítő levél, amely (az egyszerűség kedvéért) a Microsoft jól bevált Northwind nevű mintaadatbázisának Customers táblájára épül. Először egy teljesen szimpla, minden speciális formázás nélküli Word 2007 dokumentumot készítsünk, ami kb. így néz ki:

 

Tartalomvezérlők

Természetesen azt szeretnénk, hogy az azonosító , ügyfél neve, kapcsolattartó neve, kapcsolattartó beosztása szövegek helyett a Customers adatbázistábla rekordjainak megfelelő mezőiben (CustomerID, CompanyName, ContactName, ContactTitle) tárolt adatok jelenjenek meg. Ezt úgy érhetjük el, hogy a szövegek helyére ún. tartalomvezérlőket (content control) szúrunk be. Lépések:

1. Engedélyezzük a Fejlesztőeszközök fül megjelenítését a szalagon. Ikszeljük be az Office gomb / A Word beállításai / Népszerű elemek / Fejlesztőeszközök lap megjelenítése a szalagon jelölőnégyzetet.

2. Kattintsunk a Fejlesztőeszközök fülre.

3. Jelöljük ki a dokumentumban az azonosító szöveget.

4. Kattintsunk a szalag Vezérlők csoportjában a Szöveg nevű tartalomvezérlőre (fekete Aa). A dokumentumban kijelölt szöveg helyére egy ún. tartalomvezérlő kerül, amely szabadon formázható, nyomtatható, stb., de a kitöltését a későbbiekben kívülről is megvezethetjük.

   

5. A tartalomvezérlő maradjon továbbra is kijelölve, a szalagon pedig kattintsunk a Vezérlők csoport Tulajdonságok nevű gombjára. Megnyílik a tartalomvezérlő tulajdonságlapja.

6. Írjunk be egy címet (pl. azonosító, ez szerepel a szövegben) és egy azonosítót (pl. CustomerID, ez az adatbázismező neve is). Előbbinek a manuális, utóbbinak a gépi kitöltésnél lesz szerepe.

    

7. Ikszeljük be, hogy a tartalomvezérlő nem törölhető, majd kattintsunk az OK-ra.

8. Ezzel létrehoztuk az első tartalomvezérlőnket. Most készítsünk még hármat a további szövegekhez, a címek megegyezhetnek a dokumentumban lévőkkel, az azonosítók pedig az adatbázismezőkkel.

A Wordben nincs több teendőnk, mentsük a dokumentumot pl. Ügyfélértesítő.docx néven. Jöhet az adatkötések létrehozása.

Adatok

Amikor külső adatokat viszünk be egy Open XML dokumentumba, azok XML fájlokként tárolódnak a mappahierarchia adott pontján. Tegyük fel, hogy így néznek ki az adataink:

<CustomerData>
<CustomerID>ALFKI</CustomerID>
<CompanyName>Alfreds Futterkiste</CompanyName>
<ContactName>Maria Anders</ContactName>
<ContactTitle>Sales Representative</ContactTitle>
</CustomerData>

Ha azt szeretnénk, hogy a fenti szerkezetű XML adatfájlok elemei megjelenjenek a korábban létrehozott tartalomvezérlőkben, be kell juttatnunk egy mintafájlt a dokumentumba, majd össze kell kapcsolnunk az elemeit a vezérlőkkel. Ezt végezhetjük manuálisan, de használhatunk egy Word 2007 Content Control Toolkit nevű kényelmes eszközt is. Lépések az utóbbival:

1. Töltsük le és telepítsük a Content Control Toolkit aktuális változatát.

2. Nyissuk meg az Ügyfélértesítő.docx dokumentumot a Toolkitben. A következőket látjuk (nagyításhoz katt):

   

   Balra, a Content Controls listában megjelennek a korábban felvett tartalomvezérlők. Jobbra, az XML adatok helye azonban még üres.

3. Hozzunk létre egy új egyedi XML részt a parancsra kattintva, majd váltsunk át szerkesztési nézetre (Edit View).

4. Másoljuk be innen a bejegyzésből az ügyfél-mintaadatokat tartalmazó XML-részletet, majd váltsunk át kötési nézetre (Bind View). Most ezt látjuk:

   

5. Kattintással jelöljük ki a jobb oldali hierarchiában a CustomerID elemet, majd az egérrel húzzuk a bal oldalon lévő CustomerID vezérlőre.

6. Tegyük ezt a további három elem-vezérlő párossal is. Íme az eredmény:

   

7. Mentsük a dokumentumot, zárjuk be a Toolkitet, majd nyissuk meg újra a dokumentumot, ezúttal Wordben. Az adatok megjelennek a vezérlőkben:

   

Extra: Boncolás

Hova került az XML adatfájl? És hogyan kapcsolódnak az elemei a tartalomvezérlőkhöz? Vágjuk fel a dokumentum hasát, és kiderül. Ez a lépés természetesen nem feltétlenül szükséges, de az érdeklődők megtanulhatják belőle, milyen a kézi módszer.

Nevezzük át a DOCX fájlt ZIP-pé, és nyissuk meg. A Wordben egyébként szokásos mappák mellett egy customXML nevűt is látunk. Ez két fontos dolgot rejt. Egyrészt az adatokat (az item1.xml fájlban); ha megnyitjuk, visszaköszön a fent már látott XML. Másrészt az adatfájl azonosítóját (az itemProps1.xml fájlban), ami kb. így néz ki (a lényeg pirossal):

<ds:datastoreItem
ds:itemID="{ef02de5f-b653-4045-a316-b57cf1079bf4}" xmlns:ds="https://schemas.openxmlformats.org/officeDocument/2006/customXml" />

A tényleges dokumentumot továbbra is a word mappában lévő document.xml fájl tárolja. Nyissuk meg, és keressünk strukturált dokumentumjelölőket (Structured Document Tag, SDT), azaz w:sdt elemeket. Az első valahogy így kezdődik:

<w:sdt>
<w:sdtPr>
<w:dataBinding
w:xpath="/CustomerData[1]/CustomerID[1]"
w:storeItemID=
"{ef02de5f-b653-4045-a316-b57cf1079bf4}" />
<w:alias w:val="azonosító" />
<w:tag w:val="CustomerID" />
<w:id w:val="331263381" />
<w:lock w:val="sdtLocked" />
...

Gyakorlatilag az egészet a Worddel hoztuk létre, kivéve a w:databinding elemet, amelyet a Content Control Toolkittel varázsoltunk a document.xml-be. Jól látszik, hogy kézzel hozzáadni sem nagy kunszt: a zölddel jelölt w:xpath az adott elem (itt a CustomerID) adatfájlon belüli XPath-címe, a pirossal jelölt w:storeItemID pedig megegyezik a korábban hasonlóan kiemelt ds:itemID-vel.

Szünet

Félúton járunk: a dokumentum kész, képes külső adatok fogadására és értelmes megjelenítésére. A következő részben azt mutatom meg, hogy lehet ilyen fájlokat nagy tömegben összeszerelni.