Wiki source code of XML-Based Reference Syntax
Last modified by Vincent Massol on 2011/11/15 10:17
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 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 |
