repo_zf1/documentation/manual/de/module_specs/Zend_Service_LiveDocx.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 19452 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.livedocx">
    <title>Zend_Service_LiveDocx</title>

    <sect2 id="zend.service.livedocx.introduction">
        <title>Einführung in LiveDocx</title>

        <para>
            LiveDocx ist ein <acronym>SOAP</acronym> Service der es Entwicklern erlaubt Word
            Dokumente zu erstellen indem strukturierte Daten von PHP mit einem Template kombiniert
            werden, die in einer Word Bearbeitung erstellt wurden. Das resultierende Dokument kann
            als <acronym>PDF</acronym>, <acronym>DOCX</acronym>, <acronym>DOC</acronym>,
            <acronym>HTML</acronym> oder <acronym>RTF</acronym> Datei gespeichert werden. LiveDocx
            implementiert <ulink url="http://en.wikipedia.org/wiki/Mail_merge">mail-merge</ulink>
            in PHP.
        </para>

        <para>
            Die Familie der <classname>Zend_Service_LiveDocx</classname> Komponenten bietet ein
            klares und einfaches Interface zur <ulink url="http://www.livedocx.com">LiveDocx
                API</ulink> und bietet zusätzlich Funktionalitäten um die Geschwindigkeit im
            Netzwerk zu erhöhen.
        </para>

        <para>
            Wenn man, zusätzlich zu diesem Kapitel des Handbuchs, daran interessiert ist mehr
            über <classname>Zend_Service_LiveDocx</classname> und das dahinterliegende
            <acronym>SOAP</acronym> Service LiveDocx zu lernen, kann man bei den folgenden
            Ressourcen nachsehen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Mitgelieferte Beispielanwendungen</emphasis>. Es gibt eine große
                    Anzahl an Beispielanwendungen im Verzeichnis
                    <emphasis>/demos/Zend/Service/LiveDocx</emphasis> der Zend Framework
                    Distributiondatei, oder der Trunk Version die vom standardmäßigen SVN
                    repository ausgecheckt werden kann. Diese sind dazu gedacht schnell, in nur
                    ein paar Minuten, mit <classname>Zend_Service_LiveDocx</classname> zurecht zu
                    kommen.
                </para>
            </listitem>
            <listitem>
                <para>
                    <ulink url="http://www.phplivedocx.org/">
                    <classname>Zend_Service_LiveDocx</classname> Blog und Webseite</ulink>.
               </para>
            </listitem>
            <listitem>
                <para>
                    <ulink url="http://www.livedocx.com/pub/documentation/api.aspx">
                    LiveDocx SOAP API Dokumentation</ulink>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <ulink url="https://api.livedocx.com/1.2/mailmerge.asmx?wsdl">
                    LiveDocx WSDL</ulink>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <ulink url="https://www.livedocx.com/">LiveDocx Blog und Webseite</ulink>.
                </para>
            </listitem>
        </itemizedlist>

        <sect3 id="zend.service.livedocx.account">
            <title>Für einen Account anmelden</title>

            <para>
                Bevor man damit beginnt LiveDocx zu verwenden muss man sich zuerst für einen Account
                <ulink
                    url="https://www.livedocx.com/user/account_registration.aspx">anmelden</ulink>.
                Der Account ist komplett kostenlos, und mann muss nur einen
                <emphasis>Benutzernamen</emphasis>, ein <emphasis>Passwort</emphasis> und eine
                <emphasis>E-Mail Adresse</emphasis> spezifizieren. Die Anmeldedaten werden mit der
                Email Adresse verknüpft, welche man angibt, deshalb sollte man vorsichtig tippen.
            </para>
        </sect3>

        <sect3 id="zend.service.livedocx.templates-documents">
            <title>Templates und Dokumente</title>

            <para>
                LiveDocx unterscheidet zwischen den folgenden Ausdrücken: 1)
                <emphasis>Template</emphasis> und 2) <emphasis>Dokument</emphasis>. Um die
                Dokumentation und auch die aktuelle API vollständig zu verstehen, ist es wichtig
                das jeder Programmierer der LiveDocx ausliefert, den Unterschied versteht.
            </para>

            <para>
                Der Ausdruck <emphasis>Template</emphasis> wird verwendet um auf eine Eingabedatei
                zu verweisen, die in einem Word Prozessor erstellt wurde, und Formatierungen sowie
                Textfelder enthält. Man kann ein <ulink
                    url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-template.docx">Beispieltemplate</ulink>
                downloaden, welches als <acronym>DOCX</acronym> Datei gespeichert ist. Der Ausdruck
                <emphasis>Dokument</emphasis> wird verwendet um auf eine Ausgabedatei zu verweisen
                welche die Templatedatei enthält, zusammen mit Daten - z.B. das fertiggestellte
                Dokument. Man kann ein <ulink
                    url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-document.pdf">Beispieldokument</ulink>
                downloaden, welches als <acronym>PDF</acronym> Datei gespeichert ist.
            </para>
        </sect3>

        <sect3 id="zend.service.livedocx.formats">
            <title>Unterstützte Dateiformate</title>

            <para>
                LiveDocx unterstützt die folgenden Dateiformate:
            </para>

            <sect4 id="zend.service.livedocx.formats.template">
                <title>Template Dateiformate (Eingabe)</title>

                <para>
                    Templates können in jedem der folgenden Dateiformate gespeichert werden:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Office_Open_XML">DOCX</ulink> -
                            Office Open <acronym>XML</acronym> Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/DOC_(computing)">DOC</ulink> -
                            Microsoft Word <acronym>DOC</acronym> Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Rich_Text_Format">RTF</ulink> -
                            Rich Text Dateiformat
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://www.textcontrol.com/">TXD</ulink> - TX Text Control
                            Format
                        </para>
                    </listitem>
                </itemizedlist>
            </sect4>

            <sect4 id="zend.service.livedocx.formats.document">
                <title>Dokument Dateiformate (Ausgabe):</title>

                <para>
                    Das resultierende Dokument kann in jedem der folgenden Dateiformate gespeichert
                    werden:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Office_Open_XML">DOCX</ulink> -
                            Office Open <acronym>XML</acronym> Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/DOC_(computing)">DOC</ulink> -
                            Microsoft Word <acronym>DOC</acronym> Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Xhtml">HTML</ulink> -
                            <acronym>XHTML</acronym> 1.0 Transitional Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Rich_Text_Format">RTF</ulink> -
                            Rich Text File Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink
                                url="http://en.wikipedia.org/wiki/Portable_Document_Format">PDF</ulink>
                            - Acrobat Portable Document Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://www.textcontrol.com/">TXD</ulink> - TX Text Control
                            Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Text_file">TXT</ulink> -
                            <acronym>ANSI</acronym> reiner Text
                        </para>
                    </listitem>
                </itemizedlist>
            </sect4>

            <sect4 id="zend.service.livedocx.formats.image">
                <title>Bild Dateiformate (Ausgabe):</title>

                <para>
                    Das resultierende Dokument kann in jedem der folgenden grafischen Dateiformate
                    gespeichert werden:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/BMP_file_format">BMP</ulink> -
                            Bitmap Image Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/GIF">GIF</ulink> - Graphics
                            Interchange Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Jpg">JPG</ulink> - Joint
                            Photographic Experts Group Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink
                                url="http://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG</ulink>
                            - Portable Network Graphics Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink
                                url="http://en.wikipedia.org/wiki/Tagged_Image_File_Format">TIFF</ulink>
                            - Tagged Image File Format
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <ulink url="http://en.wikipedia.org/wiki/Windows_Metafile">WMF</ulink> -
                            Windows Meta File Format
                        </para>
                    </listitem>
                </itemizedlist>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.service.livedocx.mailmerge">
        <title>Zend_Service_LiveDocx_MailMerge</title>

        <para>
             <classname>Zend_Service_LiveDocx_MailMerge</classname> ist das mail-merge Objekt in der
             <classname>Zend_Service_LiveDocx</classname> Familie.
        </para>

        <sect3 id="zend.service.livedocx.mailmerge.generation">
            <title>Prozess der Dokumentenerstellung</title>

            <para>
                Der Prozess der Erstellung des Dokuments kann mit der folgenden Gleichung
                vereinfacht dargestellt werden:
            </para>

            <para>
                <emphasis>Template + Daten = Dokument</emphasis>
            </para>

            <para>
                Oder durch das folgende Diagramm ausgedrückt werden:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.generation-diabasic.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Daten werden in ein Template eingefügt um ein Dokument zu erstellen (<ulink
                            url="figures/zend.service.livedocx.mailmerge.generation-diabasic_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Ein Template das in einer Word Bearbeitungsanwendung, wie Microsoft Word, erstellt
                wird, wurd in LiveDocx geladen. Daten werden kann in das Template eingesetzt, und
                das resultierende Dokument wird in jedes der unterstützten Formate gespeichert.
            </para>
        </sect3>

        <sect3 id="zend.service.livedocx.mailmerge.templates">
            <title>Erstellen von Templates in Microsoft Word 2007</title>

            <para>
                Man muss damit beginnen Microsoft Word zu starten und ein neues Dokument zu
                erstellen. Als nächstes, wird der Dialog <emphasis>Felder</emphasis> geöffnet.
                Er sieht wie folgt aus:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.templates-msworddialog.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Dialogbox Felder in Microsoft Word 2007 (<ulink
                            url="figures/zend.service.livedocx.mailmerge.templates-msworddialog_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Durch Verwendung dieses Dialogs kann man die benötigten Merge-Felder in das eigene
                Dokument einfügen. Anbei ist ein Screenshot der Lizenz Vereinbarung in Microsoft
                Word 2007. Die Merge Felder sind als <code>{ MERGEFIELD FieldName }</code> markiert:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatefull.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Das Template in Microsoft Word 2007 (<ulink
                            url="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatefull_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Jetzt muss das Template als <emphasis>template.docx</emphasis> gespeichert werden.
            </para>

            <para>
                Im nächsten Schritt veröffentlichen wir die Merge-Felder mit textuellen Daten von
                PHP.
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatecropped.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Unterteiltes Template in Microsoft Word 2007 (<ulink
                            url="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatecropped_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Um die Merge Felder, im vorher unterteilten Screenshot des <ulink
                    url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-template.docx">Templates</ulink>,
                in Microsoft Word auszufüllen, muss das folgende geschrieben werden:
            </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->setLocalTemplate('template.docx');

$phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9')
            ->assign('licensee', 'Henry Döner-Meyer')
            ->assign('company',  'Co-Operation');

$phpLiveDocx->createDocument();

$document = $phpLiveDocx->retrieveDocument('pdf');

file_put_contents('document.pdf', $document);
]]></programlisting>

            <para>
                Das resultierende Dokument wird auf die Festplatte in die Datei
                <emphasis>document.pdf</emphasis> geschrieben. Diese Datei kann nun weiter
                bearbeitet, per Email versendet oder einfach angezeigt werden, wie anbei im
                <emphasis>Document Viewer 2.26.1</emphasis> auf <emphasis>Ubuntu 9.04</emphasis>
                gezeigt:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.templates-msworddocument.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Resultierendes Dokument als <acronym>PDF</acronym> im Document Viewer 2.26.1
                        (<ulink
                            url="figures/zend.service.livedocx.mailmerge.templates-msworddocument_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>
        </sect3>

        <sect3 id="zend.service.livedocx.mailmerge.advanced">
            <title>Gehobeneres Mail-Merge</title>

            <para>
                <classname>Zend_Service_LiveDocx_MailMerge</classname> erlaubt es Entwicklern eine
                beliebige Anzahl an Text Feldern in ein Template einzufügen. Diese textfelder werden
                mit Daten gefüllt wenn <emphasis>createDocument()</emphasis> aufgerufen wird.
            </para>

            <para>
                Zusätzlich zu Textfeldern ist es auch mäglich spezielle Regionen eines Dokuments
                zu spezifizieren, welche wiederholt werden sollen.
            </para>

            <para>
                In einer Telefonrechnung ist es z.b. notwendig eine Liste aller Verbindungen,
                inklusive der Zielnummern, der Dauer und den Kosten jedes Anrufs auszudrucken.
                Diese Funktion der wiederholten Zeile kann mit sogenannten Blöcken erzielt werden.
            </para>

            <para>
                <emphasis>Blöcke</emphasis> sind einfach Regionen eines Dokuments, welche wiederholt
                werden wenn <methodname>createDocument()</methodname> aufgerufen wird. In einem
                Block kann eine beliebige Anzahl an <emphasis>Block Feldern</emphasis> spezifiziert
                werden.
            </para>

            <para>
                Blöcke bestehen aus zwei zusammenhängenden Dokument-Zielen mit einem eindeutigen
                Namen. Der folgende Screenshot zeigt diese Ziele und deren Namen in Rot:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.advanced-mergefieldblockformat.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        (<ulink
                            url="figures/zend.service.livedocx.mailmerge.advanced-mergefieldblockformat_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Das Format eines Blocks ist wie folgt:
            </para>

            <programlisting language="text"><![CDATA[
blockStart_ + unique name
blockEnd_ + unique name
]]></programlisting>

            <para>Zum Beispiel:</para>

            <programlisting language="text"><![CDATA[
blockStart_block1
blockEnd_block1
]]></programlisting>

            <para>
                Der Inhalt eines Blocks wird wiederholt, bis alle zugeordneten Daten in Blockfeldern
                des Templates eingefügt wurden. Die Daten der Blockfelder werden in PHP als
                mehrfach-assoziatives Array spezifiziert.
            </para>

            <para>
                Der folgende Screenshot eines Templates in Microsoft Word 2007 zeigt wie Blockfelder
                verwendet werden:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblockstemplate.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Template, welches Blöcke in Microsoft Word 2007 zeigt (<ulink
                            url="figures/zend.service.livedocx.mailmerge.advanced-mswordblockstemplate_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Der folgende Code füllt das obige Template mit Daten.
            </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->setLocalTemplate('template.doc');

$billConnections = array(
    array(
        'connection_number'   => '+49 421 335 912',
        'connection_duration' => '00:00:07',
        'fee'                 => '€ 0.03',
    ),
    array(
        'connection_number'   => '+49 421 335 913',
        'connection_duration' => '00:00:07',
        'fee'                 => '€ 0.03',
    ),
    array(
        'connection_number'   => '+49 421 335 914',
        'connection_duration' => '00:00:07',
        'fee'                 => '€ 0.03',
    ),
    array(
        'connection_number'   => '+49 421 335 916',
        'connection_duration' => '00:00:07',
        'fee'                 => '€ 0.03',
    ),
);

$phpLiveDocx->assign('connection', $billConnections);

// ... andere Daten hier anhängen ...

$phpLiveDocx->createDocument();
$document = $phpLiveDocx->retrieveDocument('pdf');
file_put_contents('document.pdf', $document);
]]></programlisting>

            <para>
                Die Daten, welche im Array <varname>$billConnections</varname> spezifiziert sind,
                werden im Template im Block 'connection' wiederholt. Die Schlüssel des Arrays
                (<varname>connection_number</varname>, <varname>connection_duration</varname> und
                <varname>fee</varname>) sind die Namen der Blockfelder - deren Daten werden bei
                jeder Iteration in einer Zeile eingefügt.
            </para>

            <para>
                Das resultierende Dokument wird auf die Festplatte in die Datei
                <emphasis>document.pdf</emphasis> geschrieben. Diese Datei kann anschließend
                nachbearbietet, per Email gesendet, oder einfach dargestellt werden, wie anbei im
                <emphasis>Document Viewer 2.26.1</emphasis> unter <emphasis>Ubuntu 9.04</emphasis>
                gezeigt:
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblocksdocument.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        Das resultierende Dokument als <acronym>PDF</acronym> im Document Viewer
                        2.26.1 (<ulink
                            url="figures/zend.service.livedocx.mailmerge.advanced-mswordblocksdocument_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <para>
                Man kann die <acronym>DOC</acronym> <ulink
                    url="http://www.phplivedocx.org/wp-content/uploads/2009/01/telephone-bill-template.doc">Template
                    Datei</ulink> und das resultierende <ulink
                    url="http://www.phplivedocx.org/wp-content/uploads/2009/01/telephone-bill-document.pdf">PDF
                    Dokument</ulink> hier herunterladen.
            </para>

            <para>
                <emphasis>BEACHTE:</emphasis> Blöcke können nicht verschachtelt werden.
            </para>
        </sect3>

        <sect3 id="zend.service.livedocx.mailmerge.bitmaps">
            <title>Erstellen von Bitmap Bildern</title>

            <para>
                Zusätzlich zu den Dateiformaten für Dokumente erlaubt es
                <classname>Zend_Service_LiveDocx_MailMerge</classname> auch Dokumente als eine
                Anzahl von Bildern zu speichern (<acronym>BMP</acronym>,
                <acronym>GIF</acronym>, <acronym>JPG</acronym>, <acronym>PNG</acronym> und
                <acronym>TIFF</acronym>). Jede Seite des Dokuments wird als eine Datei gespeichert.
            </para>

            <para>
                Das folgende Beispiel zeigt die Verwendung von <methodname>getBitmaps($fromPage,
                    $toPage, $zoomFactor, $format)</methodname> und
                <methodname>getAllBitmaps($zoomFactor, $format)</methodname>.
            </para>

            <para>
                <varname>$fromPage</varname> ist die untere Grenze der Seitenzahl des Bereichs an
                Seiten die als Bild zurückgegeben werden soll, und <varname>$toPage</varname> ist
                die obere Grenze der Seitenzahlen. <varname>$zoomFactor</varname> ist die Größe
                der Bilder, als Prozentwert, relativ zur originalen Seitengröße. Der Bereich dieses
                Parameters ist von 10 bis 400. <varname>$format</varname> ist das Format des
                Bildes welches von dieser Methode zurückgegeben wird. Die unterstützten Formate
                erhält man, wenn man <methodname>getImageFormats()</methodname> aufruft.
            </para>

            <programlisting language="php"><![CDATA[
$date = new Zend_Date();
$date->setLocale('en_US');

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->setLocalTemplate('template.docx');

$phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9')
            ->assign('licensee', 'Daï Lemaitre')
            ->assign('company',  'Megasoft Co-operation')
            ->assign('date',     $date->get(Zend_Date::DATE_LONG))
            ->assign('time',     $date->get(Zend_Date::TIME_LONG))
            ->assign('city',     'Lyon')
            ->assign('country',  'France');

$phpLiveDocx->createDocument();

// Alle Bitmaps holen
// (zoomFactor, format)
$bitmaps = $phpLiveDocx->getAllBitmaps(100, 'png');

// Nur Bitmaps im spezifizierten Bereich erhalten
// (fromPage, toPage, zoomFactor, format)
// $bitmaps = $phpLiveDocx->getBitmaps(2, 2, 100, 'png');

foreach ($bitmaps as $pageNumber => $bitmapData) {
    $filename = sprintf('documentPage%d.png', $pageNumber);
    file_put_contents($filename, $bitmapData);
}
]]></programlisting>

            <para>
                Das produziert zwei Bilder (<filename>documentPage1.png</filename> und
                <filename>documentPage2.png</filename>) und schreibt diese auf der Festplatte
                in das gleiche Verzeichnis wie die ausführbare PHP Datei.
            </para>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage1.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        documentPage1.png (<ulink
                            url="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage1_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>

            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage2.png"
                        format="PNG"></imagedata>
                </imageobject>

                <caption>
                    <para>
                        documentPage2.png (<ulink
                            url="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage2_zoom.png">größer
                            darstellen</ulink>).
                    </para>
                </caption>
            </mediaobject>
        </sect3>

        <sect3 id="zend.service.livedocx.mailmerge.templates-types">
            <title>Local vs. Remote Templates</title>

            <para>
                Templates can be stored <emphasis>locally</emphasis>, on the client machine, or
                <emphasis>remotely</emphasis>, on the server. There are advantages and disadvantages
                to each approach.
            </para>

            <para>
                In the case that a template is stored locally, it must be transfered from the client
                to the server on every request. If the content of the template rarely changes, this
                approach is inefficient. Similarly, if the template is several megabytes in size, it
                may take considerable time to transfer it to the server. Local template are useful
                in situations in which the content of the template is constantly changing.
            </para>

            <para>
                The following code illustrates how to use a local template.
            </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->setLocalTemplate('./template.docx');

// assign data and create document
]]></programlisting>

            <para>
                In the case that a template is stored remotely, it is uploaded once to the server
                and then simply referenced on all subsequent requests. Obviously, this is much
                quicker than using a local template, as the template does not have to be transfered
                on every request. For speed critical applications, it is recommended to use the
                remote template method.
            </para>

            <para>
                The following code illustrates how to upload a template to the server:
            </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->uploadTemplate('template.docx');
]]></programlisting>

            <para>
                The following code illustrates how to reference the remotely stored template on all
                subsequent requests:
            </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$phpLiveDocx->setRemoteTemplate('template.docx');

// assign data and create document
]]></programlisting>
        </sect3>

        <sect3 id="zend.service.livedocx.mailmerge.information">
            <title>Getting Information</title>

            <para>
                <classname>Zend_Service_LiveDocx_MailMerge</classname> provides a number of methods
                to get information on field names, available fonts and supported formats.
            </para>

            <example id="zend.service.livedocx.mailmerge.information.getfieldname">
                <title>Get Array of Field Names in Template</title>

                <para>
                    The following code returns and displays an array of all field names in the
                    specified template. This functionality is useful, in the case that you create an
                    application, in which an end-user can update a template.
                </para>

                <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$templateName = 'template-1-text-field.docx';
$phpLiveDocx->setLocalTemplate($templateName);

$fieldNames = $phpLiveDocx->getFieldNames();
foreach ($fieldNames as $fieldName) {
    printf('- %s%s', $fieldName, PHP_EOL);
}
]]></programlisting>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.getblockfieldname">
                <title>Get Array of Block Field Names in Template</title>

                <para>
                    The following code returns and displays an array of all block field names in the
                    specified template. This functionality is useful, in the case that you create an
                    application, in which an end-user can update a template. Before such templates
                    can be populated, it is necessary to find out the names of the contained block
                    fields.
                </para>

                <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

$templateName = 'template-block-fields.doc';
$phpLiveDocx->setLocalTemplate($templateName);

$blockNames = $phpLiveDocx->getBlockNames();
foreach ($blockNames as $blockName) {
    $blockFieldNames = $phpLiveDocx->getBlockFieldNames($blockName);
    foreach ($blockFieldNames as $blockFieldName) {
        printf('- %s::%s%s', $blockName, $blockFieldName, PHP_EOL);
    }
}
]]></programlisting>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.getfontnames">
                <title>Get Array of Fonts Installed on Server</title>

                <para>
                    The following code returns and displays an array of all fonts installed on the
                    server. You can use this method to present a list of fonts which may be used in
                    a template. It is important to inform the end-user about the fonts installed on
                    the server, as only these fonts may be used in a template. In the case that a
                    template contains fonts, which are not available on the server,
                    font-substitution will take place. This may lead to undesirable results.
                </para>

            <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

Zend_Debug::dump($phpLiveDocx->getFontNames());
]]></programlisting>

                <para>
                    <emphasis>NOTE:</emphasis> As the return value of this method changes very
                    infrequently, it is highly recommended to use a cache, such as
                    <classname>Zend_Cache</classname> - this will considerably speed up your
                    application.
                </para>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.gettemplateformats">
                <title>Get Array of Supported Template File Formats</title>

                <para>
                    The following code returns and displays an array of all supported template file
                    formats. This method is particularly useful in the case that a combo list should
                    be displayed that allows the end-user to select the input format of the
                    documentation generation process.
                </para>

                <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge()

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

Zend_Debug::dump($phpLiveDocx->getTemplateFormats());
]]></programlisting>

                <para>
                    <emphasis>NOTE:</emphasis> As the return value of this method changes very
                    infrequently, it is highly recommended to use a cache, such as
                    <classname>Zend_Cache</classname> - this will considerably speed up your
                    application.
                </para>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.getdocumentformats">
                <title>Get Array of Supported Document File Formats</title>

                <para>
                    The following code returns and displays an array of all supported document file
                    formats. This method is particularly useful in the case that a combo list should
                    be displayed that allows the end-user to select the output format of the
                    documentation generation process.
                </para>

                <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

Zend_Debug::dump($phpLiveDocx->getDocumentFormats());
]]></programlisting>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.getimageformats">
                <title>Get Array of Supported Image File Formats</title>

                <para>
                    The following code returns and displays an array of all supported image file
                    formats. This method is particularly useful in the case that a combo list should
                    be displayed that allows the end-user to select the output format of the
                    documentation generation process.
                </para>

                <programlisting language="php"><![CDATA[
$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('myUsername')
            ->setPassword('myPassword');

Zend_Debug::dump($phpLiveDocx->getImageFormats());
]]></programlisting>

                <para>
                    <emphasis>NOTE:</emphasis> As the return value of this method changes very
                    infrequently, it is highly recommended to use a cache, such as
                    <classname>Zend_Cache</classname> - this will considerably speed up your
                    application.
                </para>
            </example>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=100 et:
-->