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
