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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21819 -->
<!-- Reviewed: 21819 -->
<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, MS Word
            Dokumente zu erstellen, indem strukturierte Daten von <acronym>PHP</acronym> mit einem
            Template kombiniert werden, die in einer MS Word-kompatiblen Anwendung 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
            <acronym>PHP</acronym>.
        </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 den dahinterliegenden
            <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
                    Distributionsdatei, 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 es muss nur ein
                <emphasis>Benutzername</emphasis>, ein <emphasis>Passwort</emphasis> und eine
                <emphasis>E-Mail-Adresse</emphasis> eingegeben werden. Die Anmeldedaten werden mit der
                E-Mail-Adresse verknüpft, die 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 <acronym>API</acronym> vollständig zu verstehen,
                ist es wichtig dass 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 einer Textverarbeitung 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>
                herunterladen, 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>
                herunterlaen, 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>Dateiformate des Dokuments (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-Dateiformat
                        </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>Bilddateiformate (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 Bildformat
                        </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>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.generation-diabasic_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Daten werden in ein Template eingefügt, um ein Dokument zu erstellen.
            </para>

            <para>
                Ein Template, das in einer Textverarbeitungsanwendung, wie Microsoft Word, erstellt
                wird, wird in LiveDocx geladen. Daten werden 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>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.templates-msworddialog_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Dialogbox Felder in Microsoft Word 2007.
            </para>

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

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatefull_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Das Template in Microsoft Word 2007.
            </para>

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

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

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatecropped_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Unterteiltes Template in Microsoft Word 2007.
            </para>

            <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 der Festplatte in die Datei
                <emphasis>document.pdf</emphasis> geschrieben. Diese Datei kann nun weiter
                bearbeitet, per E-Eail versendet oder einfach angezeigt werden, wie anbei im
                <emphasis>Document Viewer 2.26.1</emphasis> auf <emphasis>Ubuntu 9.04</emphasis>
                gezeigt:
            </para>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.templates-msworddocument_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Resultierendes Dokument als <acronym>PDF</acronym> im Document Viewer 2.26.1.
            </para>
        </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 Text-Felder
                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
                anzugeben, die 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 abzubilden,.
                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 Sprungmarken mit eindeutigen
                Namen. Der folgende Screenshot zeigt diese Sprungmarken und deren Namen in Rot:
            </para>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.advanced-mergefieldblockformat_zoom.png"
                    format="PNG" />
            </para>

            <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
                <acronym>PHP</acronym> als mehrfach-assoziatives Array spezifiziert.
            </para>

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

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblockstemplate_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Template, welches Blöcke in Microsoft Word 2007 zeigt.
            </para>

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

$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 der Festplatte in die Datei
                <emphasis>document.pdf</emphasis> geschrieben. Diese Datei kann anschließend
                nachbearbietet, per E-Mail gesendet, oder einfach dargestellt werden, wie anbei im
                <emphasis>Document Viewer 2.26.1</emphasis> unter <emphasis>Ubuntu 9.04</emphasis>
                gezeigt:
            </para>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblocksdocument_zoom.png"
                    format="PNG" />
            </para>

            <para>
                Das resultierende Dokument als <acronym>PDF</acronym> im Document Viewer
                2.26.1.
            </para>

            <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 Bilder zurückgegeben werden sollen 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 die Festplatte
                in das gleiche Verzeichnis wie die ausführbare <acronym>PHP</acronym>-Datei.
            </para>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage1_zoom.png"
                    format="PNG" />
            </para>

            <para>
                documentPage1.png.
            </para>

            <para>
                <inlinegraphic
                    fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage2_zoom.png"
                    format="PNG" />
            </para>

            <para>
                documentPage2.png.
            </para>
        </sect3>

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

            <para>
                Templates können <emphasis>lokal</emphasis> auf der Client-Maschine gespeichert
                werden oder <emphasis>remote</emphasis> auf dem Server. Jede Variante hat Vorteile
                und Nachteile.
            </para>

            <para>
                Im Falle, dass ein Template lokal gespeichert ist, muss es bei jeder Anfrage vom
                Client auf den Server transferiert werden. Wenn sich der Inhalt vom Templates
                selten ändert, ist dieser Weg sehr ineffizient. Ähnlich auch, wenn das Template eine
                Größe von mehreren Megabyte hat, kann es eine beträchtliche Zeit dauern, es auf den
                Server zu transferieren. Lokale Templates sind in Situationen sinnvoll, in denen der
                Inhalt des Templates konstant geändert wird.
            </para>

            <para>
                Der folgende Code zeigt, wie man ein lokales Template verwendet.
            </para>

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

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

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

// Daten hinzufügen und das Dokument erstellen
]]></programlisting>

            <para>
                Im Falle, dass ein Template remote gespeichert ist, wird es nur einmal auf den
                Server geladen und anschließend bei allen nachfolgenden Anfragen darauf
                referenziert. Natürlich ist es viel schneller, als ein lokales Template zu
                verwenden, da das Template nicht bei jeder Anfrage übertragen werden muss. Für
                Anwendungen bei denen die Geschwindigkeit kritisch ist, wird es empfohlen die
                Remote-Template-Methode zu verwenden.
            </para>

            <para>
                Der folgende Code zeigt, wie ein Template auf den Server übertragen wird:
            </para>

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

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

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

            <para>
                Der folgende Code zeigt, wie auf das remote gespeicherte Template bei allen
                weiteren Anfragen referenziert wird:
            </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>Informationen erhalten</title>

            <para>
                <classname>Zend_Service_LiveDocx_MailMerge</classname> bietet eine Anzahl an
                Methoden um Informationen über Feldnamen, vorhandene Schriftarten und unterstützte
                Formate zu erhalten.
            </para>

            <example id="zend.service.livedocx.mailmerge.information.getfieldname">
                <title>Ein Array an Feldnamen vom Template erhalten</title>

                <para>
                    Der folgende Code gibt ein Array aller Feldnamen im angegebenen Template
                    zurück und zeigt diese an. Diese Funktionalität ist nützlich, wenn man eine
                    Anwendung erstellt, in welcher der Endbenutzer das Template aktualisieren kann.
                </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>Ein Array an Blockfeldnamen vom Template erhalten</title>

                <para>
                    Der folgende Code zeigt ein Array aller Blockfeldnamen im
                    angegebenen Template an. Diese Funktionalität ist nützlich, wenn man eine
                    Anwendung erstellt, in welcher der Endbenutzer das Template aktualisieren kann.
                    Bevor solche Templates veröffentlicht werden können, ist es notwendig, die Namen
                    der enthaltenen Blockfelder herauszufinden.
                </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>
                    Ein Array von Schriftarten erhalten welche auf dem Server installiert sind
                </title>

                <para>
                    Der folgende Code zeigt ein Array aller auf dem Server installierten
                    Schriftarten an. Diese Methode kann verwendet werden, um eine Liste
                    von Schriftarten anzuzeigen, welche in einem Template verwendet werden können.
                    Das ist nützlich, um den Endbenutzer über die auf dem Server installierten
                    Schriften zu informieren, da nur diese Schriftarten in einem Template verwendet
                    werden können. Im Falle, dass ein Template Schriften enthält, welche auf dem
                    Server nicht enthalten sind, wird eine andere Schriftart verwendet. Dies kann
                    zu unerwünschten Ergebnissen führen.
                </para>

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

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

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

                <para>
                    <emphasis>BEACHTE:</emphasis> Da sich der Rückgabewert diese Methode sehr
                    selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B.
                    <classname>Zend_Cache</classname> - das macht die Anwendung sichtbar schneller.
                </para>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.gettemplateformats">
                <title>Ein Array an unterstützten Dateiformaten für Templates erhalten</title>

                <para>
                    Der folgende Code zeigt ein Array aller unterstützten
                    Dateiformate für Templates. Diese Methode ist partiell nützlich im Fall, dass
                    eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt,
                    das Eingabeformat für den Erstellungsprozess des Dokuments auszuwählen.
                </para>

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

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

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

                <para>
                    <emphasis>BEACHTE:</emphasis> Da sich der Rückgabewert diese Methode sehr
                    selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B.
                    <classname>Zend_Cache</classname> - das macht die Anwendung sichtbar schneller.
                </para>
            </example>

            <example id="zend.service.livedocx.mailmerge.information.getdocumentformats">
                <title>Ein Array an unterstützten Dateiformaten für Dokumente erhalten</title>

                <para>
                    Der folgende Code zeigt ein Array aller unterstützten
                    Dateiformate für Dokumente. Diese Methode ist besonders nützlich, falls
                    eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt,
                    das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen.
                </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>Ein Array an unterstützten Dateiformaten für Bilder erhalten</title>

                <para>
                    Der folgende Code zeigt ein Array aller unterstützten
                    Dateiformate für Bilder. Diese Methode ist besonders nützlich, falls
                    eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt,
                    das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen.
                </para>

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

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

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

                <para>
                    <emphasis>BEACHTE:</emphasis> Da sich der Rückgabewert diese Methode sehr
                    selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B.
                    <classname>Zend_Cache</classname> - das macht die Anwendung sichtbar schneller.
                </para>
            </example>
        </sect3>
    </sect2>
</sect1>