| blob | 64b3af70ea91fd8432d70915340e7efa8c94f498 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.service.livedocx">
4 <title>Zend_Service_LiveDocx</title>
6 <sect2 id="zend.service.livedocx.introduction">
7 <title>Introduction to LiveDocx</title>
9 <para>
10 LiveDocx is a <acronym>SOAP</acronym> service that allows developers to generate word
11 processing documents by combining structured data from <acronym>PHP</acronym> with a
12 template, created in a word processor. The resulting document can be saved as a
13 <acronym>PDF</acronym>, <acronym>DOCX</acronym>, <acronym>DOC</acronym>,
14 <acronym>HTML</acronym> or <acronym>RTF</acronym> file. LiveDocx implements <ulink
15 url="http://en.wikipedia.org/wiki/Mail_merge">mail-merge</ulink> in
16 <acronym>PHP</acronym>.
17 </para>
19 <para>
20 The family of <classname>Zend_Service_LiveDocx</classname> components provides a clean
21 and simple interface to the <ulink url="http://www.livedocx.com">LiveDocx API</ulink>
22 and additionally offers functionality to improve network performance.
23 </para>
25 <para>
26 In addition to this section of the manual, if you are interested in learning more about
27 <classname>Zend_Service_LiveDocx</classname> and the backend <acronym>SOAP</acronym>
28 service LiveDocx, please take a look at the following resources:
29 </para>
31 <itemizedlist>
32 <listitem>
33 <para>
34 <emphasis>Shipped demonstration applications</emphasis>. There are a large
35 number of demonstration applications in the directory
36 <emphasis>/demos/Zend/Service/LiveDocx</emphasis> of the Zend Framework
37 distribution file or trunk version, checked out of the standard SVN repository.
38 These are designed to get you up to speed with
39 <classname>Zend_Service_LiveDocx</classname> within a matter of minutes.
40 </para>
41 </listitem>
43 <listitem>
44 <para>
45 <ulink url="http://www.phplivedocx.org/">
46 <classname>Zend_Service_LiveDocx</classname> blog and web site</ulink>.
47 </para>
48 </listitem>
50 <listitem>
51 <para>
52 <ulink url="http://www.livedocx.com/pub/documentation/api.aspx">
53 LiveDocx SOAP API documentation</ulink>.
54 </para>
55 </listitem>
57 <listitem>
58 <para>
59 <ulink url="https://api.livedocx.com/1.2/mailmerge.asmx?wsdl">
60 LiveDocx WSDL</ulink>.
61 </para>
62 </listitem>
64 <listitem>
65 <para>
66 <ulink url="https://www.livedocx.com/">LiveDocx blog and web site</ulink>.
67 </para>
68 </listitem>
69 </itemizedlist>
71 <sect3 id="zend.service.livedocx.account">
72 <title>Sign Up for an Account</title>
74 <para>
75 Before you can start using LiveDocx, you must first <ulink
76 url="https://www.livedocx.com/user/account_registration.aspx">sign up</ulink>
77 for an account. The account is completely free of charge and you only need to
78 specify a <emphasis>username</emphasis>, <emphasis>password</emphasis> and
79 <emphasis>e-mail address</emphasis>. Your login credentials will be dispatched to
80 the e-mail address you supply, so please type carefully.
81 </para>
82 </sect3>
84 <sect3 id="zend.service.livedocx.templates-documents">
85 <title>Templates and Documents</title>
87 <para>
88 LiveDocx differentiates between the following terms: 1)
89 <emphasis>template</emphasis> and 2) <emphasis>document</emphasis>. In order to
90 fully understand the documentation and indeed the actual <acronym>API</acronym>, it
91 is important that any programmer deploying LiveDocx understands the difference.
92 </para>
94 <para>
95 The term <emphasis>template</emphasis> is used to refer to the input file, created
96 in a word processor, containing formatting and text fields. You can download an
97 <ulink
98 url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-template.docx">example
99 template</ulink>, stored as a <acronym>DOCX</acronym> file. The term
100 <emphasis>document</emphasis> is used to refer to the output file that contains the
101 template file, populated with data - i.e. the finished document. You can download an
102 <ulink
103 url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-document.pdf">example
104 document</ulink>, stored as a <acronym>PDF</acronym> file.
105 </para>
106 </sect3>
108 <sect3 id="zend.service.livedocx.formats">
109 <title>Supported File Formats</title>
111 <para>
112 LiveDocx supports the following file formats:
113 </para>
115 <sect4 id="zend.service.livedocx.formats.template">
116 <title>Template File Formats (input)</title>
118 <para>
119 Templates can be saved in any of the following file formats:
120 </para>
122 <itemizedlist>
123 <listitem>
124 <para>
125 <ulink url="http://en.wikipedia.org/wiki/Office_Open_XML">DOCX</ulink> -
126 Office Open <acronym>XML</acronym> format
127 </para>
128 </listitem>
130 <listitem>
131 <para>
132 <ulink url="http://en.wikipedia.org/wiki/DOC_(computing)">DOC</ulink> -
133 Microsoft Word <acronym>DOC</acronym> format
134 </para>
135 </listitem>
137 <listitem>
138 <para>
139 <ulink url="http://en.wikipedia.org/wiki/Rich_Text_Format">RTF</ulink> -
140 Rich text file format
141 </para>
142 </listitem>
144 <listitem>
145 <para>
146 <ulink url="http://www.textcontrol.com/">TXD</ulink> - TX Text Control
147 format
148 </para>
149 </listitem>
150 </itemizedlist>
151 </sect4>
153 <sect4 id="zend.service.livedocx.formats.document">
154 <title>Document File Formats (output):</title>
156 <para>
157 The resulting document can be saved in any of the following file formats:
158 </para>
160 <itemizedlist>
161 <listitem>
162 <para>
163 <ulink url="http://en.wikipedia.org/wiki/Office_Open_XML">DOCX</ulink> -
164 Office Open <acronym>XML</acronym> format
165 </para>
166 </listitem>
168 <listitem>
169 <para>
170 <ulink url="http://en.wikipedia.org/wiki/DOC_(computing)">DOC</ulink> -
171 Microsoft Word <acronym>DOC</acronym> format
172 </para>
173 </listitem>
175 <listitem>
176 <para>
177 <ulink url="http://en.wikipedia.org/wiki/Xhtml">HTML</ulink> -
178 <acronym>XHTML</acronym> 1.0 transitional format
179 </para>
180 </listitem>
182 <listitem>
183 <para>
184 <ulink url="http://en.wikipedia.org/wiki/Rich_Text_Format">RTF</ulink> -
185 Rich text file format
186 </para>
187 </listitem>
189 <listitem>
190 <para>
191 <ulink
192 url="http://en.wikipedia.org/wiki/Portable_Document_Format">PDF</ulink>
193 - Acrobat Portable Document Format
194 </para>
195 </listitem>
197 <listitem>
198 <para>
199 <ulink url="http://www.textcontrol.com/">TXD</ulink> - TX Text Control
200 format
201 </para>
202 </listitem>
204 <listitem>
205 <para>
206 <ulink url="http://en.wikipedia.org/wiki/Text_file">TXT</ulink> -
207 <acronym>ANSI</acronym> plain text
208 </para>
209 </listitem>
210 </itemizedlist>
211 </sect4>
213 <sect4 id="zend.service.livedocx.formats.image">
214 <title>Image File Formats (output):</title>
216 <para>
217 The resulting document can be saved in any of the following graphical file
218 formats:
219 </para>
221 <itemizedlist>
222 <listitem>
223 <para>
224 <ulink url="http://en.wikipedia.org/wiki/BMP_file_format">BMP</ulink> -
225 Bitmap image format
226 </para>
227 </listitem>
229 <listitem>
230 <para>
231 <ulink url="http://en.wikipedia.org/wiki/GIF">GIF</ulink> - Graphics
232 Interchange Format
233 </para>
234 </listitem>
236 <listitem>
237 <para>
238 <ulink url="http://en.wikipedia.org/wiki/Jpg">JPG</ulink> - Joint
239 Photographic Experts Group format
240 </para>
241 </listitem>
243 <listitem>
244 <para>
245 <ulink
246 url="http://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG</ulink>
247 - Portable Network Graphics format
248 </para>
249 </listitem>
251 <listitem>
252 <para>
253 <ulink
254 url="http://en.wikipedia.org/wiki/Tagged_Image_File_Format">TIFF</ulink>
255 - Tagged Image File Format
256 </para>
257 </listitem>
259 <listitem>
260 <para>
261 <ulink url="http://en.wikipedia.org/wiki/Windows_Metafile">WMF</ulink> -
262 Windows Meta File format
263 </para>
264 </listitem>
265 </itemizedlist>
266 </sect4>
267 </sect3>
268 </sect2>
270 <sect2 id="zend.service.livedocx.mailmerge">
271 <title>Zend_Service_LiveDocx_MailMerge</title>
273 <para>
274 <classname>Zend_Service_LiveDocx_MailMerge</classname> is the mail-merge object in the
275 <classname>Zend_Service_LiveDocx</classname> family.
276 </para>
278 <sect3 id="zend.service.livedocx.mailmerge.generation">
279 <title>Document Generation Process</title>
281 <para>
282 The document generation process can be simplified with the following equation:
283 </para>
285 <para>
286 <emphasis>Template + Data = Document</emphasis>
287 </para>
289 <para>
290 Or expressed by the following diagram:
291 </para>
293 <para>
294 <inlinegraphic
295 fileref="figures/zend.service.livedocx.mailmerge.generation-diabasic_zoom.png"
296 format="PNG" />
297 </para>
299 <para>
300 Data is inserted into template to create a document.
301 </para>
303 <para>
304 A template, created in a word processing application, such as Microsoft Word, is
305 loaded into LiveDocx. Data is then inserted into the template and the resulting
306 document is saved to any supported format.
307 </para>
308 </sect3>
310 <sect3 id="zend.service.livedocx.mailmerge.templates">
311 <title>Creating Templates in Microsoft Word 2007</title>
313 <para>
314 Start off by launching Microsoft Word and creating a new document. Next, open up the
315 <emphasis>Field</emphasis> dialog box. This looks as follows:
316 </para>
318 <para>
319 <inlinegraphic
320 fileref="figures/zend.service.livedocx.mailmerge.templates-msworddialog_zoom.png"
321 format="PNG" />
322 </para>
324 <para>
325 Microsoft Word 2007 Field dialog box.
326 </para>
328 <para>
329 Using this dialog, you can insert the required merge fields into your document.
330 Below is a screenshot of a license agreement in Microsoft Word 2007. The merge
331 fields are marked as <code>{ MERGEFIELD FieldName }</code>:
332 </para>
334 <para>
335 <inlinegraphic
336 fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatefull_zoom.png"
337 format="PNG" />
338 </para>
340 <para>
341 Template in Microsoft Word 2007.
342 </para>
344 <para>
345 Now, save the template as <emphasis>template.docx</emphasis>.
346 </para>
348 <para>
349 In the next step, we are going to populate the merge fields with textual data from
350 <acronym>PHP</acronym>.
351 </para>
353 <para>
354 <inlinegraphic
355 fileref="figures/zend.service.livedocx.mailmerge.templates-mswordtemplatecropped_zoom.png"
356 format="PNG" />
357 </para>
359 <para>
360 Cropped template in Microsoft Word 2007.
361 </para>
363 <para>
364 To populate the merge fields in the above cropped screenshot of the <ulink
365 url="http://www.phplivedocx.org/wp-content/uploads/2009/01/license-agreement-template.docx">template</ulink>
366 in Microsoft Word, all we have to code is as follows:
367 </para>
369 <programlisting language="php"><![CDATA[
370 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
372 $phpLiveDocx->setUsername('myUsername')
373 ->setPassword('myPassword');
375 $phpLiveDocx->setLocalTemplate('template.docx');
377 $phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9')
378 ->assign('licensee', 'Henry Döner-Meyer')
379 ->assign('company', 'Co-Operation');
381 $phpLiveDocx->createDocument();
383 $document = $phpLiveDocx->retrieveDocument('pdf');
385 file_put_contents('document.pdf', $document);
386 ]]></programlisting>
388 <para>
389 The resulting document is written to disk in the file
390 <emphasis>document.pdf</emphasis>. This file can now be post-processed, sent via
391 e-mail or simply displayed, as is illustrated below in <emphasis>Document Viewer
392 2.26.1</emphasis> on <emphasis>Ubuntu 9.04</emphasis>:
393 </para>
395 <para>
396 <inlinegraphic
397 fileref="figures/zend.service.livedocx.mailmerge.templates-msworddocument_zoom.png"
398 format="PNG" />
399 </para>
401 <para>
402 Resulting document as <acronym>PDF</acronym> in Document Viewer 2.26.1.
403 </para>
404 </sect3>
406 <sect3 id="zend.service.livedocx.mailmerge.advanced">
407 <title>Advanced Mail-Merge</title>
409 <para>
410 <classname>Zend_Service_LiveDocx_MailMerge</classname> allows designers to insert
411 any number of text fields into a template. These text fields are populated with data
412 when <emphasis>createDocument()</emphasis> is called.
413 </para>
415 <para>
416 In addition to text fields, it is also possible specify regions of a document, which
417 should be repeated.
418 </para>
420 <para>
421 For example, in a telephone bill it is necessary to print out a list of all
422 connections, including the destination number, duration and cost of each call. This
423 repeating row functionality can be achieved with so called blocks.
424 </para>
426 <para>
427 <emphasis>Blocks</emphasis> are simply regions of a document, which are repeated
428 when <methodname>createDocument()</methodname> is called. In a block any number of
429 <emphasis>block fields</emphasis> can be specified.
430 </para>
432 <para>
433 Blocks consist of two consecutive document targets with a unique name. The following
434 screenshot illustrates these targets and their names in red:
435 </para>
437 <para>
438 <inlinegraphic
439 fileref="figures/zend.service.livedocx.mailmerge.advanced-mergefieldblockformat_zoom.png"
440 format="PNG" />
441 </para>
443 <para>
444 The format of a block is as follows:
445 </para>
447 <programlisting language="text"><![CDATA[
448 blockStart_ + unique name
449 blockEnd_ + unique name
450 ]]></programlisting>
452 <para>For example:</para>
454 <programlisting language="text"><![CDATA[
455 blockStart_block1
456 blockEnd_block1
457 ]]></programlisting>
459 <para>
460 The content of a block is repeated, until all data assigned in the block fields has
461 been injected into the template. The data for block fields is specified in
462 <acronym>PHP</acronym> as a multi-assoc array.
463 </para>
465 <para>
466 The following screenshot of a template in Microsoft Word 2007 shows how block fields
467 are used:
468 </para>
470 <para>
471 <inlinegraphic
472 fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblockstemplate_zoom.png"
473 format="PNG" />
474 </para>
476 <para>
477 Template, illustrating blocks in Microsoft Word 2007.
478 </para>
480 <para>
481 The following code populates the above template with data.
482 </para>
484 <programlisting language="php"><![CDATA[
485 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
487 $phpLiveDocx->setUsername('myUsername')
488 ->setPassword('myPassword');
490 $phpLiveDocx->setLocalTemplate('template.doc');
492 $billConnections = array(
493 array(
494 'connection_number' => '+49 421 335 912',
495 'connection_duration' => '00:00:07',
496 'fee' => '€ 0.03',
497 ),
498 array(
499 'connection_number' => '+49 421 335 913',
500 'connection_duration' => '00:00:07',
501 'fee' => '€ 0.03',
502 ),
503 array(
504 'connection_number' => '+49 421 335 914',
505 'connection_duration' => '00:00:07',
506 'fee' => '€ 0.03',
507 ),
508 array(
509 'connection_number' => '+49 421 335 916',
510 'connection_duration' => '00:00:07',
511 'fee' => '€ 0.03',
512 ),
513 );
515 $phpLiveDocx->assign('connection', $billConnections);
517 // ... assign other data here ...
519 $phpLiveDocx->createDocument();
520 $document = $phpLiveDocx->retrieveDocument('pdf');
521 file_put_contents('document.pdf', $document);
522 ]]></programlisting>
524 <para>
525 The data, which is specified in the array <varname>$billConnections</varname> is
526 repeated in the template in the block connection. The keys of the array
527 (<varname>connection_number</varname>, <varname>connection_duration</varname> and
528 <varname>fee</varname>) are the block field names - their data is inserted, one row
529 per iteration.
530 </para>
532 <para>
533 The resulting document is written to disk in the file
534 <emphasis>document.pdf</emphasis>. This file can now be post-processed, sent via
535 e-mail or simply displayed, as is illustrated below in <emphasis>Document Viewer
536 2.26.1</emphasis> on <emphasis>Ubuntu 9.04</emphasis>:
537 </para>
539 <para>
540 <inlinegraphic
541 fileref="figures/zend.service.livedocx.mailmerge.advanced-mswordblocksdocument_zoom.png"
542 format="PNG" />
543 </para>
545 <para>
546 Resulting document as <acronym>PDF</acronym> in Document Viewer 2.26.1.
547 </para>
549 <para>
550 You can download the <acronym>DOC</acronym> <ulink
551 url="http://www.phplivedocx.org/wp-content/uploads/2009/01/telephone-bill-template.doc">template
552 file</ulink> and the resulting <ulink
553 url="http://www.phplivedocx.org/wp-content/uploads/2009/01/telephone-bill-document.pdf">PDF
554 document</ulink>.
555 </para>
557 <para>
558 <emphasis>NOTE:</emphasis> blocks may not be nested.
559 </para>
560 </sect3>
562 <sect3 id="zend.service.livedocx.mailmerge.bitmaps">
563 <title>Generating bitmaps image files</title>
565 <para>
566 In addition to document file formats,
567 <classname>Zend_Service_LiveDocx_MailMerge</classname> also allows documents to be
568 saved to a number of image file formats (<acronym>BMP</acronym>,
569 <acronym>GIF</acronym>, <acronym>JPG</acronym>, <acronym>PNG</acronym> and
570 <acronym>TIFF</acronym>). Each page of the document is saved to one file.
571 </para>
573 <para>
574 The following sample illustrates the use of <methodname>getBitmaps($fromPage,
575 $toPage, $zoomFactor, $format)</methodname> and
576 <methodname>getAllBitmaps($zoomFactor, $format)</methodname>.
577 </para>
579 <para>
580 <varname>$fromPage</varname> is the lower-bound page number of the page range that
581 should be returned as an image and <varname>$toPage</varname> the upper-bound page
582 number. <varname>$zoomFactor</varname> is the size of the images, as a percent,
583 relative to the original page size. The range of this parameter is 10 to 400.
584 <varname>$format</varname> is the format of the images returned by this method. The
585 supported formats can be obtained by calling
586 <methodname>getImageFormats()</methodname>.
587 </para>
589 <programlisting language="php"><![CDATA[
590 $date = new Zend_Date();
591 $date->setLocale('en_US');
593 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
595 $phpLiveDocx->setUsername('myUsername')
596 ->setPassword('myPassword');
598 $phpLiveDocx->setLocalTemplate('template.docx');
600 $phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9')
601 ->assign('licensee', 'Daï Lemaitre')
602 ->assign('company', 'Megasoft Co-operation')
603 ->assign('date', $date->get(Zend_Date::DATE_LONG))
604 ->assign('time', $date->get(Zend_Date::TIME_LONG))
605 ->assign('city', 'Lyon')
606 ->assign('country', 'France');
608 $phpLiveDocx->createDocument();
610 // Get all bitmaps
611 // (zoomFactor, format)
612 $bitmaps = $phpLiveDocx->getAllBitmaps(100, 'png');
614 // Get just bitmaps in specified range
615 // (fromPage, toPage, zoomFactor, format)
616 // $bitmaps = $phpLiveDocx->getBitmaps(2, 2, 100, 'png');
618 foreach ($bitmaps as $pageNumber => $bitmapData) {
619 $filename = sprintf('documentPage%d.png', $pageNumber);
620 file_put_contents($filename, $bitmapData);
621 }
622 ]]></programlisting>
624 <para>
625 This produces two files (<filename>documentPage1.png</filename> and
626 <filename>documentPage2.png</filename>) and writes them to disk in the same
627 directory as the executable <acronym>PHP</acronym> file.
628 </para>
630 <para>
631 <inlinegraphic
632 fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage1_zoom.png"
633 format="PNG" />
634 </para>
636 <para>
637 documentPage1.png.
638 </para>
640 <para>
641 <inlinegraphic
642 fileref="figures/zend.service.livedocx.mailmerge.bitmaps-documentpage2_zoom.png"
643 format="PNG" />
644 </para>
646 <para>
647 documentPage2.png.
648 </para>
649 </sect3>
651 <sect3 id="zend.service.livedocx.mailmerge.templates-types">
652 <title>Local vs. Remote Templates</title>
654 <para>
655 Templates can be stored <emphasis>locally</emphasis>, on the client machine, or
656 <emphasis>remotely</emphasis>, on the server. There are advantages and disadvantages
657 to each approach.
658 </para>
660 <para>
661 In the case that a template is stored locally, it must be transfered from the client
662 to the server on every request. If the content of the template rarely changes, this
663 approach is inefficient. Similarly, if the template is several megabytes in size, it
664 may take considerable time to transfer it to the server. Local template are useful
665 in situations in which the content of the template is constantly changing.
666 </para>
668 <para>
669 The following code illustrates how to use a local template.
670 </para>
672 <programlisting language="php"><![CDATA[
673 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
675 $phpLiveDocx->setUsername('myUsername')
676 ->setPassword('myPassword');
678 $phpLiveDocx->setLocalTemplate('./template.docx');
680 // assign data and create document
681 ]]></programlisting>
683 <para>
684 In the case that a template is stored remotely, it is uploaded once to the server
685 and then simply referenced on all subsequent requests. Obviously, this is much
686 quicker than using a local template, as the template does not have to be transfered
687 on every request. For speed critical applications, it is recommended to use the
688 remote template method.
689 </para>
691 <para>
692 The following code illustrates how to upload a template to the server:
693 </para>
695 <programlisting language="php"><![CDATA[
696 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
698 $phpLiveDocx->setUsername('myUsername')
699 ->setPassword('myPassword');
701 $phpLiveDocx->uploadTemplate('template.docx');
702 ]]></programlisting>
704 <para>
705 The following code illustrates how to reference the remotely stored template on all
706 subsequent requests:
707 </para>
709 <programlisting language="php"><![CDATA[
710 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
712 $phpLiveDocx->setUsername('myUsername')
713 ->setPassword('myPassword');
715 $phpLiveDocx->setRemoteTemplate('template.docx');
717 // assign data and create document
718 ]]></programlisting>
719 </sect3>
721 <sect3 id="zend.service.livedocx.mailmerge.information">
722 <title>Getting Information</title>
724 <para>
725 <classname>Zend_Service_LiveDocx_MailMerge</classname> provides a number of methods
726 to get information on field names, available fonts and supported formats.
727 </para>
729 <example id="zend.service.livedocx.mailmerge.information.getfieldname">
730 <title>Get Array of Field Names in Template</title>
732 <para>
733 The following code returns and displays an array of all field names in the
734 specified template. This functionality is useful, in the case that you create an
735 application, in which an end-user can update a template.
736 </para>
738 <programlisting language="php"><![CDATA[
739 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
741 $phpLiveDocx->setUsername('myUsername')
742 ->setPassword('myPassword');
744 $templateName = 'template-1-text-field.docx';
745 $phpLiveDocx->setLocalTemplate($templateName);
747 $fieldNames = $phpLiveDocx->getFieldNames();
748 foreach ($fieldNames as $fieldName) {
749 printf('- %s%s', $fieldName, PHP_EOL);
750 }
751 ]]></programlisting>
752 </example>
754 <example id="zend.service.livedocx.mailmerge.information.getblockfieldname">
755 <title>Get Array of Block Field Names in Template</title>
757 <para>
758 The following code returns and displays an array of all block field names in the
759 specified template. This functionality is useful, in the case that you create an
760 application, in which an end-user can update a template. Before such templates
761 can be populated, it is necessary to find out the names of the contained block
762 fields.
763 </para>
765 <programlisting language="php"><![CDATA[
766 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
768 $phpLiveDocx->setUsername('myUsername')
769 ->setPassword('myPassword');
771 $templateName = 'template-block-fields.doc';
772 $phpLiveDocx->setLocalTemplate($templateName);
774 $blockNames = $phpLiveDocx->getBlockNames();
775 foreach ($blockNames as $blockName) {
776 $blockFieldNames = $phpLiveDocx->getBlockFieldNames($blockName);
777 foreach ($blockFieldNames as $blockFieldName) {
778 printf('- %s::%s%s', $blockName, $blockFieldName, PHP_EOL);
779 }
780 }
781 ]]></programlisting>
782 </example>
784 <example id="zend.service.livedocx.mailmerge.information.getfontnames">
785 <title>Get Array of Fonts Installed on Server</title>
787 <para>
788 The following code returns and displays an array of all fonts installed on the
789 server. You can use this method to present a list of fonts which may be used in
790 a template. It is important to inform the end-user about the fonts installed on
791 the server, as only these fonts may be used in a template. In the case that a
792 template contains fonts, which are not available on the server,
793 font-substitution will take place. This may lead to undesirable results.
794 </para>
796 <programlisting language="php"><![CDATA[
797 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
799 $phpLiveDocx->setUsername('myUsername')
800 ->setPassword('myPassword');
802 Zend_Debug::dump($phpLiveDocx->getFontNames());
803 ]]></programlisting>
805 <para>
806 <emphasis>NOTE:</emphasis> As the return value of this method changes very
807 infrequently, it is highly recommended to use a cache, such as
808 <classname>Zend_Cache</classname> - this will considerably speed up your
809 application.
810 </para>
811 </example>
813 <example id="zend.service.livedocx.mailmerge.information.gettemplateformats">
814 <title>Get Array of Supported Template File Formats</title>
816 <para>
817 The following code returns and displays an array of all supported template file
818 formats. This method is particularly useful in the case that a combo list should
819 be displayed that allows the end-user to select the input format of the
820 documentation generation process.
821 </para>
823 <programlisting language="php"><![CDATA[
824 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge()
826 $phpLiveDocx->setUsername('myUsername')
827 ->setPassword('myPassword');
829 Zend_Debug::dump($phpLiveDocx->getTemplateFormats());
830 ]]></programlisting>
832 <para>
833 <emphasis>NOTE:</emphasis> As the return value of this method changes very
834 infrequently, it is highly recommended to use a cache, such as
835 <classname>Zend_Cache</classname> - this will considerably speed up your
836 application.
837 </para>
838 </example>
840 <example id="zend.service.livedocx.mailmerge.information.getdocumentformats">
841 <title>Get Array of Supported Document File Formats</title>
843 <para>
844 The following code returns and displays an array of all supported document file
845 formats. This method is particularly useful in the case that a combo list should
846 be displayed that allows the end-user to select the output format of the
847 documentation generation process.
848 </para>
850 <programlisting language="php"><![CDATA[
851 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
853 $phpLiveDocx->setUsername('myUsername')
854 ->setPassword('myPassword');
856 Zend_Debug::dump($phpLiveDocx->getDocumentFormats());
857 ]]></programlisting>
858 </example>
860 <example id="zend.service.livedocx.mailmerge.information.getimageformats">
861 <title>Get Array of Supported Image File Formats</title>
863 <para>
864 The following code returns and displays an array of all supported image file
865 formats. This method is particularly useful in the case that a combo list should
866 be displayed that allows the end-user to select the output format of the
867 documentation generation process.
868 </para>
870 <programlisting language="php"><![CDATA[
871 $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();
873 $phpLiveDocx->setUsername('myUsername')
874 ->setPassword('myPassword');
876 Zend_Debug::dump($phpLiveDocx->getImageFormats());
877 ]]></programlisting>
879 <para>
880 <emphasis>NOTE:</emphasis> As the return value of this method changes very
881 infrequently, it is highly recommended to use a cache, such as
882 <classname>Zend_Cache</classname> - this will considerably speed up your
883 application.
884 </para>
885 </example>
886 </sect3>
887 </sect2>
888 </sect1>
889 <!--
890 vim:se ts=4 sw=4 tw=100 et:
891 -->