• Why a new format
• Proposed format
  • Common
    • Blocks
  • Current
    • Blocks parameters (optional)
    • Children blocks (optional)
    • Types aliases
  • 1.0
• Examples
• TODO
  • provide a xsd too validate the content

Provide an easy to parse exact mapping of the rendering events.

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.

Why a new format

• pros
  • XML is the easiest syntax to parse in most of the environments and languages
  • exact mapping of the events/dom, no approximation/conversions needed
  • the exact mapping with events make it also easier to parser/render and should be quicker since there is no fancy conversion
  • the parser can easily support most of the events at once using reflexion to find the right methods of the API
  • provide a parsable event representation for rendering module unit tests
  • 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
• cons
  • new syntax
  • a lot more verbose than xwiki/2.0 syntax for example

Proposed format

It's actually one generic format and the needed freezed formats for each version of the rendering Listener API.

Common

What is common between all version of XDOM+XML syntax (for now at least).

Blocks

Each block is represented by a <block> element

Current

A dynamic version of the XDOM+XML format

Pros:

• parser does not need to know the blocks/events it just match events names with org.xwiki.rendering.listener.chaining.EventType
• 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
• renderer is pretty generic too since the real thing can be summarized to three methods directly called by the events:
  • beginEvent(EventType eventType, Object... parameters)
  • endEvent(EventType eventType)
  • onEvent(EventType eventType, Object... parameters)
• exact mapping of the blocks/events, nothing can be lost
• designed to be as fast and simple as possible to render/parse: the only logic in it is:
  • 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))
  • parameters conversion to and from XML (but there is plenty of tools to do that so nothing really need to be implemented here)
• support any kind of event without touching the dtd/xsd

Cons:

• 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
• only works from one version of the rendering API to the same

Blocks parameters (optional)

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.

Parameters are types but not names, they are following the same order than events parameters order.

For example a String parameter would give:
<string>value</string>

And a map containing one entry with String key and String value:
<map><entry><string>key</string><string>value</string></entry></map>

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.

Children blocks (optional)

Then children block are follow. There is no <childBlocks> or <blocks> element because it's not really needed.

Types aliases

• any java.util.Map implementation -> <map>

1.0

A freezed format of the XDOM+XML syntax.

Pros:

• works whatever the version of the rendering API
• makes possible to compact a bit more the result by not being generic

Cons:

• will need a 1.1 version etc.. for each modification of the rendering API

Examples

would gives something like (extended here to be more readable, otherwise it's supposed to be compacted)

TODO

provide a xsd too validate the content