forked from javigomez/lib_tbs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tbs_plugin_opentbs.html
executable file
·564 lines (563 loc) · 41.4 KB
/
tbs_plugin_opentbs.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>OpenTBS - create OpenOffice and Ms Office documents with PHP</title>
<style type="text/css">
<!--
body, td, th {
font-family: Arial, sans-serif;
font-size: 13px;
}
h4 {
font-size: 13px;
font-weight:normal;
margin-bottom: 5px;
}
h5 {
font-size: 13px;
font-weight:normal;
text-decoration:underline;
margin-bottom: 5px;
}
ul {
list-style-type:square;
list-style-position:inside;
padding-left:0;
}
.shift {
margin-left: 10px;
padding: 3px;
}
.code {
font-family: "Courier New", Courier, monospace;
font-size: 13px;
color: #036;
background-color: #E1EBFF;
padding-top: 3px;
padding-bottom: 3px;
}
.template {
font-family: "Courier New", Courier, monospace;
font-size: 12px;
color: #030;
background-color: #E1FFEB;
padding-top: 3px;
padding-bottom: 3px;
}
.versioning {
font-style: italic;
color: #060;
}
.smallcode {
font-family: "Courier New", Courier, monospace;
font-size: 13px;
color: #036;
}
.warning {
color: #F30;
}
-->
</style>
<meta name="Keywords" content="openxml, odf, template" />
</head>
<body>
<h1>OpenTBS - create OpenOffice and Ms Office documents with PHP</h1>
<div>version 1.7.6, 2012-06-06, by Skrol29<br />
help file modified on 2012-06-06</div>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#install">Installing</a></li>
<li><a href="#principles">Understanding principles</a></li>
<li><a href="#coding">Synopsis and code examples</a>
<ul>
<li>4.1. <a href="#preparation">Preparation of TinyButStrong Template Engine with the OpenTBS plug-in</a></li>
<li>4.2. <a href="#loadtemplate">Method LoadTemplate()</a></li>
<li>4.3. <a href="#show">Method Show()</a></li>
<li>4.4. <a href="#chart">Change data of series in charts</a></li>
<li>4.5. <a href="#pic">Change pictures in the document</a></li>
<li>4.6. <a href="#modify_contents">Manual modification in the contents</a></li>
<li>4.7. <a href="#modify_files">Manual modification of files in the archive</a></li>
<li>4.8. <a href="#misc">Miscellaneous</a></li>
</ul>
</li>
<li><a href="#demo">Demo</a></li>
<li><a href="#debug">Debugging your template</a></li>
<li><a href="#zlib">What to do if Zlib extension is not enabled with PHP?</a></li>
<li><a href="#changelog">Changelog</a></li>
<li><a href="#license">License</a></li>
</ol>
<h2><a name="intro" id="intro"></a>1. Introduction</h2>
<p>OpenTBS is a plug-in for the <a href="http://www.tinybutstrong.com">TinyButStrong</a> Template Engine. <br />
<br />
TinyButStrong is a PHP Template Engine which has special template syntax and allows you to design templates in their natural editing tools. But it normally works only for Text files, including XML and HTML. <br />
<br />
With TinyButStrong and its plug-in OpenTBS, you can use the template engine to merge <strong>OpenOffice</strong> documents and <strong>Ms Office </strong> documents with lot of facilities. All <strong>OpenDocument Format</strong> (ODF) and <strong> Office Open XML</strong> (OOXML) can be merged with OpenTBS, and also XPS files (XPS is a PDF competitor provided by Microsoft). In fact, all zip archives containing Xml/Html/Text files can be merged with OpenTBS.</p>
<h5>What is special to OpenTBS:</h5>
<ul>
<li>Design your templates directly with OpenOffice or MS Office.</li>
<li>No exe file needed to merge documents.</li>
<li>No temporary files needed to merge documents.</li>
<li>Output directly as an http download, a new file on the disk, or as a string (for file attachment for example).</li>
<li>Works with both PHP 4 and PHP 5.</li>
<li>No PHP extension is required (If the Zlib extension is enabled it becomes easier to use templates, see more detail below)</li>
</ul>
<p> You should know Template Engines and more specifically <a href="http://www.tinybutstrong.com">TinyButStrong</a> to use
OpenTBS.</p>
<h2><a name="install" id="install"></a>2. Installing</h2>
<h5>Requirements:</h5>
<ul>
<li>TinyButStrong version 3.7.0 or higher. (OpenTBS versions <= 1.5.0 require TinyButStrong version 3.6.0 or higher)</li>
<li>PHP 4.3 or higher, PHP 5</li>
<li>It is better to have the <a href="http://www.php.net/manual/en/book.zlib.php">Zlib</a> extension enabled on your PHP installation. If it's not, <a href="#zlib">here is what to do</a>.</li>
</ul>
<h5>Installation:</h5>
<p> Just put the file "tbs_plugin_opentbs.php" with your PHP scripts.</p>
<h2><a name="principles" id="principles"></a>3. Understanding principles</h2>
<p>It is important to figure out that OpenOffice and Ms Office (since version 2007) documents are technically zip archives containing XML files, even if the extension of the document is not ".zip". Those zip archives can contain other file types like pictures or sounds, but the document structure and the text contents are saved as XML files. The <a href="xml_synopsis.txt">XML Synopsis</a> summarizes the key entities of XML sub-files contained in OpenOffice and Ms Office documents.</p>
<p>TinyButStrong can merge XML files, but cannot read zip archives by itself. The plug-in OpenTBS extends the TinyButStrong methods <a href="http://www.tinybutstrong.com/manual.php#php_loadtemplate">LoadTemplate()</a> and <a href="http://www.tinybutstrong.com/manual.php#php_show">Show()</a> to make them working with zip archives. <span id="result_box"><span title="">But you do not have to bother with it because OpenTBS is managing archives in a way that is invisible for you.</span></span></p>
<p> When the OpenTBS plugin is installed, the LoadTemplate() method becomes able to first load a zip archive (an OpenOffice or Ms Office document), and then to load the contents of any XML or Text files stored in the archive. You can then merge the contents of XML or Text files with all features of the TinyButStrong template engine. At the end, the Show() method does render the entire zip archive including modified stored files. The render can be done as an HTTP download, a news file on the server's disk, or in a PHP string.</p>
<p>Since OpenTBS version 1.3, you can also add and delete files in the archive. Before this version you could only modify existing files in the archive.<br />
</p>
<p> <a name="extension" id="extension"></a>OpenTBS has <strong>automatic extension recognition</strong>. When you load a document which has one of the following extensions { odt, odg, ods, odf, odp, odm, docx, xlsx, pptx }, then the main XML file of the archive are automatically loaded, and some special character conversion are preset. For example, for all OpenDocument files, the stored file "content.xml" is automatically loaded.<br />
Since version 1.6.0,
if the extension is not recognized then OpenTBS also try to find the document by the sub-file presence. And if all fails, then you can force the document type using a <a href="#force_doctype">special command</a>.</p>
<h2><a name="coding" id="coding"></a>4. Synopsis and code examples</h2>
<h3><a name="preparation" id="preparation"></a>4.1. Preparation of TinyButStrong Template Engine with the OpenTBS plug-in</h3>
<div class="shift code">include_once('tbs_class.php');<br />
include_once('tbs_plugin_opentbs.php');<br />
<br />
$TBS = new clsTinyButStrong;<br />
$TBS->Plugin(TBS_INSTALL, OPENTBS_PLUGIN);</div>
<h3><a name="loadtemplate" id="loadtemplate"></a>4.2. Method LoadTemplate()</h3>
<h4>• Load an archive with the automatic extension recognition (<a href="#extension">explained above</a>): </h4>
<div class="shift">
<div class="code">$TBS->LoadTemplate('document.odt'); // Load the archive 'document.odt'.</div>
</div>
<h4>• Load an archive without the automatic extension recognition:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS version 1.1)</span>
<div class="code">$TBS->LoadTemplate('document.odt#');</div>
</div>
<h4>• Load an archive and one file stored in this archive:</h4>
<div class="shift code">$TBS->LoadTemplate('document.odt#content.xml');</div>
<h4>• Load an archive and several files stored in this archive:</h4>
<div class="shift code">$TBS->LoadTemplate('document.odt#content.xml;settings.xml');</div>
<h4>• Load a stored file from the current archive:</h4>
<div class="shift">
<div class="code">$TBS->LoadTemplate('#content.xml'); // Load the stored file 'content.xml' from the current archive.</div>
<p>The archive must be previously loaded.<br />
If the file is stored in a subfolder, then indicate the full path. For example: 'word/document.xml'.</p>
</div>
<h4>• Load an archive with special data conversion:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS version 1.3.2)</span>
<div class="code">$TBS->LoadTemplate('document.odt', OPENTBS_ALREADY_UTF8);</div>
<p>OpenTBS manages XML files that are UTF8 encoded. But by default, it assumes that all the data to merge (which can come from PHP or SQL) is Ascii encoded, and thus it performs conversions. If you want to define the data conversion, then you can use one of the following constants:</p>
<ul>
<li><span class="smallcode">OPENTBS_DEFAULT</span>: OpenTBS assumes that all data is ASCII encoded,</li>
<li><span class="smallcode">OPENTBS_ALREADY_UTF8</span>: OpenTBS assumes that all data is already UTF8 encoded,</li>
<li><span class="smallcode">OPENTBS_ALREADY_XML</span>: OpenTBS assumes that all data is already XML encoded, and thus it won't convert data at all. Take care of that option.</li>
</ul>
<p> Please note that if
you need to change the data conversion for one or few fields only in your template, then you can use parameter "<span class="smallcode">htmlconv</span>" (see the TBS documentation for more details). </p>
</div>
<h3><a name="show" id="show"></a>4.3. Method Show()</h3>
<p>Render options for OpenTBS:</p>
<h4>• Render the merged archive as an HTTP download: ($file_name is optional)</h4>
<div class="shift code">$TBS->Show(OPENTBS_DOWNLOAD, $file_name);</div>
<h4>• Render the merged archive as an HTTP output with your customized HTTP headers:</h4>
<div class="shift code">header(...); // your custom headers here<br />
$TBS->Show(OPENTBS_NOHEADER); // output the binary file without header</div>
<h4>• Render the merged archive as a new file saved on the server's disk:</h4>
<div class="shift code">$TBS->Show(OPENTBS_FILE, $file_name);</div>
<h4>• Render the merged archive as a PHP string:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.1)</span>
<div class="code"> $TBS->Show(OPENTBS_STRING);<br />
$string = $TBS->Source; </div>
<p>When you use <span class="smallcode">OPENTBS_STRING</span> then there is no output for the client. But instead, the binary source of the archive is placed into property $TBS->Source. This feature can be useful, for example, when you want to place the merged document into an email as an attached file.</p>
</div>
<h3><a name="chart" id="chart"></a>4.4. Change data of series in charts</h3>
<h4>• Change series in charts:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.6.0, for Ms Word only)</span>
<div class="code">Example: $TBS->PlugIn(OPENTBS_CHART, $ChartNameOrNum, $SeriesNameOrNum, $NewValues, $NewLegend=false)</div>
<p>This command changes the values of a series in a Chart of the document. The chart will be automatically actualized when the merged document is opened because OpenTBS also breaks the link between the chart and its cached view.<br />
The result is <span class="smallcode">true</span> if the series is modified with success, otherwise the result is <span class="smallcode">false</span>. <br />
</p>
<table width="100%" border="0" cellspacing="2" cellpadding="0">
<tr>
<th align="left" valign="top">Argument</th>
<th align="left">Description</th>
</tr>
<tr>
<td valign="top" class="smallcode">$CharteNameOrNum</td>
<td>Internal name of the XML file that contains the chart definition (with or without the extension), or the order number of the chart in the document (first is number 1).<br />
You can use the command <a href="#debugmode">OPENTBS_DEBUG_CHART_LIST</a> in order to view all chart internal names in the document.<br />
<span class="smallcode">$CarteNameOrNum</span> is typically <span class="smallcode">'chart1'</span> or <span class="smallcode">1</span>.</td>
</tr>
<tr>
<td valign="top" class="smallcode">$SeriesNumOrName</td>
<td>Exact caption of the series in the chart, or its number (first is number 1). Typically <span class="smallcode">'Series 1'</span> or <span class="smallcode">1</span>. </td>
</tr>
<tr>
<td valign="top" class="smallcode">$NewValues</td>
<td>The new data of the series. Must be an array, or value <span class="smallcode">false</span> if you want to delete the series.<br />
The array can store data with 2 possibilities:<br />
<span class="code">$NewValues = array( array('cat1', 'cat2', 'cat3', ...), array(val1, val2, val3, ...) );</span><br />
or <br />
<span class="code">$NewValues = array('cat1'=>val1, 'cat2'=>val2, 'cat3'=>val3, ...);</span><br />
If the chart type is "X Y (Scatter)" then you must use only the first data store type.</td>
</tr>
<tr>
<td valign="top" class="smallcode">$NewLegend</td>
<td>Optional. The new caption of the series. </td>
</tr>
</table>
<h5>Please note:</h5>
<ul>
<li>The type of the chart won't be changed.</li>
<li>Some charts may not be recognized by this feature when the Word document is created with Word <= 2007 or is saved with a Compatibility Mode. You have to convert charts to have it work (right on the chart and choose "Convert"). You can use the command <a href="#debugmode">OPENTBS_DEBUG_CHART_LIST</a> in order to view all unsupported charts in the document.</li>
</ul>
</div>
<h3><a name="pic" id="pic2"></a>4.5. Change pictures in the document</h3>
<h4>• Change an internal picture with a new one:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS version 1.4.0, for OpenOffice and MsOffice documents only)</span>
<div class="template">Example: [onshow.x;ope=changepic;from='../pic/[val].gif';as='[val].gif';default=current]</div>
<p>I the example above, $x is a PHP global variable containing the name or the path for an external picture file. But the feature works simillary with items data merged with a TBS block.</p>
<p> When a TBS field having <span class="smallcode">"ope=changepic"</span> is merged in the template, then OpenTBS will search the first picture located before the field (to be more precise, the TBS field must be located somewhere inside or after the opening tag of the picture in the template source code), and then it will change the picture assuming that the value of the field is the path for a picture file on the server. You don't have to care about loading the picture file in the document, OpenTBS will manage this for you.</p>
<p>Note that parameter <span class="smallcode">"ope=changepic"</span> is a feature provided by the OpenTBS plug-in, which extends the "<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_ope">ope</a>" parameter natively present with TBS.<br />
<br />
In order to
simplify your coding, they are other complementary parameters that are provided for the <span class="smallcode">changepic</span> parameter: </p>
<table border="0" cellpadding="0" cellspacing="4" style="marging-left:20px;">
<tr>
<th align="left">Parameter</th>
<th align="left">Description</th>
</tr>
<tr>
<td valign="top"><span class="smallcode">from</span></td>
<td>Reformulate the path of the picture to insert. The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter "<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_file">file</a>". Parameter "<span class="smallcode">from</span>" is optional.</td>
</tr>
<tr>
<td valign="top"><span class="smallcode">as</span></td>
<td> Reformulate name of the picture that it will take inside the document. It is rare to need it, but it can help in some cases. Note that the external picture file is not renamed. The new name must be defined without path.
The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter "<a href="http://www.tinybutstrong.com/manual.php#html_field_prm_file">file</a>". Parameter <span class="smallcode">"as"</span> is optional.</td>
</tr>
<tr>
<td valign="top"><span class="smallcode">default</span></td>
<td>Define the picture that should be used when the expected one is not found. The parameter's value must be the path of a file on the server, or the keyword "<span class="smallcode">current"</span>. If you've set <span class="smallcode">"default=current"</span> then OpenTBS will let the picture of the template if the expected one is not found.</td>
</tr>
<tr>
<td valign="top"><span class="smallcode">adjust</span></td>
<td>Adjust the size of the picture in the document. This parameter requires that PHP is configured with the <a href="http://www.php.net/manual/en/book.image.php">GD</a> extension, which is usually the case.<br />
Values can be on of the followings:<br />
<table border="0" cellspacing="0" cellpadding="3">
<tr>
<td valign="top"><span class="smallcode">adjust</span> (or <span class="smallcode">adjust=inside</span>)</td>
<td>The picture is adjusted to enter into the picture bounds of the template.</td>
</tr>
<tr>
<td valign="top"><span class="smallcode">adjust=samewidth</span><br /></td>
<td>The picture is adjusted to have the same width than the picture of the template.</td>
</tr>
<tr>
<td valign="top" class="smallcode">adjust=sameheigth</td>
<td>The picture is adjusted to have the same height than the picture of the template.</td>
</tr>
<tr>
<td valign="top"><span class="smallcode">adjust=100%</span> (or
another pourcentage) </td>
<td>The picture is adjusted to be proportional to the originial size.</td>
</tr>
</table>
<span class="versioning">Parameter adjust is supported since OpenTBS version 1.7.0.</span></td>
</tr>
</table>
</div>
<h3><a name="modify_contents" id="modify2"></a>4.6. Manual modification in the contents</h3>
<p><span class="versioning">The following commands are supported since OpenTBS version 1.7.0</span>:</p>
<table border="0" cellspacing="1" cellpadding="0">
<tr>
<th align="left">Command</th>
<th align="left">Desciption</th>
</tr>
<tr>
<td valign="top" nowrap="nowrap"><span class="smallcode">$TBS->PlugIn(OPENTBS_SELECT_MAIN)</span></td>
<td>Select and load the main sub-file in the opened template. For example in a Writer document, or an Ms Word document, this command can bring you back from the merging of a header to the main body.</td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_SELECT_SHEET, $Sheet)</td>
<td><p>Select and load the sub-file corresponding to $Sheet.<br />
This command will raise an error if the opened template is not a Workbook (Ms Word or OpenOffice Calc). This command is useless for an
OpenOffice Calc workbook because all sheets are saved in single sub-file. Nevertheless using it won't raise an error.<br />
<span class="smallcode">$Sheet</span> must be a sheet identifier.<br />
A sheet identifier can be
either an integer corresponding to the index of the sheet, or a string corresponding to the name of the sheet.<br />
Use command <span class="smallcode">$TBS->PlugIn(<a href="#debugmode">OPENTBS_DEBUG_INFO</a>)</span> to list all id and name of sheets in current Workbook.</p></td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DISPLAY_SHEETS, $Sheets[, $Visible])</td>
<td>Make one or several sheets visible or hidden.<br />
This command will raise an error if the opened template is not a Workbook.<br />
<span class="smallcode">$Sheets</span> must be an array of sheet identifier, or even a single sheet identifier. See command <span class="smallcode">OPENTBS_SELECT_SHEET</span> for more details about sheet identifiers.<br />
<span class="smallcode">$Visible</span> must be a boolean, default value is <span class="smallcode">true</span>.</td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DELETE_SHEETS, $Sheets[, $Delete])</td>
<td>Make on or several sheets deleted or not.<br />
This command will raise an error if the opened template is not a Workbook.<br />
<span class="smallcode">$Sheets</span> must be an array of sheet identifier, or even a single sheet identifier. See command <span class="smallcode">OPENTBS_SELECT_SHEET</span> for more details about sheet identifiers.<br />
<span class="smallcode">$Delete</span> must be a boolean, default value is <span class="smallcode">true</span>.<br />
<em class="warning">Please note that for now, you must not delete a sheet that contains a Pivot Table because this will produce an error when the workbook is opened.</em></td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DELETE_COMMENTS)</td>
<td>Delete all usual user comments in the opened template. </td>
</tr>
<tr>
<td valign="top" nowrap="nowrap"><span class="smallcode">$TBS->PlugIn(OPENTBS_DELETE_ELEMENTS, $Elements)</span></td>
<td>Delete XML elements in the current sub-file.<br />
<span class="smallcode">$Elements</span> must be an array of strings. For example:<br />
<span class="smallcode">$Elements = array('w:bookmarkStart', 'w:bookmarkEnd')</span><br />
This will delete all bookmarks in an Ms Word document.
</td>
</tr>
</table>
<h3><a name="modify_files" id="modify_files"></a>4.7. Manual modification of files in the archive</h3>
<h4 style="display:inline">• Check if a file does exists in the archive:</h4>
<div class="shift">
<div class="code">$TBS->Plugin(OPENTBS_FILEEXISTS, $Name)
</div>
<p>Return <span class="smallcode">true</span> or <span class="smallcode">false</span>. $Name must include the inner path.<br />
For example : $Name = 'META-INF/manifest.xml';</p>
<div class="versioning">(supported since OpenTBS version 1.7.4)</div>
</div>
<h4>• Add any new file in the archive:</h4>
<div class="shift">
<div class="code">// OpenTBS >= 1.6.0<br />
$TBS->Plugin(OPENTBS_ADDFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true); <br />
<br />
// Deprecated since OpenTBS 1.6.0<br />
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_ADDFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true); </div>
<p> If $Data is false then the previously add file with the given name is canceled if any.</p>
<p> $DataType must be <span class="smallcode">OPENTBS_STRING</span> if $Data is the content to add ; it must be <span class="smallcode">OPENTBS_FILE</span> if $Data is the path of the external file to insert.</p>
<p> $Compress can be true, false or an array with keys ('meth','len_u','crc32') which means that the data is already previously compressed.</p>
<div class="versioning">(supported since OpenTBS version 1.3)</div>
</div>
<h4>• Replace an existing file in the archive:</h4>
<div class="shift">
<div class="code">$TBS->Plugin(OPENTBS_DELETEFILE, $Name, $Data, $DataType=OPENTBS_STRING, $Compress=true);
</div>
<p>The arguments are the same as command <span class="smallcode">OPENTBS_ADDFILE</span>.<br />
Please note that any TBS
merge on a file in the archive will cancel previous or future replacements.</p>
<div class="versioning">(supported since OpenTBS version 1.7.4)</div>
</div>
<h4>• Delete an existing file in the archive:</h4>
<div class="shift">
<div class="code">// OpenTBS >= 1.6.0<br />
$TBS->Plugin(OPENTBS_DELETEFILE, $Name);<br />
<br />
// Deprecated since OpenTBS 1.6.0<br />
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_DELETEFILE, $Name);</div>
<p>Delete the existing file in the archive, or a file previously added using the <span class="smallcode">OPENTBS_ADDFILE</span> command.</p>
<div class="versioning">(supported since OpenTBS version 1.3)</div>
</div>
<h4>• Reset all modifications in the archive:</h4>
<div class="shift">
<div class="code">// OpenTBS >= 1.6.0<br />
$TBS->Plugin(OPENTBS_RESET);<br />
<br />
// Deprecated since OpenTBS 1.6.0<br />
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);</div>
<p>The automatic extension recognition is also applied as it was applied for the first load of the archive.</p>
</div>
<h3><a name="misc" id="misc"></a>4.8. Miscellaneous</h3>
<h4>• Dealing with apostrophes:</h4>
<div class="shift">
<p> Both OpenOffice and Ms Office may automatically convert single quotes (') into typographic apostrophes (’), depending to the auto-correction options. This may be annoying when you need to code a TBS fields that have a single quote. That's why OpenTBS automatically convert by default all (’) back to single quotes (') in documents.<br />
If you want to stop this conversion, you can set <span class="smallcode">$TBS->OtbsConvertApostrophes = false;</span> and no apostrophes will be converted. Note that you can avoid the auto-correction of single quotes (') in Ms Word using keys[ctrl]+[z], and in OpenOffice using the cancel button.<br />
</p> <div class="versioning">Property OtbsConvertApostrophes is supported since OpenTBS version 1.6.0.</div>
</div>
<h4><a name="force_doctype" id="demo4"></a>• Forcing the document type recognition:</h4>
<div class="shift">
<p>You can force the document type recognition using command OPENTBS_FORCE_DOCTYPE. Example:</p>
<div class="code"> $TBS->PlugIn(OPENTBS_FORCE_DOCTYPE, 'docx');</div>
<p class="versioning">This command is supported since OpenTBS version 1.6.0.</p> </div>
<h4>• Retrieving the name of the current document:</h4>
<div class="shift">
<p> Property <span class="smallcode">$TBS->tbsCurrFile</span> indicates the name of the current file loaded from the archive. The value is false if no file is loaded yet from the archive.</p>
<p> Other TinyButStrong methods and properties stay unchanged and are available for merging your template. </p>
<div class="versioning">(supported since OpenTBS version 1.1)</div>
</div>
<h2><a name="demo" id="demo"></a>5. Demo</h2>
<p>The OpenTBS package includes a full set of runnable templates. Some templates can contain useful complementary information for designing.<br />
Run the following demo under PHP: <a href="http://www.tinybutstrong.com/plugins/opentbs/demo">OpenTBS demo</a></p>
<h2><a name="debug" id="debug"></a>6. Debugging your template</h2>
<p><a name="debugmode" id="debugmode2"></a>Since OpenTBS version 1.6.0, there are several commands for debugging. Please note that those commands do not exit the process.</p>
<table border="0" cellspacing="1" cellpadding="0">
<tr>
<th align="left">Command</th>
<th align="left">Desciption</th>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_INFO [, $Exit])</td>
<td>Display technical information about the current loaded template, including sheet information if the template is a workbook, and chart information if the template have some.<br />
<span class="smallcode">$Exit</span> must be a boolean, default value is <span class="smallcode">true</span>.</td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_XML_CURRENT)</td>
<td>Display XML contents of sub-files already opened and modified for merging. XML is indented in order to improve reading.</td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_XML_SHOW)</td>
<td>Ends the merge process as if the final document was created. But instead of creating the document, displays
the XML contents of sub-files modified for merging. XML is indented in order to improve reading.</td>
</tr>
</table>
<p>There is also deprecated debug options:</p>
<table border="0" cellspacing="1" cellpadding="0">
<tr>
<th align="left">Command</th>
<th align="left">Desciption</th>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_XML)</td>
<td>Does the same as <span class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_XML_SHOW);</span><br />
<span class="versioning">Supported since OpenTBS version 1.3.2.</span></td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_XML+OPENTBS_DEBUG_AVOIDAUTOFIELDS)</td>
<td>Avoid merging of [onload], [onshow] and [var].<span class="versioning">Supported since OpenTBS version 1.3.2.</span></td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->Render = OPENTBS_DEBUG_AVOIDAUTOFIELDS;</td>
<td> Work also in property Render.<span class="versioning">Supported since OpenTBS version 1.3.2.</span><br /></td>
</tr>
<tr>
<td valign="top" nowrap="nowrap" class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_CHART_LIST)</td>
<td>Does the same as <span class="smallcode">$TBS->PlugIn(OPENTBS_DEBUG_INFO);</span><span class="versioning">Supported since OpenTBS version 1.6.0.</span></td>
</tr>
</table>
<p>Otherwise, here are some indications that may help for the issues you can met with merging:</p>
<h3>a) The merged document is producing error messages when opened with its application (OpenOffice or Ms Office)</h3>
<p>The most likely causes are:</p>
<p>• You've chosen the <span class="smallcode">OPENTBS_DOWNLOAD</span> render option but a php error message or any other unexpected content has been output before by PHP.</p>
<p class="shift">Activate the <a href="#debugmode">debug mode</a> using the command <span class="smallcode">OPENTBS_DEBUG_XML_SHOW</span>, it helps to check PHP error message and other unexpected content.</p>
<p>• The merging has produced an invalid document or an invalid XML content in an XML file of the document.</p>
<p class="shift">Activate the <a href="#debugmode">debug mode</a> using it helps to check the XML contents of merged files.</p>
<p> See section (b) below for more information in the XML structure of the files.</p>
<h3>b) The merged document is well opened by its application (OpenOffice or Ms Office) but the content is not designed as expected</h3>
<p>First, you can have a look the <a href="#demo">demo templates</a>, they contain examples and advices for each type of document.<br />
And to go further: even if you can edit your template using directly OpenOffice or Ms Office, you will probably need to understand the XML tags and attributes to complete your merge. The file <a href="xml_synopsis.txt">xml_synopsis.txt</a> is a small synopsis of the XML structure you can found in the inner source of those documents. Have a look to it if you feel lost.</p>
<h3>c) Go deeper in the debugging</h3>
<p>You can view the inner source of a document using a zip software like <a href="http://www.7-zip.org/">7-Zip</a>. It allows you to open an archive even if the extension is not ".zip".<br />
</p>
<ul>
<li>Open the merged document with 7-Zip (or your other zip software),</li>
<li> extract the main XML file (or another file that you've merged),</li>
<li> then open the XML file in an Text Editor software.</li>
<li>those XML files are usually saved with no line breaks, which make them hard to be read. Some Text Editors can reformat them. You can also use the <a href="#debugmode">debug mode</a> to see the formatted XML.</li>
<li>check the structure of the XMK, try some fix and arrangements, deleted suspicious parts, ...</li>
<li>put the modified XML file back to the archive, and test if it's correctly opened with its application (OpenOffice, Ms Office)</li>
</ul>
<h2><a name="zlib" id="zlib"></a>7. What to do if Zlib extension is not enabled with PHP?</h2>
<p>OpenTBS uses Zlib functions in order to automatically uncompress and recompress files stored in the zip archive. If Zlib is not enabled, then you have to use your own uncompress/compress tool, or to prepare the template to have files uncompressed in the zip archive.</p>
<p><u>Example to uncompress the "content.xml" file in an ODT document using 7-Zip:</u><br />
1) open the ODT file with 7-Zip<br />
2) extract the "content.xml" file from the ODT file in the same folder than the ODT file<br />
3)
close 7-Zip<br />
4)
open 7-Zip, and change current directory to be the same as the ODT file<br />
5) select the
"content.xml" file and click on button [Add], or menu [File][7-Zip][Add to archive...]<br />
6) A new window named "Add to archive" is opened,<br />
- replace the archive name with the ODT file name,<br />
- set the Compression level to "None".<br />
7) Click on [Ok]<br />
If you re-open the ODT file with 7-Zip, you can notice that the size and the uncompressed size are the same.<br />
If the file should be placed in a sub-folder of the archive, then open the archive and rename the file in order to move it in a folder. For example rename "manifest.xml" to "META-INF\manifest.xml" will move it into META-INF. But moving the file will no delete the one which has the same name in the target folder. You have to go and delete the old one. </p>
<h2><a name="changelog" id="demo3"></a>8. Changelog</h2>
<p>version 1.7.6, on 2012-06-06<br />
- Restore lost spaces around merged TBS fields in Ms Word documents. The patch doesn't work for headers and footers, unfortunately.</p>
<p> version 1.7.5, on 2012-02-14<br />
- Avoid erroneous Ms Word merged documents when duplicating objects such as drawings and shapes.<br />
- Based on TbZip version 2.11<br />
- New coding shorctut $TBS->TbsZip.<br />
- More examples of formulas for Xlsx and Ods speadsheets.
</p>
<p>version 1.7.4, on 2011-10-20<br />
- parameter "defaut=current" does not work and may build invalid documents when the target image is missing.<br />
- new command OPENTBS_REPLACEFILE<br />
- new command OPENTBS_FILEEXISTS</p>
<p>version 1.7.3, on 2011-10-13<br />
- fixed bug: in Ms Word documents, automatic fields (onload, onshow) placed in headers and footers with parameter "ope=changepic" are producing an erroneous merge. In Word 2010 the picture may by missing, in Word 2007 the docx file may be considered as corrupted.</p>
version 1.7.2, on 2011-10-12<br />
- fixed bug: error when using command OPENTBS_SELECT_SHEET with a sheet name: <span class="warning">Notice: Undefined index: xxx in xxx on line 1986</span>.
<p>version 1.7.1, on 2011-10-07<br />
- fixed bug: first non-empty cell of an Excel Spreadsheet is never merged if it contains a TBS field.<br />
- minor internal improvements.</p>
<p>version 1.7.0, on 2011-08-21<br />
- new parameter 'adjust' for changing picture size<br />
- new command OPENTBS_DEBUG_INFO <br />
- new command OPENTBS_SELECT_MAIN <br />
- new command OPENTBS_SELECT_SHEET<br />
- new command OPENTBS_DISPLAY_SHEETS<br />
- new command OPENTBS_DELETE_SHEETS<br />
- new command OPENTBS_DELETE_COMMENTS <br />
- new command OPENTBS_DELETE_ELEMENTS<br />
- parameter 'changepic' is optimized</p>
<p>version 1.6.2, on 2011-07-12<br />
- fixed bug: Ms Excel cells could consider as error some formatted values such as '0.00000000000000'.</p>
<p>version 1.6.1, on 2011-06-08<br />
- fixed bug: some documents may be corrupted when created using OPENTBS_DOWNLOAD because of a PHP error <span class="warning">"supplied argument is not a valid stream resource"</span> or <span class="warning">"Undefined property: clsOpenTBS::$OutputHandle"</span>.<br />
- fixed bug: using keyword "xlsxNum", "xlsxDate" or "xlsxBool" inside a cell that is not merged can make a corrupted XLSX spreadsheet.<br />
- improvement: updated templates in the demo.<br />
- based on a TbsZip v2.8</p>
<p>version 1.6.0, on 2011-06-07<br />
- new feature: merge charts in Ms Word documents.<br />
- new feature: merge rows and columns Ms Excel workbooks.<br />
- new feature: new "ope" parameters for forcing cells type in Ms Excel (Numeric, Date and Boolean).<br />
- new feature: debug mode enhanced.<br />
- new feature: force the type of document using command OPENTBS_FORCE_DOCTYPE.<br />
- new property: deal with apostrophes using property OtbsConvertApostrophes.<br />
- improvement: if the document extension is not recognized, then try to recognize document type by sub-file presence.<br />
- improvement: can use the Direct Command feature of TBS 3.7.0.<br />
- based on a TbsZip v2.6</p>
<p>version 1.5.0, on 2011-03-20<br />
- new feature: headers and footers are automatically loaded for OpenOffice & MsOffice.<br />
- new feature: automatically cleans up spelling and change trackings information in MsWord templates (such information may
deconstruct the TBS tags). This feature can be disabled.<br />
- new constant OPENTBS_DEBUG_AVOIDAUTOFIELDS <br />
- <span id="result_box4" lang="en" xml:lang="en"><span title="Cliquer ici pour voir d'autres traductions">improvement</span></span>: Debug doesn't stopped if an OpenTBS alert occurs. <br />
- <span id="result_box3" lang="en" xml:lang="en"><span title="Cliquer ici pour voir d'autres traductions">improvement</span></span>: OpenTBS alerts say if the process will be stopped. <br />
- fixed bug: in debug mode: "warning function.str-repeat: Second argument has to be greater than or equal to 0"<br />
- fixed bug: when using OPENTBS_RESET: "Warning: Missing argument 2 for clsOpenTBS::OnCommand() in ... on line 225"<br />
- fixed bug: DML images were not found when using parameter "ope=changepic" in a DOCX document<br />
- fixed bug: the script ends and display the XML contents when a when using parameter "ope=changepic" with a new image type in a DOCX document</p>
<p>version 1.4.1, on 2010-10-28<br />
- major bug fixed: due to TbsZip, some added or modified files can be saved the document with a wrong CRC control code. This could make softwares to consider the document as corrupted, but were often easily fixed by OpenOffice and Ms Office. Only few CRC codes are wrongly saved, thus the bug is rare and can seem to appear randomly on few documents.</p>
<p> version 1.4.0, on 2010-10-05<br />
- new parameters "<span class="smallcode">changepic</span>" and "<span class="smallcode">default</span>"</p>
<p> version 1.3.3, on 2010-08-05<br />
- property Version of OpenTBS version 1.3.2 was saying 1.3.1</p>
<p> version 1.3.2, on 2010-07-23<br />
- possibility to change de default data conversion using the new constants <span class="smallcode">OPENTBS_DEFAULT</span>, <span class="smallcode">OPENTBS_ALREADY_XML</span> or <span class="smallcode">OPENTBS_ALREADY_UTF8</span><br />
- enhanced debug mode: listing of added, deleted and modified files ; and show XML formated contents of files merged with OpenTBS.</p>
<p> version 1.3.1, on 2010-07-01<br />
- based on TbsZip version 2.1: fixes a bug that saved a bad time of modification file was added, and saved time modification when a file content is replaced.<br />
- the addpic operator now automatically updates the <span class="smallcode">"fanifest.xml"</span> file on OpenOffice document. Without this fix, an ODP merged document could be open with an error message with OpenOffice >= 3.2 </p>
<p> version 1.3, on 2010-06-01<br />
- a new plugin command that add a new file in the archive<br />
- a new plugin command that delete a new file in the archive<br />
- a parameter '<span class="smallcode">ope=addpic</span>' that add a new picture in the archive directly from the template<br />
- based on a TbsZip v2 (modify/delete/add files in a zip archive, )</p>
<p>version 1.1, on 2009-11-19<br />
- New render option : <span class="smallcode">OPENTBS_STRING</span><br />
- New feature: can reset changes in the current archive using <span class="smallcode">$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);</span><br />
- New behavior: extension of the archive is ignored by <span class="smallcode">LoadTemplate()</span> if the name is ended with '<span class="smallcode">#</span>'<br />
- Bug fixed: in case of several files to take from the archive in one shot, then only the last one had [onload] fields merged.</p>
<h2><a name="license" id="demo2"></a>9. License</h2>
<p>OpenTBS is under <a href="http://www.gnu.org/licenses/lgpl.html">LGPL</a> (Lesser General Public License)</p>
<p> </p>
</body>
</html>