/
tbs_plugin_opentbs.html
2117 lines (2085 loc) · 112 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
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>OpenTBS documentation - create OpenOffice and Ms Office documents
with PHP</title>
<script>
// redirection if open without the menu at the TBS site
if ( (document.location.href.indexOf('www.tinybutstrong.com') > 0)
&& (document.location.href.indexOf('tbs_plugin_opentbs.html') > 0)
) {
document.location.href = "/opentbs.php?doc";
}
</script> <style>
<!--
body, td, th {
font-family: Arial, sans-serif;
font-size: 13px;
}
/* makes first paragraph alignet to top in tables */
td > p:first-child ,
td > ul:first-child {
margin-top: 0px;
}
td th {
vertical-align: top;
}
#main-body h4 {
font-size: 13px;
font-weight:normal;
margin-bottom: 5px;
}
#main-body h5 {
font-size: 13px;
font-weight:normal;
text-decoration:underline;
margin-bottom: 5px;
}
#main-body ul {
list-style-type: square;
padding-left: 10px;
line-height: 20px;
}
#main-body ul li ul {
list-style-type: circle;
padding-left: 14px;
line-height: 20px;
}
.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;
margin-top: 3px;
margin-bottom: 3px;
padding-top: 3px;
padding-bottom: 3px;
}
.versioning {
font-style: italic;
color: #060;
}
.category {
color: #C33;
font-weight: bold;
font-size: 13px;
}
.smallcode {
font-family: "Courier New", Courier, monospace;
font-size: 13px;
color: #036;
}
.small-list {
list-style: circle;
}
.nowrap {
white-space: nowrap;
}
.centered {
text-align:center;
}
.top {
vertical-align: top;
}
.warning {
color: #F30;
}
.yes {
color: #060;
}
.no {
color: #C30;
}
-->
</style> <meta name="Keywords" content="openxml, odf, template">
</head>
<body>
<!-- div main-body is used for insertion in the TBS menu -->
<div id="main-body">
<h1>OpenTBS - create OpenOffice and Ms Office documents with PHP</h1>
<div>version 1.12.1, 2024-03-06 by Skrol29</div>
<div>help file modified on 2024-03-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="#blockalias">Block Alias</a></li>
<li>4.5. <a href="#chart">Charts - Change or read data of series in
a chart</a></li>
<li>4.6. <a href="#pic">Pictures - Change pictures in the document</a></li>
<li>4.7. <a href="#col">Tables - Delete or merge columns in tables</a></li>
<li>4.8. <a href="#mergecell">Tables - Merge cells vertically</a></li>
<li>4.9. <a href="#cells">Workbook - Merging data in spreadsheet
cells</a></li>
<li>4.10. <a href="#ranges">Workbook - Read and writre ranges in a
workbook</a></li>
<li>4.11. <a href="#docfield">Merge document fields</a></li>
<li>4.12. <a href="#other_commands">Other merging commands</a>
<ul>
<li><a href="#commands_for_all">For all types of documents</a></li>
<li><a href="#commands_for_documents">For documents (ODT and
DOCX)</a></li>
<li><a href="#commands_for_workbooks"> For workbooks (ODS and
XLSX)</a></li>
<li> <a href="#commands_for_presentations">For presentations
(ODP and PPTX)</a><br>
</li>
</ul>
</li>
<li>4.13. <a href="#modify_files">Manage files in the archive</a></li>
<li>4.14. <a href="#special_options">Special options</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="#license">License</a></li>
</ol>
<h2><a id="intro"></a>1. Introduction</h2>
<p>OpenTBS is a plug-in for the <a href="http://www.tinybutstrong.com">TinyButStrong</a>
Template Engine. </p>
<p> 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.</p>
<p> 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>
<p>Since version 1.10.0, OpenTBS can also read data in workbooks (<strong>xlsx</strong>
and <strong>ods</strong> files).</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 PHP 8, PHP 7 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 id="install"></a>2. Installing</h2>
<h5>Requirements:</h5>
<ul>
<li>TinyButStrong version 3.12.0 or higher.</li>
<li>PHP 8, PHP 7 or 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 id="principles"></a>3. Understanding principles</h2>
<p>It is important to figure out that documents made with LibreOffice,
OpenOffice and Ms Office (since version 2007) 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.html">XML Synopsis</a>
summarizes the key entities of XML sub-files contained in LibreOffice,
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 quite invisible for you.</span></span></p>
<p> When the OpenTBS plugin is installed, the LoadTemplate() method
becomes able to first load a zip archive (a LibreOffice, OpenOffice or
Ms Office document), and then to load the contents of any XML or Text
files stored in the archive. Then you can load an merge the contents of
XML or Text files with all features of the TinyButStrong template
engine. TBS can merge fields and blocks only for the current loaded
sub-file, but OpenTBS make you very easy to <a href="#modify_files">manage
sub-files</a> and gives lot of facilities for special contents such as
pictures, charts, ... . 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, or a new file on the server's disk, or as a
PHP string containg the binary of the result archive.</p>
<p>Since OpenTBS version 1.3, you can also add and delete files in the
archive.</p>
<p><a 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.</p>
<p> 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 id="coding"></a>4. Synopsis and code examples</h2>
<h3><a id="preparation"></a>4.1. Preparation of TinyButStrong Template
Engine with the OpenTBS plug-in</h3>
<pre class="shift code">include_once('tbs_class.php');
include_once('tbs_plugin_opentbs.php');
$TBS = new clsTinyButStrong;
$TBS->Plugin(TBS_INSTALL, OPENTBS_PLUGIN);</pre>
Or, with an autoloader :
<pre class="shift code">$TBS = new clsTinyButStrong;
$TBS->Plugin(TBS_INSTALL, 'clsOpenTBS');</pre>
<h3><a 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>
<div class="shift">
<div class="code">$TBS->LoadTemplate('document.odt',
OPENTBS_ALREADY_UTF8); // Load the archive and tells that the PHP
script and merged data are already UTF8. </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 with a PHP file handle:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS
version 1.8.1)</span>
<pre class="code">$handle = tmpfile();
fwrite($handle, $binary_contents);
$TBS->LoadTemplate($handle);</pre>
</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>• Unload the current template, so the template file is no longer
locked:</h4>
<div class="shift"><span class="versioning">(supported since OpenTBS
version 1.9.5)</span>
<div class="code">$TBS->LoadTemplate(false);</div>
</div>
<h4>• Load a stored file from the current archive:</h4>
<div class="shift">
<p>See command <a href="#opentbs_select_file">OPENTBS_SELECT_FILE</a>.</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 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_DOWNLOAD + 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 id="blockalias"></a>4.4. Block alias</h3>
<p><span class="versioning">Block Alias are supported since OpenTBS
version 1.8.0, they can work only with TBS 3.8.0 or higher</span>.</p>
<p>The Block Alias are wrappers for defining TBS blocks on usual Libre
Office and Ms Office entities. This helps to not referring directly to
XML entities and to harmonize block definitions between types of
documents. For example: you can use <span class="smallcode">block=tbs:row</span>
instead of <span class="smallcode">block=table:table-row</span>.</p>
<p> Some Block Alias, such as <span class="smallcode">tbs:page</span> and
<span class="smallcode">tbs:section</span>, are also defining an entity
that you cannot have with normal XML entities.</p>
<h5>Block alias available according to the type of document :</h5>
<table cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<th rowspan="2" class="tbl-list" align="left">Alias</th>
<th rowspan="2" align="left">Desciption</th>
<th colspan="3" align="center">LibreOffice</th>
<th colspan="3" align="center">Ms Office</th>
</tr>
<tr>
<th class="centered">Writer<br>
(odt)</th>
<th class="centered">Calc<br>
(ods)</th>
<th class="centered">Impress<br>
(odp)</th>
<th class="centered">Word<br>
(docx)</th>
<th class="centered">Excel<br>
(xlsx)</th>
<th class="centered">PowerPoint<br>
(pptx)</th>
</tr>
<tr>
<td class="nowrap top smallcode">tbs:p</td>
<td>A paragraph.</td>
<td class="yes centered">yes</td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="nowrap top smallcode">tbs:title</td>
<td>A title.</td>
<td class="centered yes">yes</td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:section</td>
<td>A section of text.</td>
<td class="centered yes">yes</td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes (*)</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:table</td>
<td>A table inserted in the document.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><em>a sheet</em></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:row</td>
<td>A row of a table.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:cell</td>
<td>A cell of a table.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:comment</td>
<td>A comment.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:page</td>
<td>A page defined by an explicit page break before a paragraph.(*)</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes (*)</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:slide</td>
<td>A slide.</td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:sheet</td>
<td>A worksheet.</td>
<td class="centered"><em>a table</em></td>
<td class="centered yes">yes</td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="no">no</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:draw</td>
<td>A single draw, or set of draws (Ms Word)</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:drawgroup</td>
<td>A group of draws.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:drawitem</td>
<td>A single draw item among a set of items.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
<tr>
<td class="top smallcode nowrap">tbs:listitem</td>
<td>An item of a bullet list.</td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="yes">yes</span></td>
<td class="centered"><span class="no">no</span></td>
<td class="centered"><span class="yes">yes</span></td>
</tr>
</tbody>
</table>
<h5>Notes (*)</h5>
<ul>
<li><span class="code">tbs:page</span> in a DOCX: works with the two
ways for defining a page break: (1) insert a section break doing a
page break, or (2) use the paragraph property named <em>page break
before</em>.</li>
<li><span class="code">tbs:page</span> in a DOCX: the TBS tag using the
alias <span class="smallcode">tbs:page</span> must not be placed in
the last paragraph of the page if it uses a section break doing a page
break. This is a knowed bug. Instead, use the paragraph property named
<em>page break before</em>, or move the TBS tag in another paragraph.</li>
<li><span class="smallcode">tbs:section</span> in a DOCX: this alias
points out avery kind of sections, including thoses defined with a
section break doing a page break</li>
</ul>
<h3><a id="chart"></a>4.5. Change or read data of series in a chart</h3>
<h4>• <a id="opentbs_chart"></a>Change series in a chart:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS
version 1.6.0, for Ms Word and Ms Powerpoint, since version 1.8.0 for
LibreOffice)</span>
<div class="code">Example: $TBS->PlugIn(OPENTBS_CHART, $ChartRef,
$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. It can also delete or rename the series in
the chart.</p>
<p> The result is <span class="smallcode">true</span> if the series is
modified with success, otherwise the result is <span class="smallcode">false</span>.
</p>
<table width="100%" cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<th class="top" align="left">Argument</th>
<th align="left">Description</th>
</tr>
<tr>
<td class="top smallcode">
<p>$ChartRef</p>
</td>
<td class="top">
<p>The reference to find the chart. This value can be either:</p>
<ul>
<li>The name of a field placed anywhere in the Alternative
Text property of the frame that embeds the chart. <span class="versioning">(supported
since OpenTBS 1.10.4)</span>. <br>
This name must be unique for charts in the entire document.
<br>
For example: <code>$ChartRef = 'my_chart'</code> is
corresponding to the field <code>[my_chart]</code> placed
in the Alt Text property. <br>
The property Alt Text of the frame that embeds the chart is
available in both Ms Office and LibreOffice. <br>
In Ms Office you can retrieve this property from the
contextual menu of the frame, and choose <em>Alt. Text...<em>.
<br>
In LibreOffice you can retrieve this property from the
contextual menu of the frame, and choose <em>Description...<em>,
or sometimes <em>Properties...<em> in Writer. </em></em></em></em></em></em></li>
<em><em><em>
<li>The order number of the chart in the document (first
is number 1).</li>
<li>Deprecated: <code>$ChartRef</code> can aslo be
exactly the property title of frame that embeds the
chart <span class="versioning">(supported since
OpenTBS 1.8.0)</span>. <br>
Note: In Ms Office, this property is no more available
since Ms Office 2019. <br>
Note: In LibreOffice this property can sometimes be
captioned "Alternative - text only" in Writer. </li>
</em></em></em>
</ul>
<em><em><em>
<p> You can use the command <a href="#debugmode">OPENTBS_DEBUG_INFO</a>
in order to view all charts in the document that OpenTBS
can manage.<br>
You can use the command <a href="#opentbs_chart_info">OPENTBS_CHART_INFO</a>
in order to read data in the chart. </p>
<p>Deprecated since version 1.8.0: in previous version, <span
class="smallcode">$ChartRef</span> could be the
internal name of the XML file that contains the chart
definition, with or without the extension. Such as <span
class="smallcode">'chart1'</span>.</p>
</em></em></em></td>
</tr>
<tr>
<td class="top smallcode">
<p>$SeriesNumOrName</p>
</td>
<td class="top">
<p>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>. </p>
</td>
</tr>
<tr>
<td class="top smallcode">
<p>$NewValues</p>
</td>
<td class="top">
<p>The new data of the series. Must be an array, or value <span
class="smallcode">false</span> if you want to delete the
series.</p>
<p> The array can store data with 3 possibilities:</p>
<p> Structure #1: <span class="code">$NewValues = array(
array('cat1', 'cat2', 'cat3', ...), array(val1, val2, val3,
...) );</span></p>
<p> Structure #2: <span class="code">$NewValues =
array('cat1'=>val1, 'cat2'=>val2, 'cat3'=>val3,
...);</span></p>
<p> Structure #3: <span class="code">$NewValues = array(
array(x1, y1), array(x2,y2), array(x3, y3), ...);</span> </p>
<p>Notes :</p>
<ul>
<li>A chart may have some values missing for one series and
not for others. You can define a missing value for a
category using PHP values <span class="smallcode">null</span>,
<span class="smallcode">'NULL'</span>, <span class="smallcode">false</span>
or <span class="smallcode">''</span> (empty string).</li>
<li>Structure #3 is supported only for LibreOffice, and is
required when the chart type is <strong>XY (Scatter)</strong>,
<strong>Bubble</strong> or<strong> Stock</strong>. Use 2
values in each items for XY, 3 for Bubble, and 4 for Stock.</li>
<li>Structure #1 is required for Ms Office when the chart type
is <strong>XY (Scatter)</strong>. Bubble and Stock are not
yet supported for Ms Office.</li>
</ul>
</td>
</tr>
<tr>
<td class="top smallcode">
<p>$NewLegend</p>
</td>
<td class="top">
<p>Optional. The new caption of the series. </p>
</td>
</tr>
</tbody>
</table>
<h5>Please note:</h5>
<ul>
<li>The type of the chart cannot 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_INFO</a> in order to view all
unsupported charts in the document.</li>
<li>With Ms Office, the chart must not be linked to external data
(such as an Excel worksheet). Otherwise the chart will be
automatically actualized back the previous values when it will be
opened. </li>
</ul>
<p class="versioning">Charts in worksheets (DOCX and ODS files) are
supported since OpenTBS version 1.9.12.</p>
<p class="versioning">Before version OpenTBS 1.9.12, the visual Data
Editor in Ms Office softwares (Excel, Word, Powerpoint) becomes
unavailable on a merged chart.</p>
</div>
<h4> <a id="opentbs_chart_info2"></a>Delete a category in a chart:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS
version 1.9.11)</span>
<div class="code">Example: $ok =
$TBS->PlugIn(OPENTBS_CHART_DELETE_CATEGORY, $ChartRef, $Categories,
$NoErr = false)</div>
<p>This command delete one or several categories in the chart. It
returns <span class="smallcode">true</span> if succeed.</p>
<p>Argument <span class="smallcode">$Categories</span> can be either
the name of a single category, an array of names, or the keyword <span
class="smallcode">'*'</span> wich mean all categories.</p>
<p>By default an error occurs if one of the searched categories is not
found in the chart. But if your set argument <span class="smallcode">$NoErr</span>
to <span class="smallcode">true</span> then the function returns <span
class="smallcode">false</span> and no error occurs.</p>
<p><span class="versioning">Array of names and the keyword '*' are
supported since OpenTBS version 1.9.12.</span></p>
</div>
<h4>• <a id="opentbs_chart_info"></a>Read series in a chart:</h4>
<div class="shift"> <span class="versioning">(supported since OpenTBS
version 1.9.5)</span>
<div class="code">Example: $info = $TBS->PlugIn(OPENTBS_CHART_INFO,
$ChartRef, $Complete=false)</div>
<p>This command returns information about all series in the chart.</p>
<p> The result is an associative array whose structure depends on
argument <span class="smallcode">$Complete</span>. </p>
<table width="100%" cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<th class="top" align="left">Argument</th>
<th align="left">Description</th>
</tr>
<tr>
<td class="top smallcode">
<p>$ChartRef</p>
</td>
<td class="top">
<p>The reference to find the chart. Same as <a href="#opentbs_chart">OPENTBS_CHART</a>.</p>
</td>
</tr>
<tr>
<td class="top smallcode">
<p>$Complete</p>
</td>
<td class="top">
<p>If<span class="smallcode"> $Complete</span> = <span class="smallcode">false</span>,
the command returns a simple list of all series and theirs
corresponding data with structue #1 described in <span class="smallcode"><a
href="#chart">OPENTBS_CHART</a></span>.</p>
<pre class="code">// Example :
array (
'Series 1' => array(
0 => array (0 => 'Category A', 1 => 'Category B', 2 => 'Category C'),
1 => array (0 => '2', 1 => '2.1', 2 => false,),
),
'Series 2' => array(
0 => array (0 => 'Category A', 1 => 'Category B', 2 => 'Category C',),
1 => array (0 => '7', 1 => '7.1', 2 => '6.9',),
),
...
); </pre>
<p>If<span class="smallcode"> $Complete</span> = <span class="smallcode">true</span>,
the command return an array with information about subfiles,
and also all the series (name, categories, values) in a
different structure.</p>
<pre class="code">// Example :
array (
'file_idx' => 17,
'file_name' => 'Object 1/content.xml',
'parent_idx' => 19,
'parent_name' => 'content.xml',
'series' => array (
0 => array (
'name' => 'Series 1',
'cat' => array (0 => 'Category A', 1 => 'Category B', 2 => 'Category C',),
'val' => array (0 => '2', 1 => '2.1', 2 => false,),
),
1 => array (
'name' => 'Series 2',
'cat' => array (0 => 'Category A', 1 => 'Category B', 2 => 'Category C',),
'val' => array (0 => '7', 1 => '7.1', 2 =>'6.9',),
),
...
); </pre>
</td>
</tr>
</tbody>
</table>
</div>
<h3><a id="pic"></a>4.6. 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]</div>
<p>In the example above, $x is a PHP global variable containing the name
of an external picture file (relative or absolute path). Of course you
can use this feature on TBS fields merged with <a href="http://www.tinybutstrong.com/manual.php#php_mergeblock">MergeBlock()</a>.</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 (see parameter <span class="smallcode">tagpos</span>
below for another position), 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.</p>
<p>Instead of change a picture with a TBS tag, you can also do it
manually at the PHP side using the command <a href="#other_commands">OPENTBS_CHANGE_PICTURE</a>.</p>
<p>Known limitations:</p>
<ul>
<li>SVG pictures are not supported for Ms Office templates. Nor as an
image to replace in the template, nor as an image to insert.</li>
<li>Note that since OpenTBS version 1.8.0, you can change picture in
Ms Excel worksheet. You must put the TBS field inside the picture
description and use parameter "tagpos=inside". Before this version
it was not possible to change pictures in an Ms Excel worksheet.</li>
</ul>
<p>Options:</p>
<p>In order to simplify your coding, they are other complementary
optional parameters: </p>
<table style="margin-left:20px;" cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<th align="left">Parameter</th>
<th align="left">Description</th>
</tr>
<tr>
<td class="top"><span class="smallcode">tagpos</span></td>
<td>
<p>Supported values are "<span class="smallcode">after</span>",
"<span class="smallcode">before</span>" and "<span class="smallcode">inside</span>".
This option indicates the position of the TBS tag relativelly
to the target picture.</p>
<p> The default value is "<span class="smallcode">after</span>",
it means that the TBS tag (the one with "<span class="smallcode">ope=changepic</span>")
must be placed after the picture.</p>
<p> You can use "<span class="smallcode">tagpos=inside</span>"
when you put the TBS field in the Description or Title of the
image (LibreOffice/OpenOffice or Ms Office). </p>
<ul>
<li>This option won't work if you put the TBS tag inside the
property Name of an image in LibreOffice/OpenOffice.</li>
<li> In Ms Word 2007, property Description and Title are
supported but not available for editing, but you can use
"Alternative text" (in the "Web" tab of the Size dialog box)
, ot the URL, or the Toolipt of a Link on the image.</li>
<li> In Ms Excel, you must use "tagpos=inside" because
pictures are not saved in the sheet, they are not positioned
relativelly to cells.</li>
</ul>
<p> <span class="versioning">Parameter tagpos is supported
since OpenTBS version 1.8.0. Previsouly the TBS tag had to
be placed after the picture.</span></p>
</td>
</tr>
<tr>
<td class="top"><span class="smallcode">adjust</span></td>
<td>
<p>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.</p>
<p> Values can be on of the followings: </p>
<table cellspacing="0" cellpadding="3" border="0">
<tbody>
<tr>
<td class="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 class="top"><span class="smallcode">adjust=samewidth</span></td>
<td>The picture is adjusted to have the same width than
the picture of the template.</td>
</tr>
<tr>
<td class="top smallcode">adjust=sameheigth</td>
<td>The picture is adjusted to have the same height than
the picture of the template.</td>
</tr>
<tr>
<td class="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>
</tbody>
</table>
<p class="versioning">Parameter adjust is supported since
OpenTBS version 1.7.0.</p>
</td>
</tr>
<tr>
<td class="top"><span class="smallcode">unique</span></td>
<td>
<p>Indicate to OpenTBS that the original picture is unique in
the template and can be deleted. This actually saves size of
the final document.<br>
The value of argument <span class="smallcode">unique</span>
can be omitted. If the value is 1 or ommited, then the
original picture is deleted from the template.</p>
<p>If the original picture is in fact displayed somewhere else
in the template, that may produce a missing picture.</p>
<p> <span class="versioning">Parameter unique is supported
since OpenTBS version 1.9.1.</span></p>
</td>
</tr>
<tr>
<td class="top"><span class="smallcode">from</span></td>
<td>
<p>This option reformulates the path of the new 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"
class="smallcode">file</a>". </p>
<div class="template">Example:
[onshow.x;ope=changepic;from='../pic/[val].gif']</div>
</td>
</tr>
<tr>
<td class="top"><span class="smallcode">as</span></td>
<td>
<p>This option reformulates the 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"
class="smallcode">file</a>". </p>
<div class="template">Example:
[onshow.x;ope=changepic;as='[val].gif']</div>
</td>
</tr>
<tr>
<td class="top"><span class="smallcode">default</span></td>
<td>
<p>This option defines 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>.<br>
If the value is <span class="smallcode">"current"</span> then
OpenTBS will let the current picture of the template if the
new picture is not found.</p>
<p> <span class="versioning">Since OpenTBS version 1.8.0 the
default value is "current". In prior versions, there was no
default value and an OpenTBS error message was prompted if
the new image was not found. </span></p>
</td>
</tr>
</tbody>
</table>
</div>
<h3><a id="col"></a>4.7. Delete or merge columns in a table</h3>
<h5><a id="delcol"></a>4.7.1 Delete columns in a table</h5>
<p>Parameter "<span class="smallcode">ope=delcol</span>" enables you to
delete specified columns in a table in an Ms Word document (docx) or any
LibreOffice document.</p>
<p> Limitations of parameter "<span class="smallcode">ope=delcol</span>" :</p>
<ul>
<li>It will produce a wrong result if there is any cell with a merged
style before of within the columns to delete using OpenTBS.</li>
<li>If used with other <span class="smallcode">"ope"</span> options,
then it must be the last one. This is because it avoid the usual
merging process. Example : <span class="smallcode">ope=docfield,delcol</span>.</li>
</ul>
<p> You have to put a TBS field anywhere inside the table with the
following parameters:</p>
<table cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<td class="top"><span class="template">ope=delcol</span></td>
<td>activate the deletion feature</td>
</tr>
<tr>
<td class="top"><span class="template">colnum=...</span></td>
<td>
<p>(ignored if <span class="template">colset</span> is defined)
define the column numbers to delete. By default, this parameter
is the merged value.<br>
It can be :</p>
<ul class="small-list">
<li> a number (first column is number 1)</li>
<li> a range (tow columns numbers separated with '-')</li>
<li>a list of numbers or ranges separated with coma (,)</li>
</ul>
<p>Both parameters "<span class="template">colnum</span>" and "<span
class="template">colshift</span>" can contain [val] and [var]
fields. Unfortunaltely parameter <span class="template">"ope"</span>
is processed before parametre <span class="template">"if"</span>,
so the merged value must be directly the colums to delete.</p>
</td>
</tr>
<tr>
<td class="top"><span class="template">colshift=...</span></td>
<td>(optional, ignored if <span class="template">colset</span> is
defined) if parameter <span class="template">colnum</span> has
only one value then parameter <span class="template">colshift</span>
extends the number of columns to delete to the left (if positive)
or to the right (if negative).</td>
</tr>
<tr>
<td class="top"><span class="template">colset=...</span></td>
<td>
<p>Define several set of columns, seperated with pipe (|). When
this parameters is used, then OpenTBS wil delete the set of
columns corresponding to the merged value.</p>
</td>
</tr>
</tbody>
</table>
<p>If a column number to delete is empty (''), or zero (0), or negative,
or over the actual number of colmun int the table, then the value is
ignored whitout raising error.</p>
<div class="shift">
<p>Examples:</p>
<table cellspacing="1" cellpadding="4" border="0">
<tbody>
<tr>
<th align="left">Example</th>
<th align="left">Description</th>
</tr>
<tr>
<td class="top">
<p><span class="template">[onshow.col_to_delete;ope=delcol]</span></p>
</td>
<td>
<p>if <span class="smallcode">$col_to_delete = 3</span>, then
it will delete columns 3.<br>
if <span class="smallcode">$col_to_delete = array(5,8)</span>,