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 Fri, 05 Nov 2004 17:08:36 GMT
Nicola Ken Barozzi wrote:
> Ross Gardler wrote:
>> Nicola Ken Barozzi wrote:
>>> We have now a basic plugin system, but as Ross has shown, it's not 
>>> enough in practice. We have to define the points where the plugins 
>>> can hook into the existing system and extend it.
>>> Before going wild into defining possible scenarios, I have to 
>>> understand better the reason why the current system is not enough and 
>>> where we will need to extend the system.
>>> Do we need plugin dependencies?
>> To date I have not found a compelling reason to allow such things. So 
>> far I have managed to do everything I need to with the values 
>> available from core (i.e. {forrest:*} and {project:*}). My guts tell 
>> me that it will be a necessity one day - but if we can avoid it all 
>> the better.
> I'm thinking of the DocBook plugin and plugins that output the DocBook
> as Sean has shown... so there is a dependency
>   DocBook_outputting_plugin-> Docbook_plugin -> Forrest

Isn't this just a roundabout way of providing a different intermediate 
format? Why do we have to go via the Docbook route? I am not aware of 
any formats that do not provide XHTML stylesheets that do provide 
Docbook ones.

> A solution to this would be Cocoon Blocks, but they would still
> need some sort of automatic resolution for us to be of use.
> --------------------
>  Thinking out loud
> --------------------
> Let's take for example a 'ken' source plugin and file
>   test.ken
> If I ask for
>   ken.html
> the system would give a change to match to all plugins in turn, and not
> matching anything, it would try and ask for:
>   ken.xml
> It asks for it, and the 'ken' plugin, finding the test.ken file would
> match, thus giving us that file in DocumentDTD format.
> But what if the format it gives is not DocumentDTD but DocBook? It
> should match again hoping a plugin can convert it, but it's too late...

In my view, a source plugin *must* provide our intermediate format. If 
we keep it simple like this then we don't have any plugin dependencies 
as everything goes via Forrest core.

That isn't to say that we will always think this way, but right now I 
can't think of a valid use case where this is necessary. As I said 
above, I cannot think of a single format that provides conversion to 
Docbook but not to XHTML. Furthermore, we don't currently need the 
complexity of the Docbook markup since we are only concerned with 


>>> Why is the current system not working?
>> It is, but with hack solutions, see FOR-344 - linked above, and my 
>> proposal below this explanation.
> Ok, cool, let's read :-)
>> The problem with the original implementation was that the plugin 
>> sitemap was being mounted before any matches were made by Forrest, as 
>> a result if a plugin wanted to match all **.xml files it prevented 
>> forrest specialist matchers for things like faq.xml or site.xml.
> 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.

I am assuming that Cocoon can match in this way.

>> The solution was to move the plugin sitemap mount so that it came 
>> after these specialist matcher but before Forrests default **.xml 
>> matcher. This worked fine for the source format plugins, but prevented 
>> the IMSManifest plugin from working since it needs to match the 
>> site.xml and tabs.xml requests. This plugin is an example of an 
>> "infrastructure" plugin.
> The above solution would solve this. Well, you could have prevented this
> probably using a regexp matcher, but it's a hack :-)

Yes, I thought about using a regexp but that would have had to be 
maintained by each individual plugin whenever core added a "reserved" 
filename. I thought about making this a property accessible by all 
plugins but felt it was getting too messy.

>> 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.
>> - 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.
>> 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.
> An alternative would be that plugins define conversion services and that 
> there is a resolution system that pipes one in the other... please stop 
> me! :-D

STOP!! (for now ;-)

>> Remaining problems
>> ------------------

<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.


View raw message