Show last authors
1 {{toc/}}
2
3 Provide an easy to parse exact mapping of the rendering events.
4
5 One direct use case is the support of generic markers in the XHTML renderer for example, we want to put in a XHTML comment what was the source dom before behing transformed so we need to be able to write the exact source dom without loosing anything and if possible as quickly as possible.
6
7 = Why a new format
8
9 * pros
10 ** XML is the easiest syntax to parse in most of the environments and languages
11 ** exact mapping of the events/dom, no approximation/conversions needed
12 ** the exact mapping with events make it also easier to parser/render and should be quicker since there is no fancy conversion
13 ** the parser can easily support most of the events at once using reflexion to find the right methods of the API
14 ** provide a parsable event representation for rendering module unit tests
15 ** can be used as the standard rendering syntax, the one on which you can check all the others and the simplest one for internal use
16 * cons
17 ** new syntax
18 ** a lot more verbose than xwiki/2.0 syntax for example
19
20 = Proposed format
21
22 It's actually one generic format and the needed freezed formats for each version of the rendering Listener API.
23
24 == Common ==
25
26 What is common between all version of XDOM+XML syntax (for now at least).
27
28 === Blocks
29
30 Each block is represented by a <block> element
31
32 == Current ==
33
34 A dynamic version of the XDOM+XML format
35
36 Pros:
37 * parser does not need to know the blocks/events it just match events names with ##org.xwiki.rendering.listener.chaining.EventType##
38 * so it's easy to add a new block without breaking the format or touching the parser: just need to add the corresponding entry in ##org.xwiki.rendering.listener.chaining.EventType## and make sure all the types are covered by ParameterManager component
39 * renderer is pretty generic too since the real thing can be summarized to three methods directly called by the events:
40 ** ##beginEvent(EventType eventType, Object... parameters)##
41 ** ##endEvent(EventType eventType)##
42 ** ##onEvent(EventType eventType, Object... parameters)##
43 * exact mapping of the blocks/events, nothing can be lost
44 * designed to be as fast and simple as possible to render/parse: the only logic in it is:
45 ** to find the right ##EventType## from the name stored in the ##<block>## element (which just mean calling Enum.valueOf("ON_" + name) and Enum.valueOf("BEGIN_" + name))
46 ** parameters conversion to and from XML (but there is plenty of tools to do that so nothing really need to be implemented here)
47 * support any kind of event without touching the dtd/xsd
48
49 Cons:
50 * would take less place if block element was directly named from events names (<document> instead of <block name="document">) but that means and new events would need to modify the dtd
51 * only works from one version of the rendering API to the same
52
53 === Blocks parameters (optional)
54
55 Events parameters are stored in a the <parameters> element at the beginning of the <block> element. <parameters> has to be the first child element of a block.
56
57 Parameters are types but not names, they are following the same order than events parameters order.
58
59 For example a String parameter would give:
60 {{code language="xml"}}
61 <string>value</string>
62 {{/code}}
63
64 And a map containing one entry with String key and String value:
65 {{code language="xml"}}
66 <map><entry><string>key</string><string>value</string></entry></map>
67 {{/code}}
68
69 It's easier to write generic parser and renderer since parameters are serialized/unserialized in the right order and given as it to the events methods without having to do any special mapping between event parameter name and type.
70
71 === Children blocks (optional)
72
73 Then children block are follow. There is no <childBlocks> or <blocks> element because it's not really needed.
74
75 === Types aliases
76
77 * any java.util.Map implementation -> {{code language="xml"}}<map>{{/code}}
78
79 == 1.0 ==
80
81 A freezed format of the XDOM+XML syntax.
82
83 Pros:
84 * works whatever the version of the rendering API
85 * makes possible to compact a bit more the result by not being generic
86
87 Cons:
88 * will need a 1.1 version etc.. for each modification of the rendering API
89
90 = Examples
91
92 {{code language="none"}}
93 [[[[image:attach.png||height="100" width="100"]]>>url:http://xwiki.org||param=value .param2=value2]]
94 {{/code}}
95
96 would gives something like (extended here to be more readable, otherwise it's supposed to be compacted)
97
98 {{code language="xml"}}
99 <block name="document" version="current">
100 <block name="paragraph">
101 <block name="link">
102 <parameters>
103 <org.xwiki.rendering.listener.ResourceReference>
104 <type>url</type>
105 <reference>http://xwiki.org</reference>
106 </org.xwiki.rendering.listener.ResourceReference>
107 <boolean>false</boolean>
108 <map>
109 <entry>
110 <string>param</string>
111 <string>value</string>
112 </entry>
113 <entry>
114 <string>.param2</string>
115 <string>value2</string>
116 </entry>
117 </map>
118 </parameters>
119 <block name="image">
120 <parameters>
121 <org.xwiki.rendering.listener.ResourceReference>
122 <type>attach</type>
123 <reference>attach.png</reference>
124 </org.xwiki.rendering.listener.ResourceReference>
125 <boolean>false</boolean>
126 <map>
127 <entry>
128 <string>height</string>
129 <string>100</string>
130 </entry>
131 <entry>
132 <string>width</string>
133 <string>100</string>
134 </entry>
135 </map>
136 </parameters>
137 </block>
138 </block>
139 </block>
140 </block>
141 {{/code}}
142
143 {{code language="xml"}}
144 <block name="document" version="1.0">
145 <block name="paragraph">
146 <block name="link">
147 <reference>
148 <type>url</type>
149 <reference>http://xwiki.org</reference>
150 </link>
151 <!-- No need to put the freestanding information because it's the default value (false) -->
152 <parameters>
153 <param>value</param>
154 <!-- Extended form because ".param2" is an invalid XML node name -->
155 <entry name=".param2">value2</entry>
156 </parameters>
157 <block name="image">
158 <reference>
159 <type>attach</type>
160 <reference>attach.png</reference>
161 </reference>
162 <parameters>
163 <height>100</height>
164 <width>100</width>
165 </parameters>
166 </block>
167 </block>
168 </block>
169 </block>
170 {{/code}}
171
172 = TODO
173
174 == provide a xsd too validate the content
  • Powered by XWiki 11.10.2-node2. Hosted and managed by XWiki SAS

Get Connected