forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: [RT] plugin infrastructure
Date Mon, 08 Nov 2004 15:38:20 GMT
Nicola Ken Barozzi wrote:
> Ross Gardler wrote:
>> Nicola Ken Barozzi wrote:

<snip what="we don't need plugin dependencies (yet?)"/>

>>> faq should start using the content aware pipelines, and this is solved.
>> +1 this can be done when the faq stuff is moved to a plugin.
> ...
>>> For other special *internal* parts we should probably not use name for
>>> matching but maybe a parameter.
>>>   *?forrest-part=site.xml
>> +1, this could facilitate the generation of different Forrest parts 
>> for different pages. There is no forrest-part at present that needs 
>> this, but some time ago there was an RT about have Forrest provide 
>> additional parts, for example, a news panel. These parts can be 
>> provided by infrastructure plugins and using the above match we can 
>> customise on a per page basis. For example, 
>> "index.html?forrest-part=news.xml" would return news about project 
>> releases whilst "developers/index.html?forrest-part=news.xml" would 
>> provide recent changes.
> Hand on a second, let's go deeper in this.
> I see three issues:
> 1 - the page is the context, the part is the data:
>     forrest-part should show some extra data as it has to be shown
>     on the page being rendered.
>     forrest-part=tabs.xml would show the tabs with the selected one
>                           specified
>     forrest-part=site.xml would show the site with the selected one
>                           specified
>     ...etc
> 2 - the page is the data, and we specify a view
>     for each page we may have different representations of it:
>          -> MyClass.html  javadocs
>          -> MyClass.html  UML graph
>          -> MyClass.html  highlighted source code
>          -> MyClass.html  checkstyle result
>     How do we differentiate them? Not with parameters, as it has to
>     remain in a name.
>     Proposal:
>          -> MyClass-javadocs.html   javadocs
>          -> MyClass-uml.html        UML graph
>          -> MyClass-source.html     highlighted source code
>          -> MyClass-checkstyle.html checkstyle result

I already came across this very issue in the s5 (slides) plugin and the 
(soon to be announced) WYSIWYG editor plugin.

My current solution has been to encode it in the URL, i.e. 
slides/index.html gives the slides, index.html gives the default HTML 
output. The problem with this solution, is that it causes some 
complications with relative linking from one type of document to the 
other (i.e. slides to normal HTML) and it reserves some patterns in the 
URL space.

Your proposal solves both these problems, but introduces another:

>      Problem: How do we define the "default" view, which is
>               MyClass.html?

Here's a partial solution, but it doesn't quite work, maybe it will fire 
an idea:

Each plugin that wants to do so defines a default behaviour:

<map:match pattern="**.html">
   <map:redirect src="cocoon://{1}-javadocs.html"/>

(yeah, I know the above rewrtie rule doesn't work, we need a "not 
**-*.html" in the first part, but I can't think about regexps this 
morning, not my strongpoint, and I'm sure you get the point)

The user then has control over which one takes precedence because they 
can control the order in which sitemaps are processed through the 
project.required.plugins property (see below).

Problem: the above will match all requests for an HTML document and 
redirect it, even ones that are not Java related.

> 3 - extra data to be put on a page
>      Since we have to aggregate, we need to specify a new section
>      for information nuggets. This is to make all skins able to render
>      them.
>      The question is: how to add things to the nugget section?
>      Seems like the last point of this mail is getting more
>      important :-)

This is more a problem of for skins than plugins. If we can solve the 
matching problem above, and the skins can give us a way to hook into 
them we have this solution.

I think this last one is probably going a step too far at this stage. 
Maybe we should put it on the back-burner for now - the solution may 
turn out to be creating a portal plugin from the Cocoon Portal 
Framework. (now it's time for someone to stop me!)

> ...
>>>> My Proposal
>>>> ===========
>>>> Each plugin should be able to provide three sitemaps rather than the 
>>>> current 1.
>>>> - sitemap.xmap - this provides the infrastructure matchers (i.e. 
>>>> site.xml, faq.xml, issues.xml), as such it will be mounted before 
>>>> *any* of the Forrest matches. This sitemap can override any 
>>>> behaviour within Forrest)
>>>> - source.xmap - this provides the source matchers (i.e. **.xml), it 
>>>> is mounted in forrest.xmap before the default forrest **.xml 
>>>> behaviour and therefore can override that default behaviour but it 
>>>> will not interfere with any internal Forrest infrastructure matches, 
>>>> or any other plugins infrastructure matches.

This should be named input.xmap as Clay points out in a later mail in 
this thread.

>>>> - output.xmap - this provides (surprise!) the output matchers (i.e. 
>>>> **.html, **.pdf, **.slides), it is mounted before any of the default 
>>>> matchers for Forrest and so can override this default behaviour
>>>> Ideally, each plugin should only provide one of these three 
>>>> sitemaps. I believe this will help us to define a sensible 
>>>> granularity for the plugins. However, further exploration of use 
>>>> cases may show otherwise and therefore we should make it legal (but 
>>>> not encouraged) to implement more than one of them.
>>> I tend to like the concept, even if it may not result to be technically
>>> needed. Just thinking out loud.

As Nicola says in a later mail in this thread:

"When Dave has asked to rename the last plugin to show that it's an 
output plugin, alarm bells started ringing in my head. I had not 
pondered it enough, and the separation that was hinted became clearly 

IOW, I now understand what probably has been plain obvious to all others 
:-) : we *must* have each plugin use only one of the following sitemaps."

I agree. Nicola went on to say:

This gives us the problem of libraries and components in each plugin, as 
more plugins can need the same jars or cocoon xconf extensions.

The RTF plugin demonstrates the jars problem. The first incarnation of 
this plugin requires the user to copy the files into the 
forrest/webapp/WEB-INF/lib directory. Of course, this needs to be automated.

I see two possible solutions:

- plugins provide a build.xml file that will configure the local version 
of forrest (copy jars, use XSLT to configure cocoon.xconf etc.) The 
problem with this is there is a potential for clashes between 
incompatible jar files (implement a version management system?), in 
addition the number of jars in the classpath will grow whenever a plugin 
is loaded, but they will not always be used. Perhaps even more of a 
problem is that changes to the cocoon.xconf will be permanent and will 
be changing the file in Forrest itself.

-  We could make the forrest scripts handle this configuration, as it 
handles the configuration of the plugin sitemap.xmap now. That is, each 
time we run forrest we configure cocoon.xconf accordingly. This will 
require cocoon.xconf to be renamed something like 
"cocoon.xconf.default", this is then processed by XSLT when Forrest is 
run to create cocoon.xconf for that run (cocoon.xconf would then be 
added to svn:ignore). With respect to the jar files we could build the 
classpath to include the relevant plugin/WEB-INF/lib and 
plugin/WEB-INF/class folders.

>>>> Avoiding Plugin Conflicts
>>>> -------------------------
>>>> Clashes between plugins can occur. For example, the 
>>>> simplified-docbook and full docbook plugins may try and process the 
>>>> same files. In this instance the one that is mounted first will take 
>>>> precedence. Plugins are mounted in the order they appear in the 
>>>> project.required.plugins property, therefore the mounting order and 
>>>> therefore processing precedence is under user control.
>>> +1
>>> Easy, simple, effective.
> ...
>> <snip what="stuff we agree can wait"/>
>>>> - Plugin resources are 
>>>> not copied to site - in order to fix this problem I believe each 
>>>> plugin should implement a site-build.xml file that provides a target 
>>>> for copying any required resources into the built site. This is not 
>>>> necessary when running dynamically.
>>> Well, this is another RT altogether, about how to generate a site 
>>> with non-linked resources.
>> Actually, one of my plugins needs this now (the slideshow plugin) as 
>> will the WYSIWYG editor I started last week (but have not had the time 
>> to finish). I'm happy to implement the build file solution above. This 
>> does not break the copyless behaviour since the plugin deals with the 
>> matching, it is only in statically built sites that we need to do this.
>> Hmmmm. if the plugin creates the right matches during a live run why 
>> doesn't cocoon copy the files when generating statically? The files 
>> are linked through <link...> elements in the head.
> Err, then it's something that needs fixing, if it's linked it should 
> pick it up.

There is a bug report at


View raw message