[xwiki-devs] [Discussion] Designing the new Rendering/Parsing component/API

[Vincent Massol]

On Sep 24, 2007, at 12:23 PM, Mikhail Kotelnikov wrote:

> Hi!
>
> On 9/22/07, Vincent Massol <vincent at massol.net > wrote:
> Thinking more about storing documents into a DOM in the database, I
> have found 2 issues to discuss:
>
> 1) Using verbatim blocks is going to be a nightmare for users.
> Consider your example below using verbatim blocks:
>
> -------------------------------------
> // WikiModel:
> -------------------------------------
> <div>
> <h1>Hello {{{$customer.Name}}}!</h1>
> <table>
> {{{#foreach( $mud in $mudsOnSpecial )
>
>     #if ( $customer.hasPurchased($mud) )
> }}}
>        <tr>
>          <td>
> {{{         $flogger.getPromo( $mud )
> }}}
>          </td>
>        </tr>
> {{{
>     #end
> #end
> }}}
> </table>
> </div>
>
> It's really ugly and eve worse than the <% from groovy.. :)
>
>
> I would say that your example should be:
> ----------------------------------------------------
> = Header1 =
> This  is a normal wiki syntax...
>
> * list item one
> * list item two
>
> And the verbatim block below contains Velocity markup:
> {{{
> <div>
> <h1>Hello {{{$customer.Name}}}!</h1>
> <table>
> #foreach( $mud in $mudsOnSpecial )
>    #if ( $customer.hasPurchased($mud) )
>       <tr>
>         <td>
>           $flogger.getPromo( $mud )
>         </td>
>       </tr>
>    #end
> #end
> </table>
> </div>
> }}}
>
> This  is a normal wiki syntax again...
> ----------------------------------------------------
>
> In this case the processing of your verbatim block will lead to  
> generation of the (X)HTML. (It is up to the template implementor to  
> generate a well-formed XHTML).
>
> By the way: maybe I was not clear but all "<" and ">" symbols in  
> normal wiki blocks (like paragraphs, tables; not in verbatim  
> blocks) are considered as "special" symbols.
> For example the "before<table>after" string in the middle of a wiki  
> document will be reported in listeners as following:
> - onWord: "before"
> - onSpecialSymbol: "<"
> - onWord: "table"
> - onSpecialSymbol: ">"
> - onWord: "after"

Right I was wrong, the HTML is indeed inside the verbatim block. BTW,  
we'll need a way to parse verbatim blocks to know which parser to be  
used (Groovy, Velocity, etc).

My example was bad but I think the issue still stands, just not as a  
bad as with HTML.

The points I was making is that having to force velocity syntax into  
verbatim blocks makes unfriendly which isn't good and doesn't provide  
a fluent integration of velocity with wiki syntax. I think this was  
one of the nice thing in current xwiki.

>  2) We need to consider current users who are using velocity
> intermixed with wiki syntax and we need to continue supporting them,
> either by having TextProcessors and a VelocityTextProcessor (thus
> storing text in the DB) or by somehow converting the current way of
> writing velocity to the "new" way, whatever this is. But in any case
> we need to find something better than what is in 1) above. I'd hate
> that it be worse for users. This leads me to believe we might need to
> keep TextProcessors and store the content in textual format in the DB.
>
> You can have the following scenarios:
>
> Scenario A: Processing of the  source for each request
> 1. You load your content from  the DB
> 2. You process the content using a template engine (Velocity/ 
> Freemarker/StringTemplate/...). The whole page is considered as a  
> simple template for the corresponding template engine.
> 3. The results of such a processing is parsed by the WikiModel  
> parsers.
> pro: You template engine can be used to generate additional wiki  
> elements. No needs to use "embedded blocks" and stuff like that
> con: You have to repeat the operations 2) and 3) for *each  
> request*. These steps are the slowest steps in the page processing.
>
> Scenario B: You process only some verbatim blocks containing  
> template-based "inclusions".
> 1. You load your page from the DB as an XML document or as a wiki  
> syntax
> 2. You parse it and transform the content into an in-memory  
> structure (DOM). This object can be cached in memory.
> 3. You handle only some verbatim blocks in this DOM structure to  
> transform its content using a template engine.
> pro: For each query you repeat only the step 3. The initial DOM  
> structure is the same and it can be cached. In this case we avoid  
> the parsing the wiki document from wiki syntax or DOM
> con: You can not generate the wiki syntax. Your template blocks  
> have to generate the resulting (X)HTML.
>
> Personally I prefer the Scenario B. In this case some verbatim  
> blocks can be considered as an HTML/TeX/... markup, as Groovy/ 
> Javascript/JPython/JRuby/... script blocks and some - as template  
> blocks (Velocity/Freemarker/StringTemplate/...)

Yes, this is exactly my point. I don't see a way to have the pros of  
both A and B.

I'm leaning towards B right now, not for performance reasons of  
course (for this B is better) but for usability and backward  
compatibility.

When say you "prefer" solution B, I'm pretty sure you're preferring  
it as a developer but not as an end user. The following:

{{{
#foreach ($link in $doc.backlinks)
* [whatever>$link]
#end
}}}

Is always more complex for users than:

#foreach ($link in $doc.backlinks)
* [whatever>$link]
#end

I feel users will write stuff like this:

{{{
full content of the page containing wiki syntax and velocity markup
}}}

which means we're back to square one and to solution A, since we can  
have velocity markup include wiki syntax...

This in term of performance I don't think A and B will be very  
different. Only advantage of B is that we can define a notation to  
specify which templating engine to use. Something like:

{{{ velocity|freemarker:
content
}}}

This would be in addition to the macro definition presented by  
Stephane in an earlier message:

{{{macro:mymacro (String parameters)
dothis
dothat
}}}

BTW Stephane/Mikhail, how do you call macros? Do you call them using  
a verbatim block too?

Also is there a generic support in WikiModel for variables? For example:

A list:
* item $myitem

> BTW: I created a very simple common template API which is available  
> in the public Nepomuk repository. There are two implementations for  
> this API: a Velocity and a Freemarker-based on (see Freemarker  
> here: http://freemarker.org/) I think it is easy to implement the  
> same API for StringTemplate (http://www.stringtemplate.org/). It  
> may be useful for the future implementations of the XWiki  
> templating...

Ok good to know in case we need it.

[snip]

Thanks
-Vincent

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.xwiki.org/pipermail/devs/attachments/20070924/113800d3/attachment.html