-
Notifications
You must be signed in to change notification settings - Fork 0
/
XTiger-XML-spec.html
806 lines (806 loc) · 49.2 KB
/
XTiger-XML-spec.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
<html>
<head>
<meta charset="UTF-8"/>
<link rel="stylesheet" href="css/Specification.css"/>
</head>
<body>
<h1>XTiger XML Language Specification</h1>
<p>Updated: May 10, 2013; Editor: Stéphane Sire (<a href="http://www.oppidoc.fr">Oppidoc</a> and <a href="http://www.media.epfl.ch">Media</a> research group)</p>
<h3>Notice</h3>
<p>You should have a reasonable understanding of XHTML and XML to be able to read this document. You are strongly encouraged to try the primitive editors described in this document by opening some template documents inside the <a href="http://ssire.github.com/axel/editor/editor.xhtml">AXEL demonstration editor</a> which is available online. This specifiation itself is maintained in a GitHub <a href="https://github.com/ssire/xtiger-xml-spec">repository</a> using an XTiger template and an editor built with <a href="http://ssire.github.com/axel/">AXEL</a>. The latest version is published at <a href="http://ssire.github.com/xtiger-xml-spec/">http://ssire.github.com/xtiger-xml-spec/</a>.</p>
<h3>Table of content</h3>
<ol>
<li><a href="#intro">Introduction to the XTiger XML language</a></li>
<li><a href="#anatomy">Anatomy of an XTiger XML document</a></li>
<li><a href="#primitive">Primitive component types</a></li>
<li><a href="#head">The "xt:head" element</a></li>
<li><a href="#component">The "xt:component" element</a></li>
<li><a href="#use">The "xt:use" element</a></li>
<li><a href="#attribute">The "xt:attribute" element</a></li>
<li><a href="#marker">The "xt:menu-marker" element</a></li>
<li><a href="#repeat">The "xt:repeat" element</a></li>
<li><a href="#text">The "text" primitive component type</a></li>
<li><a href="#select">The "select" primitive component type</a></li>
<li><a href="#processing">XTiger XML Processing Model</a></li>
<li><a href="#styling">Styling XTiger XML templates</a></li>
<li><a href="#summary">Summary tables</a></li>
<li><a href="#deprecated">Deprecated features</a></li>
</ol>
<h2 id="intro">Introduction to the XTiger XML language</h2>
<p>XTiger XML defines several XML elements and their attributes which can be mixed on a host document using the <tt>xt:</tt> prefix associated with the <tt>"http://ns.inria.org/xtiger"</tt> namespace. Note that this namespace was first introduced at INRIA for an <a href="http://www.w3.org/Amaya/Templates/XTiger-spec.html">XTiger language</a> that is a precursor of XTiger XML. The rest of this document will use the term XTiger for XTiger XML.</p>
<p>The combination of XTiger with an host document forms a <strong>template document</strong>. Such a document can be processed by an XTiger processing engine for different purposes.</p>
<p>The purpose of a template document is to describe a visual presentation for a document that will be used to edit XML data. This is similar to a formular. When the template document is processed with an adequate engine it becomes interactive and the user can enter data. The processing engine is also able to load XML data into the template and to save back XML data from the template. </p>
<p>Currently there is one XTiger processing engine called <strong>AXEL</strong> (Adaptable XML Editing Library). It transforms template documents hosted on an XHTML document into XML authoring applications. You can name the template document with any suffix, but it is wised to name it with an <em>".html"</em> or a <em>".xhtml"</em> suffix to be able to open it directly inside a browser. Note that if you open it without transforming it you may only see parts of it.</p>
<p>The figure below summarizes the languages involved in a template document : the host language (XHTML) serves a a view to generate a document form, some XTiger attributes and elements define some contraints driving the evolution of the structure of the host document while editing, two XTiger attributes (<em>label</em> and <em>name</em>) define a mapping from the document form to a target XML content model that a linearization algorithm can generate at any time.</p>
<div class="illustration">
<img src="images/layers.png"/>
<p>Layered view of an XTiger XML document</p>
</div>
<p>In summary, when writing an XTiger XML template document, you should have on one hand an idea of the XML Content Model you want to edit, and on the other hand an idea of a presentation document based on XHTML that you would like your formatted data looks like. The processing engine will transform some of the XTiger elements embedded inside the XHTML template into dynamical data entry fields that will allow to edit the document and to save the edited data to XML when finished. This is what we call <em>pseudo-WYSIWIG</em> editing.</p>
<h2 id="anatomy">Anatomy of an XTiger XML document</h2>
<p>A typical XTiger document looks like the following simple "hello world" document template below:</p>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<head>
<title>My first template</title>
<xt:head <strong>label="greetings"</strong>>
<xt:component name="t_friend">
<li><xt:use types="text">name</xt:use><xt:menu-marker/></li>
</xt:component>
</xt:head>
</head>
<body>
<p>List of persons to great:</p>
<ul>
<xt:repeat minOccurs="0" maxOccurs="*" <strong>label="persons"</strong>>
<xt:use types="t_friend" <strong>label="name</strong>"/>
</xt:repeat>
</ul>
</body>
</html></pre>
<p>As you can see, it contains two parts: </p>
<ul>
<li>a <tt>xt:head</tt> section within the XHTML document <tt>head</tt> section; it contains some definition of some component types inside <tt>xt:component</tt> elements which can themselves contain the same content as the body part of the document;</li>
<li>the <tt>body</tt> part of the XHTML document which can, in addition to its XHTML content, declare some inclusion of types (i.e. components) and some constaints on the document structure (i.e. repetition and optionality) with the XTiger vocabulary.</li>
</ul>
<p>The example above declares a single component type named friend. This component type is included in the body section where it can be repeated between zero and a non limited number of times. Consequently, when used to enter data, the previous template can produce the following target XML document:</p>
<pre><greetings>
<persons/>
</greetings></pre>
<p>or this one:</p>
<pre><greetings>
<persons>
<name>Charlie</name>
<name>Oscar<name>
</persons>
</greetings></pre>
<p>The mapping between the document template and the target XML content model is controlled with two attributes (in green in the document example above):</p>
<ul>
<li>a <tt>label</tt> attribute which can be set i) on the <tt>xt:head</tt> element to define the root of the target XML document, ii) when repeating some content (in the example above see the <tt>label="persons"</tt> on the repetition) and iii) when including a component type (see the <tt>label="name"</tt> declaration on the component type inclusion);</li>
<li>a <tt>name</tt> attribute which is mandatory when declaring an attribute (not shown in the example above).</li>
</ul>
<p>In the document template above you may also notice a <tt>xt:menu-marker</tt> element. This element is just a hint given to the XTiger processor for placing the Add / Remove buttons that will be generated to control the repetition inside the <tt>xt:repeat</tt> element. In the document above these buttons will be inserted in place of the <tt>xt:menu-marker</tt>, which means at the end of the <tt>li</tt> element. This way, they will appear at the end of the line and not on a new line, which would break the document layout. This type of hint if precious for the XTiger processor as it allows to keep a more natural document appearance when editing data.</p>
<h2 id="primitive">Primitive component types</h2>
<p>XTiger defines a set of built-in component types which are ultimately mapped to editable user interface text input fields. These built-in component types allow the user to enter or to modify data into the document. Consequently a template document that does not reference any built-in component type will not allow users to input new data, at most it will allow users to repeat static parts of the document, to change their order or to choose between different parts, which is not quite useful.</p>
<p>The built-in component types are included in the template document with an <tt>xt:use</tt> element with a pre-defined types attribute set to the unique type name of the built-in component. For instance the following declaration <<tt>xt:use types="text"</tt>><tt>name</tt><<tt>/xt:use/</tt>> includes a text editor that can be used to input a name, as suggested by its default value which is put in the element content.</p>
<p>An XTiger processor component library can be extended with new built-in components. This is usually done by creating a Javascript plugin which has to register it's type name to the library. This way it is possible to create many different editing interaction styles by using different plugin editors. For instance a common use of plugin editors is to create editors that constrain the input data, such as entering a date, or a number, uploading an image, etc.</p>
<p>An XTiger processor should at least implement 2 primitive component types: <tt>text</tt> and <tt>select</tt>. They will be described below.</p>
<h2 id="head">The <tt>"xt:head"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span><tt>xt:component</tt></span>
</p>
<p>
<span>Contained in</span>
<span><tt>head</tt> (XHTML)</span>
</p>
</div>
<p>The <tt>xt:head</tt> element contains the component types declaration section of the template document. It must be present even if it is empty.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>label</td>
<td>no</td>
<td>any string, defaults to <tt>instance</tt> if not defined</td>
<td>defines the tag name for the root element of the target XML content model of the template</td>
</tr>
</tbody>
</table>
<p>Currently XTiger XML does not interpret the other attributes for this element which are defined in the <a href="http://www.w3.org/Amaya/Templates/XTiger-spec.html">original XTiger specification</a>.</p>
<h3>Example</h3>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<head>
<xt:head <strong>label="test"</strong>/>
</head>
<body>
<p>Empty</p>
</body>
</html></pre>
<p>The template above generates only one XML content model:</p>
<pre><test/></pre>
<h2 id="component">The <tt>"xt:component"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span>any XHTML content, <tt>xt:use</tt>, <tt>xt:repeat</tt>, <tt>xt:attribute</tt>, <tt>xt:menu-marker</tt></span>
</p>
<p>
<span>Contained in</span>
<span><tt>xt:head</tt></span>
</p>
</div>
<p>The <tt>xt:component</tt> element declares a new component type which can be included later on with an <tt>xt:use</tt> element. The content of the component may be any regular XHTML, or it can includes other XTiger elements or both. The creation of nested components can be achieved by including other components within a component through one or more <tt>xt:use</tt> elements. This will also create nested XML data structures as the <tt>xt:use</tt> elements can be mapped to a tag name in the XML content model of the template (see below).</p>
<p>An <tt>xt:component</tt> may contain one or several optional <tt>xt:menu-marker</tt> elements. Each one is significant only if it is included within the scope of an <tt>xt:repeat</tt> element. In that case the <tt>xt:menu-marker</tt> element will be replaced by the user interface widget(s) for the repetition menu.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>yes</td>
<td>string</td>
<td>name for component type, it must be unique within all the components of a template document and it is used to insert the component with an <tt>xt:use</tt> element</td>
</tr>
<tr>
<td>i18n</td>
<td>no</td>
<td>string</td>
<td>label that is displayed for the option that represents the inclusion of this component in the menu generated in case of a <tt>xt:use</tt> element that references multiple types; this is used for internationalization purposes of a template document</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<p><em>modifier l'exemple pour illustrer menu-marker, prendre les keywords dans un article</em></p>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<xt:head>
<xt:component <strong>name="t_introduction"</strong>>
<p>I was born the <xt:use types="string" label="date">day of month, year <xt:use>
in <xt:use types="string" label="place">city</xt:use></p>
<xt:component>
</xt:head>
</head>
<body>
<h2>Presentation of <xt:use types="text" label="name" param="shape=parent">name</xt:use></h2>
<xt:use <strong>types="t_introduction"</strong> label="birth"/>
</body>
</html></pre>
<h2 id="use">The <tt>"xt:use"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span>empty, or text node</span>
</p>
<p>
<span>Contained in</span>
<span><tt>xt:component</tt>, <tt>xt:repeat</tt> or any XHTML element that can have child elements</span>
</p>
</div>
<p>The <tt>xt:use</tt> element includes a component inside the document. It may include a <strong>single component type</strong>, a <strong>primitive component type</strong>, or a <strong>list of component types</strong>.</p>
<h3>The "xt:use" element with a single component type</h3>
<p>This is the case when the <tt>types</tt> attribute contains the name of a component type which is declared by an <tt>xt:component</tt> element of the same name in the <tt>xt:head</tt> section of the template document. That inclusion will be treated by generating the component type's content in place of the <tt>xt:use</tt> element.</p>
<p>The optional <tt>label</tt> attribute defines the name of the target XML element to generate in the target document. If it is not defined it is inherited by the context. The <tt>xt:use</tt> element in this role should have an empty content.</p>
<h3>The "xt:use" element with a single primitive component type</h3>
<p>This is the case when the <tt>types</tt> attribute contains the name of a builtin component type. The list of builtin component types is dependent of the plugins defined by the XTiger processor, however the specification require to implement at least a <tt>text</tt> and a <tt>select</tt> primitive editor plugins.</p>
<p>The optional <tt>label</tt> attribute defines the name of the target XML element to generate in the target document. If it is not defined it is inherited by the context. The content of the <tt>xt:use</tt> element in this role is not defined per the specification. It should serve as a default content to initialize the primitive editor plugin. It is a good practice to set a self-explanatory default content that hints the user about the expected content</p>
<h3>The "xt:use" element with a list of component types</h3>
<p>This is the case when the <tt>types</tt> attribute contains a list of names of component types. For simplifying implementations, the list may be restricted to exclude any builtin component type.</p>
<p>The <tt>xt:use</tt> in this role generates a selection menu allowing the user to choose the component type to include at runtime. The current selection will define which component's content will replace the <tt>xt:use</tt> element. Unless using the <tt>xt:menu-marker</tt> to position the selection menu (see the explanations in the corresponding section), this menu is generated as a previous sibling of the current component's content.</p>
<p>The target content generated by this type of component inclusion is always enclosed inside an XML element baring the name of the current component selection. For instance, if the <tt>xt:head</tt> section define some <em>parag</em>, <em>list</em> and <em>figure</em> components :</p>
<pre><xt:use types="para list figure"/></pre>
<p>will generate one of the three :</p>
<pre><para>...</para>
or <list>...</list>
or <figure>...</figure></pre>
<p>target XML content. However it is possible to enclose the target XML content inside a parent XML element using a <tt>label</tt> attribute, as with the other cases. For instance :</p>
<pre><xt:use types="para list figure" label="definition"/></pre>
<p>will generate one of the three :</p>
<pre><definition><para>...</para></definition>
or <defnition><list>...</list></defnition>
or <defnition><figure>...</figure></defnition></pre>
<p>Finally if the <tt>label</tt> attribute contains a list of names instead of a single name, each name in the list will be matched with the corresponding name in the <tt>types</tt> list of names, and it will be used to generate the target XML element instead. Both lists must have the same size. For instance :</p>
<pre><xt:use types="para list figure" label="DefPara DefList DefFig"/></pre>
<p>will generate one of the three :</p>
<pre><DefPara>...</DefPara>
or <DefList>...</DefList>
or <DefFig>...</DefFig></pre>
<p>The <tt>xt:use</tt> element in this role should have an empty content.</p>
<p>The names that will appear in the selection menu will be either the component type names (e.g. above <em>para</em>, <em>list</em> or <em>figure</em>), the component names as defined per the <tt>label</tt> attribute if it is used to rename the target XML content tag names (e.g. above <em>DefPara</em>, <em>DefList</em>, <em>DefFig</em>), or the component name given by its <tt>i18n</tt> attribute if it has one. The i18n attribute supersedes any other choice.</p>
<h3>The optional <tt>"handle"</tt> attribute</h3>
<p>The <tt>xt:use</tt> element that includes a primitive component type may declare an optional <tt>handle</tt> attribute. This attribute is set to the name of a preferred XHTML element that should be used as a handle by the primitive editor plugin. This is mostly targeted at a text editing plugins that use a default <tt>span</tt> handle, to change that for a block-level handle that may be preferrable with some filters.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>types</td>
<td>yes</td>
<td>list of white space separated type names</td>
<td>lists the components which can be included at the position of the xt:use, if there are several names the XTiger processor will generate a selection menu</td>
</tr>
<tr>
<td>label</td>
<td>no</td>
<td>string</td>
<td>mapping with a tag name in the XML content model</td>
</tr>
<tr>
<td>option</td>
<td>no</td>
<td><tt>set</tt> or <tt>unset</tt></td>
<td>if this attribute is present, the xt:use content is optional, when its value is "set" the content is set by default whereas it is not set if its value is "unset" NOTE: actually option is interpreted if and only if <tt>types</tt> integrates a single primitive component type</td>
</tr>
<tr>
<td>handle</td>
<td>no</td>
<td>XHTML tag name</td>
<td>changes the default handle created by a primitive editor plugin to a specific one; note that this is plugin implementation dependent</td>
</tr>
<tr>
<td>param</td>
<td>no</td>
<td>list of semi-colon separated <tt>key=value</tt> pairs</td>
<td>declares some options which can be set for the primitive editor that will manage the component included with this xt:use; this attribute is only taken into account 1) if the <tt>xt:use</tt> contains only one type name in the types attribute and ii) if this is the type name of a registered primitive editor</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<xt:head <strong>label="presentation"</strong>>
<xt:component name="intro">
<p>I was born the <<em>xt:use types="string"</em><strong>label="date"</strong>>day of month, year <xt:use>
in <<em>xt:use types="string"</em><strong>label="place"</strong>>city</xt:use></p>
</xt:component>
</xt:head>
</head>
<body>
<h2>Presentation of <<em>xt:use types="text"</em><strong>label="name"</strong> param="shape=parent">name</xt:use>
</h2>
<<em>xt:use types="intro"</em><strong>label="birth"</strong>/>
</body>
</html></pre>
<p>The template above will generate the following type of XML data:</p>
<pre><presentation>
<name/>
<birth>
<date/>
<place/>
</birth>
</presentation></pre>
<p>You may have notice that the previous example is not completely internationalized, as some text inside the template itself, which is not part of the XML content model, such as the <h2> sub-title <em>Presentation of</em> , should also be internationalized. This is out of the scope of this specifciation. This can be chieved using different templating mechanisms that depend of the server-side framework used to serve the templates themselves.</p>
<h2 id="attribute">The <tt>"xt:attribute"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span>emtpy or text node</span>
</p>
<p>
<span>Contained in</span>
<span>descendant of an <tt>xt:component</tt> or an <tt>xt:repeat</tt> element</span>
</p>
</div>
<p>The <tt>xt:attribute</tt> element includes a built-in component type that will be mapped to an XML attribute in the XML content model of the document. This XML attribute will be attached to the current XML element in scope when generating the XML data. The component type name is given in the <tt>types</tt> attribute, which although in a plural form must contain only one component type name.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>types</td>
<td>yes</td>
<td>a primitive component type</td>
<td>sets the built-in editor that will be used to edit the attribute; this is restricted to a primitive component type editor (e.g. <tt>text</tt> or <tt>select</tt>)</td>
</tr>
<tr>
<td>name</td>
<td>yes</td>
<td>string</td>
<td>mapping withn an attribute name in the target XML content model</td>
</tr>
<tr>
<td>option</td>
<td>no</td>
<td><tt>set</tt> or <tt>unset</tt></td>
<td>if this attribute is present, the xt:attribute is optional, when its value is "set" it is set by default whereas it is not set if its value is "unset"</td>
</tr>
<tr>
<td>values</td>
<td>no</td>
<td>optional white space separated list of the values allowed for the attribute</td>
<td>defines a list of allowed values for the attribute, <strong>this only applies with a primitive component type that manages a list of choices</strong> (i.e. at that moment this is the case only with the <tt>select</tt> primitive component type)</td>
</tr>
<tr>
<td>default</td>
<td>yes</td>
<td>string</td>
<td>if the attribute value is defined by a list of <tt>values</tt>, then the default one must be defined by this attribute</td>
</tr>
<tr>
<td>i18n</td>
<td>no</td>
<td>optional white space separated list of the labels to display for each value in the <tt>values</tt> attribute</td>
<td>if the attribute value is defined by a list of <tt>values</tt>, then it gives a list of corresponding labels for each value in the menu that presents the allowed values to the user; if present, the order of the labels in this list must be the same as the order of the corresponding <tt>values</tt></td>
</tr>
<tr>
<td>handle</td>
<td>no</td>
<td>XHTML tag name</td>
<td>changes the default handle created by a primitive editor plugin to a specific one; note that this is plugin implementation dependent (same as for <tt>xt:use</tt>)</td>
</tr>
<tr>
<td>param</td>
<td>no</td>
<td>list of semi-colon separated <tt>key=value</tt> pairs</td>
<td>declares some primitive editor's dependent options</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<xt:head <strong>label="book"</strong>>
<xt:component name="author">
<p>My name is <xt:use types="text" <strong>label="name"</strong>>your name<xt:use>,
but you can call me <xt:attribute types="text" <strong>name="nickname"</strong>>your nickname</xt:attribute></p>
</xt:component>
</xt:head>
</head>
<body>
<xt:use types="author" <strong>label="author"</strong>/>
</body>
</html></pre>
<p>The extract above will generate the following type of XML data:</p>
<pre><book>
<author nickname="your nickname">
<name>your name</name>
</author>
</book</pre>
<h2 id="marker">The <tt>"xt:menu-marker"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span>empty</span>
</p>
<p>
<span>Contained in</span>
<span>descendant of an <tt>xt:component</tt> or an <tt>xt:repeat</tt> element</span>
</p>
</div>
<h3>Usage for controlling an "xt:repeat" repetition menu insertion point</h3>
<p>The <tt>xt:menu-marker</tt> element must be placed inside the scope of an <tt>xt:repeat</tt> element (either as a direct descendant or as a descendant after one or more type inclusions through <tt>xt:use</tt> elements). It controls the insertion point of the Add / Remove buttons generated by the XTiger processor when transforming the <tt>xt:repeat</tt> element. For instance in the following <em>list</em> component :</p>
<pre><xt:component name="list">
<ul>
<xt:repeat minOccurs="1" maxOccurs="*" label="list"/>
<li>click to enter an item <strong><xt:menu-marker/></strong></li>
</xt:repeat>
</ul>
</xt:component></pre>
<p>The repetition Add / Remove buttons must be generated as the last child of each <em>li</em> element, whereas without any <tt>xt:menu-marker</tt> set, they would be generated as first child of the repeated fragments, which means just before each <em>li</em> element.</p>
<h3>Usage for controlling an "xt:use" selection menu insertion point</h3>
<p>The <tt>xt:menu-marker</tt> element can also be used to control the insertion point of the selection menu generated by an <tt>xt:use</tt> element contained in the same <tt>xt:component</tt>. For that purpose the <tt>xt:use</tt> element must declare in a <tt>param</tt> attribute a <tt>name</tt> parameter that serves as an identifier. That identifier must also be set as the value of the <tt>target</tt> attribute of the <tt>xt:menu</tt> marker.</p>
<p>For instance the following component contains two <tt>xt:menu-marker</tt> elements. The one without a <tt>target</tt> attribute will be used to insert the Add / Remove buttons of it's enclosing <tt>xt:repeat</tt> element as described above. The one with a <tt>target</tt> attribute will be used to insert the selection menu for the <tt>xt:use</tt> with a choice of multiple component types :</p>
<pre><xt:component name="section">
<xt:repeat minOccurs="1" maxOccurs="*" label="section">
<div class="row">
<div class="menu">
<xt:menu-marker <strong>target="t_select"</strong>/><br/>
<xt:menu-marker/>
</div>
<xt:use types="parag list title1 title2" <strong>param="name=t_select"</strong>/>
</div>
</xt:repeat>
</xt:component></pre>
<p>Together with a proper choice of class names and CSS rules, this is a convenient way to group repetition and selection menus, and to control the position of those menus to improve user interaction.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>size</td>
<td>no</td>
<td>an integer (e.g. 20, default to <strong>16</strong>)</td>
<td>optional size in pixels for the buttons; it's interpretation is implementation dependent</td>
</tr>
<tr>
<td>target</td>
<td>no</td>
<td>name of a named <tt>xt:use</tt></td>
<td>the <tt>xt:menu-marker</tt> will be used to display the selection menu for a named <tt>xt:use</tt> element declared within the same <tt>xt:component</tt></td>
</tr>
</tbody>
</table>
<h2 id="repeat">The <tt>"xt:repeat"</tt> element</h2>
<div class="containBox">
<p>
<span>Contains</span>
<span>any XHTML content, xt:use, xt:repeat, xt:attribute, xt:menu-marker</span>
</p>
<p>
<span>Contained in</span>
<span>any XHTML element that can have child elements, xt:component, or another xt:repeat</span>
</p>
</div>
<p>The <tt>xt:repeat</tt> element defines a document fragment that can be repeated zero or more times. A zero time repetition means that the fragment is optional and is not set. The <tt>xt:repeat</tt> element will generate some interaction element (a pair of Add / Remove buttons) that will be inserted in place of the first <tt>xt:menu-marker</tt> element inside the fragment, or inserted at the end of the fragment if it doesn't contain any.</p>
<p>The <tt>xt:repeat</tt> element can be mapped to a tag name in the XML content model through a <tt>label</tt> attribute, in a way similar to the <tt>xt:use</tt> element. If it is not associated with a tag name, it must declare in a <tt>pseudoLabel</tt> attribute the list of the names of the first tag names that may appear first in the target XML content model. This is mandatory to allow the XTiger processor to correctly load XML data into the template.</p>
<h3>Attributes</h3>
<table>
<thead>
<tr>
<th>Name</th>
<th>Mandatory</th>
<th>Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>minOccurs</td>
<td>no</td>
<td>integer (defaults to 0)</td>
<td>minimum number of inclusions of the content fragment in the document, 0 means it is optional (<em>currently the only supported values are 0 or 1</em>)</td>
</tr>
<tr>
<td>maxOccurs</td>
<td>no</td>
<td>integer or <tt>*</tt> (defaults to <tt>*</tt>)</td>
<td>maximum number of inclusions of the content fragment in the document, * means there is no limit (<em>currently the only supported value are 1 or *</em>)</td>
</tr>
<tr>
<td>label</td>
<td>yes (unless <em>pseudoLabel</em> is defined)</td>
<td>string</td>
<td>mapping with a tag name in the XML content model</td>
</tr>
<tr>
<td>pseudoLabel</td>
<td>yes (unless <em>label</em> is defined)</td>
<td>string</td>
<td>in case <tt>label</tt> is not defined on the <tt>xt:repeat</tt>, it must contains a list of the names of the first XML tag names that may appear in first position in the repeated target XML content model</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<pre><?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xt="http://ns.inria.org/xtiger">
<head>
<xt:head <strong>label="menucard"</strong>>
<xt:component name="dish">
<p><xt:menu-marker/><xt:use types="text">dish</xt:use>
costs <xt:attribute types="text" <strong>name="price"</strong> default="00"/> euros</p>
</xt:component>
</xt:head>
</head>
<body>
<h2>Restaurant Menu Card</h2>
<<em>xt:repeat minOccurs="0" maxOccurs="*"</em><strong>pseudoLabel="dish"</strong>>
<xt:use types="dish" <strong>label="dish"</strong>/>
</<em>xt:repeat</em>>
</body>
</html></pre>
<p>The extract above will generate the following type of XML data:</p>
<pre><menucard>
<dish price="20">Chicken and fries</dish>
<dish price="30">Noodles and salmon</dish>
<dish price="15">Rice and pork</dish>
</menucard></pre>
<h2 id="text">The <tt>"text"</tt> primitive component type</h2>
<div class="containBox">
<p>
<span>Synopsis</span>
</p>
<pre><xt:use types="text" label="parag" param="type=textarea;layout=float">
Write a new paragraph here.</xt:use></pre>
<pre><xt:attribute types="text" name="birthdate" default="year"
param="type=input;layout=placed;expansion=none" option="set"/></pre>
</div>
<p>The <tt>text</tt> primitive component type is associated with a text editor that generates a span in the document and either an input field or a textarea field (for multilines entry) in the document. The difference with the string editor is that the input or the textarea fields are shared between all the text primitive editors which are created inside the document.</p>
<p>The text editor supports two types of input or textarea fields with different layout. The float layout dynamically positions the input or the textarea on top of the content to edit when the user clicks on it (using CSS absolute positioning). The placed layout dynamically replaces the content to edit, which is stored in a span, by the input or the textarea field when the user clicks on the content. Once the editing is finished, a float field is hidden revealing the content span which is updated with the last entry; similarly, a placed field is replaced back with the content span.</p>
<p>The text editor supports the <tt>option</tt> attribute of the <tt>xt:use</tt> or <tt>xt:attribute</tt> element that includes it. If this attribute is present it generates a checkbox from which the user can include its content into the document or not.</p>
<p>The content of this editor is initialized to the text content of the <tt>xt:use</tt> element, or to the value of the <tt>default</tt> attribute of the <tt>xt:attribute</tt> element.</p>
<p>The text editor is controlled by passing a list of option declarations into the <tt>param</tt> attribute on the XTiger element that includes it into the document. For instance the example in the synopsis creates a text editor with a shared textarea and a float layout.</p>
<h3>Parameters (passed through the <tt>param</tt> attribute on xt:use)</h3>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Values</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>'input' (default)</td>
<td>the edit field is an <input> (shared at the document level between all the instances)</td>
</tr>
<tr>
<td>type</td>
<td>'textarea'</td>
<td>the edit field is a <textarea> (shared at the document level between all the instances)</td>
</tr>
<tr>
<td>layout</td>
<td>'placed' (default)</td>
<td>the edit field is inserted dynamically into the DOM instead of the <span> handle</td>
</tr>
<tr>
<td>layout</td>
<td>'float'</td>
<td>the edit field is placed dynamically on top of the <span> handle using CSS absolute positioning</td>
</tr>
<tr>
<td>shape</td>
<td>'self' (default)</td>
<td>the shape/length of the edit field equals the current shape of the handle</td>
</tr>
<tr>
<td>shape</td>
<td>'parent'</td>
<td>the shape of the edit field equals the current shape of the parent of the handle</td>
</tr>
<tr>
<td>class</td>
<td>string</td>
<td>a class name to set on the handle (e.g. span) that displays the editor content; it must also be set on the entry field when editing</td>
</tr>
<tr>
<td>expansion</td>
<td>'grow' (default)</td>
<td>the edit field expands as the user types text; the direction of the expansion may depend on the implementation of the primitive editor and on the 'shape' parameter too, for instance an edit field implemented as an <input> can only grow horizontally, while an edit field implemented as a <textarea> will grow horizontally if its shape is set to 'self' and vertically if its shape is set to 'parent'</td>
</tr>
<tr>
<td>expansion</td>
<td>'none'</td>
<td>the edit field has a fixed shape/length</td>
</tr>
</tbody>
</table>
<h3>Recommended "clickthrough" behavior</h3>
<p>The <tt>text</tt> plugin should position the cursor at the character under the mouse when switching to edit mode.</p>
<h2 id="select">The <tt>"select"</tt> primitive component type</h2>
<div class="containBox">
<p>
<span>Synopsis</span>
</p>
<pre><xt:attribute types="select" label="country" default="Switzerland"
values="France Italy Switzerland"/></pre>
<pre><xt:attribute types="select" label="currency" default="EUR"
values="EUR USD CHF" i18n="Euro Dollars Franc-Suisse"/></pre>
<pre>or alternatively :
<xt:use types="select" label="currency"
values="EUR USD CHF" i18n="Euro Dollars Franc-Suisse">EUR</xt:use></pre>
</div>
<p>The <tt>select</tt> primitive component type is associated with a popup menu editor that generates a span in the document that contains a current selection. The popup menu is displayed each time the user clicks on the span and it updates its value to the selected value.</p>
<p>The select editor supports the <tt>option</tt> attribute of its host element. If this attribute is present it generates a checkbox from which the user can include its content into the document or not.</p>
<p>The <tt>select</tt> primitive component is mainly associated with an <tt>xt:attribute</tt> element because it uses its <tt>values</tt> attribute (and optionaly its <tt>i18n</tt> attribute) to build the options of the popup menu, and it gets the option selected by default from its <tt>default</tt> attribute. However it is tolerated than an implementation supports the <tt>select</tt> plugin with an <tt>xt:use</tt> element. In that case it will extend its definition to support a <tt>values</tt> and an <tt>i18n</tt> attributes, however the selected option by default will be declared in the text content of the <tt>xt:use</tt>.</p>
<p>This editor does not currently manage any parameter in the <tt>param</tt> attribute.</p>
<h2 id="processing">XTiger XML Processing Model</h2>
<p>The AXEL (Adaptable XML Editing Library) XTiger processor is implemented as a Javascript client-side library. You have the choice to import this Javascript library directly into the template file, using script tags, to make it an <em>auto-editable template</em>. As an alternative you can use an editing application. Such applications can be built with the library. They should allow to load templates and to edit documents with them. They should allow to load XML data into the documents and to save back the document to XML data. Editing applications may load the template to transform inside an <tt>iframe</tt>, or they can use an XHR request and transform the template inside a target <tt>div</tt> element. This is explained in a tutorial coming with the library.</p>
<p>The Javascript processor takes as input a template document. It's invocation should start by a rendering process to generate the editor. Then it should expose, using an API, a generation process, to linearize the current editor's content into XML, and optionally a loading process, to replace current editor's content with external XML data.</p>
<div class="illustration">
<img src="images/processing.png"/>
<p>AXEL processing model</p>
</div>
<p>The rendering process should load the template document into the browser memory and then transforms it, removing the XTiger elements and generating adequate XHTML content to turn the document into an interactive editable document. During this transformation the processor creates some Javascript objects to control user's input and the dynamic display of user interaction elements (e.g. buttons, popup menus, etc.).</p>
<h2 id="styling">Styling XTiger XML templates</h2>
<p>The AXEL XTiger processor engine generates some pre-defined CSS class names while transforming a template document. These are used to style the generated editing application. Most of the time, as a document template author, you will use the standard <tt>axel.css</tt> file which is distributed with AXEL (path: <tt>axel/axel.css</tt>). But you may also redefine some of these rules or override them using an <tt>!important</tt> CSS instruction.These CSS class names are described in the table below.</p>
<p>The most interesting class name is <tt>axel-core-editable</tt> which is set on the handle of primitive editors. It can be used for instance to improve feedback about the editable fields by using <tt>:hover</tt> pseudo selectors.</p>
<p>For convenience, the CSS rules are defined in two different files in the AXEL source code distribution, these two files are concatenated to form the <tt>axel/css</tt> file when you build the library from source:</p>
<ul>
<li><tt>stylesheets/axel-core.css</tt> defines core rules required for the basic functionalities of the library to operate, you should not alter them</li>
<li><tt>stylesheets/axel-style.css</tt> defines the appearance of the editors, these are the rules you are more likely to modify to comply with your look and feel</li>
</ul>
<p>The next table gives a few example of common CSS selectors set by the library, have a look at the second part of the <tt>axel.css</tt> (or to <tt>stylesheets/axel-style.ss</tt>) file to see all of them.</p>
<table>
<thead>
<tr>
<th>Source</th>
<th>Class (or selector)</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>internal</td>
<td>axel-generator-error</td>
<td>highlights fragments generated from an XTiger template when some error occurred during the transformation process</td>
</tr>
<tr>
<td><tt>xt:repeat</tt> element</td>
<td>axel-repeat-left</td>
<td>left image button (<em>delete</em>)</td>
</tr>
<tr>
<td><em>idem</em></td>
<td>axel-repeat-right</td>
<td>right image button (<em>add</em>)</td>
</tr>
<tr>
<td><tt>text</tt> primitive editor</td>
<td>axel-core-editable</td>
<td>set on the handle (usually a <span>) that contains some editable text</td>
</tr>
<tr>
<td>any editor made optional with the <tt>option</tt> attribute</td>
<td>axel-option-checkbox</td>
<td>checkbox image</td>
</tr>
<tr>
<td><em>idem</em></td>
<td>axel-option-set</td>
<td>set on the handle of an optional editor which is set</td>
</tr>
<tr>
<td><em>idem</em></td>
<td>axel-option-unset</td>
<td>set on the handle of an optional editor which is unset</td>
</tr>
<tr>
<td><tt>select</tt> primitive editor</td>
<td>axel-popup-container</td>
<td><div> container for the popup menu</td>
</tr>
<tr>
<td><em>idem</em></td>
<td>.axel-popup-container li.selected</td>
<td>current selected item in the popup menu</td>
</tr>
<tr>
<td><em>idem</em></td>
<td>.axel-popup-container li.selectable</td>
<td>item that may be selected in the popup menu</td>
</tr>
</tbody>
</table>
<h2 id="summary">Summary tables</h2>
<h3>Attributes per component types for use with <tt>xt:use</tt> and <tt>xt:attribute</tt></h3>
<table>
<thead>
<tr>
<th>XTiger element</th>
<th>Attributes (bold if mandatory)</th>
<th>Values for ''types''</th>
<th>''option'' attribute</th>
<th>"handle" attribute</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>xt:use</tt></td>
<td><strong>types</strong>, label, option, handle, param</td>
<td>text</td>
<td>supported</td>
<td>supported</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>select</td>
<td>supported</td>
<td>no</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>single component type defined in the <tt>xt:head</tt> section</td>
<td>no (use a <tt>xt:repeat</tt> with maxOccurs="1")</td>
<td>no</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>list of component types</td>
<td>(use a <tt>xt:repeat</tt> with maxOccurs="1")</td>
<td>no</td>
</tr>
<tr>
<td><tt>xt:attribute</tt></td>
<td><strong>types</strong>, <strong>name</strong>, option, handle, param, <strong>default</strong>, values, i18n (NOTE: the last 3 are only used with types set to select)</td>
<td>text</td>
<td>supported</td>
<td>supported</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>select</td>
<td>supported</td>
<td>no</td>
</tr>
</tbody>
</table>
<h3>Parameters Key-Value pairs per component types</h3>
<table>
<thead>
<tr>
<th>Primitive component type</th>
<th>Allowed in</th>
<th>Key </th>
<th>Value (default)</th>
</tr>
</thead>
<tbody>
<tr>
<td>text</td>
<td><tt>xt:use</tt>, <tt>xt:attribute</tt></td>
<td>type</td>
<td>input, textarea (input)</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>shape</td>
<td>parent<em>[-NBpx]</em>, self (self)</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>layout</td>
<td>float, placed (placed)</td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>class</td>
<td><em>class name</em></td>
</tr>
<tr>
<td>-</td>
<td>-</td>
<td>expansion</td>
<td>grow, none (grow)</td>
</tr>
<tr>
<td>select</td>
<td><tt>xt:attribute</tt></td>
<td>N/A</td>
<td>N/A</td>
</tr>
</tbody>
</table>
<h2 id="deprecated">Deprecated features</h2>
<h3>The "string" primitive component type</h3>
<p><em>The "string" primitive editor has been removed on May 10, 2013. It is superseded by the "text" primitive editor.</em></p>
<h3>The "flow" attribute of the "xt:use" element</h3>
<p><em>The "flow" attribute has been removed on May 10, 2013. It has been deprecated to simplify XTiger implementations, and because it can be replaced with server-side code to aggregate / dispatch document fragments from / to multiple sources.</em></p>
</body>
</html>