forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Modifying plugin
Date Tue, 07 Mar 2006 09:08:23 GMT
Paul Bolger wrote:
> I've been building a site with the Dispatcher, using the Open Office
> plugin to translate documents to Forrest internal document format. I
> found that I had to make a couple of minor modifications to the plugin
> - turned off the warning that the heading hierarchy is wrong (the
> documents are supplied by others and I'm doing this to save myself
> time - I can try and convince the clients that the documents will look
> better if they structure them correctly, but I'm not going to fix
> their mistakes for them.) I also turned off the class which puts an
> arrow graphic at the start of each line, for some reason the plugin
> thinks every line deserves an arrow...
> Anyhow, to prevent my modifications from being overwritten by
> Subversion I copied the plugin, renamed the copy, searched the new
> directories for any mention of the old plugin name, and then changed
> forrest.properties to the new plugin name. Works fine.
> My question is: is there a less clunky way of modifying a plugin, or
> is what I did the best way?

You have two options right now, create a new plugin as you have done or 
parameterise the existing plugin behaviour. The best way to do it would 
be to parameterise the things you think need to change and commit the 
changes back to Forrest. My reasoning is that since you need it to work 
one way, and someone else needs it to work another way we need this to 
be an option.

We are working on a kind of "plugin inheritance", but this is not 
operational right now. We need to resolve a couple of issues with 
resolving resources via the locationmap first.

However, looking at your comments some of your changes may be better 
made in the core without parameterisation, and you are doing the right 
thing by asking about them here.

Firstly, the warning about heading hierarchy. This warning is there for 
a reason, in some cases information may be lost if the hierarchy is not 
correct. You need to be very careful if turning it off. However, your 
point is valid and this should really be parameterised, more on this below.

Your point about an "arrow graphic" confuses me. I have never seen this, 
so it is a specific use in your case. Certainly, the samples, such as 
[1], do not exhibit this behaviour. It would be best for us to figure 
out why this is happening and improve the stylesheets to prevent it 
happening when not expected, as in your case. Can you post the code 
snippet you needed to change for this.

Now, back to parameterisation.

In 0.7 it is not easy to parameterise plugins. It is possible, but 
complex and requires modifications to core, which is obviously not a 
good thing for a plugin to do. In 0.8-dev though it is much easier.

Basically, you create a default.plugin.properties.xml file in the root 
of the plugin directory and add any properties you need. In this case we 
want a property to define if we are to allow incorrect heading 
hierarchies. SO our default.properties.xml plugin would look like 
something like this:

<?xml version="1.0" encoding="UTF-8"?>
<properties>
    <!-- OpenOffice plugin properties -->

    <!-- OpenOffice documents can be created with poorly structured 
heading hierarchies. This is bad practice and can result in unintended 
visual effects when rendering in other formats. Set this property to 
true if you would like the plugin to insert a warning in such documents. -->

    <property name="OOo.headingsHierarchy.warning" value="true"/>

</properties>

Now we need to pass this parameter into the stylesheets so that they can 
be modified to behave as required. This requires a modification to the 
input.xmap, for example:

add
   <map:parameter name="warnHeadingHierarchies" 
value="{project:OOo.headingHierarchy.warning}" />

to the sx* transformations, i.e.:

         <map:when test="{lm:project.{uri}.sxw}">
           <map:match type="regexp" pattern="^(.*?)([^/]*).xml$">
             <!-- FIXME: use the OOo generator as seen in the resume 
plugin -->
             <map:generate src="{lm:OOo.bootstrap}"/>
             <map:transform 
src="{lm:OOo.transform.xsl.aggregates/openoffice-document}">
               <map:parameter name="src" value="{lm:project.{1}{2}.sxw}"/>
             </map:transform>
             <map:transform type="cinclude"/>
             <map:transform 
src="{lm:OOo.transform.openoffice-writer.forrest}">
               <map:parameter name="filename" value="{2}" />
               <map:parameter name="extension" value="sxw" />
               <map:parameter name="warnHeadingHierarchies" 
value="{project:OOo.headingHierarchy.warning}" />
             </map:transform>
             <map:serialize type="xml-document"/>
           </map:match>
         </map:when>

Finally we need to make the XSL behave differently according to this 
parameter:

<xsl:param name="warnHeadingHierarchies"/>

...

<xsl:if test="warnHeadingHierarchies='true'">
   <!-- add the warning -->
</xsl:if>

Now, if the user wants to change this behaviour all they need to do is 
override the value of OOo.headingsHierarchy.warning in 
forrest.properties.xml in their project root.

It is also possible for individual users to change the value of this 
using local.forrest.properties.xml.

---

It would be great if you could provide a patch or this. The advantage is 
that you will not have to keep your OOo plugin in synch with the one we 
release and, of course, we all get the benefit of your work.

Ross

[1] 
http://forrest.apache.org/pluginDocs/plugins_0_70/org.apache.forrest.plugin.input.OpenOffice.org/samples/openoffice-writer.html

Mime
View raw message