forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Customising plugins (Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml)
Date Wed, 07 Jun 2006 15:34:41 GMT
Johannes Schaefer wrote:
> Ross Gardler wrote:
> 
>>Cyriaque Dupoirieux wrote:
>>
>>>le 07/06/2006 13:23 rgardler@apache.org a écrit :
>>>
>>
>>...
>>
>>
>>>Ok, You have totally removed the previous text, but I think
>>>information were useful - declaration of the location of the new copy,
>>>share between several projects, order of the declaration.
>>>Can't we merge both versions ?
>>
>>You beat me to it. I was going to mail on this subject...
>>
>>When I came to do the merge I thought better of it. The main problem I
>>have is with the fact that copying a plugin, as you suggested, results
>>in a conflict of plugin names. This is in contradiction of the naming
>>convention which requires a world unique name.
>>
>>I tried to think of a use case where such a forking would be necessary.
>>I couldn't think of any. Either the use case is sufficiently different
>>that it warrants a new plugin. Or it is sufficiently similar that it
>>should be added to the existing plugin. 
> 
> 
> I recently used the photo-gallery plugin.
> I had support PNG (sufficiently similar to be added to the plugin).
> I also changed the appearance of the filename "buttons":
>   they were generated with svg and our long filenames didn't fit.
>   This is a matter of taste ...
>   How would I adapt this?
>   It's not sufficiently different and yet a "matter of taste" how to
>   display the file name (I know your answer: make it configurable ;-)

Good question.

Here is what I hope is a good answer - although I confess I am bouncing 
ideas. My comments above are "perfect world" comments but we may find my 
ideas for solutions aren't quite perfect.

It's also worth noting that I'm not writing these options directly with 
respect to your use case. To make one or more of them work in the 
PhotoGallery plugin may require a little extra work in the plugin code.

Configurable behaviour
----------------------

Make the behaviour configurable using forrest.properties.xml

WARNING: This new property definition method is not officially part of 
Forrest, so use this technique at your own risk. However, it is used 
within a number of plugins at allready and appears to be a far superior 
configuration system than the current "official" method.

forrest.properties.xml allows you to expose configuration options for a 
plugin in the forrest configuration files. Plugins can provide default 
settings for each property, then projects, users or even site 
customisations can be provided. It is used extensively in the Daisy plugin.

It is largely undocumented at present, but there are plenty of notes in 
the issue tracker [1]

Resource Overriding
-------------------

If you simply want to replace a resource provided by the plugin, for 
example, substitute your own images for those supplied by the plugin you 
  should be able to use the locationmap.

A correctly designed plugin will resolve all resources via the 
locationmap. Furthermore it will conform to the naming convention 
defined for locationmaps [2]

A well documented plugin will clearly identify what resources it exposes 
via its locationmap.

Taking these two things into account we can replace any resource by 
simply adding a match to our project locationamp for the relevant item. 
For example, if a pluiging provides a set of button images that are 
exposed in the locationmap as "fooPlugin.button.bar.gif" we can add a 
match like this:

<match src="fooPlugin.button.**">
   <location src="{project.home}/xdocs/images/buttons/{1}"/>
</match>

Ross

[1] http://forrest.apache.org/docs_0_80/locationmap.html#namingConvention

[2] http://issues.apache.org/jira/browse/FOR-588








Mime
View raw message