You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by rg...@apache.org on 2006/06/07 13:23:51 UTC
svn commit: r412368 -
/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Author: rgardler
Date: Wed Jun 7 04:23:51 2006
New Revision: 412368
URL: http://svn.apache.org/viewvc?rev=412368&view=rev
Log:
put back warning about the need to restart forrest or locally deploy edited plugins and encourage people to contribute back rather than fork our code.
Modified:
forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml?rev=412368&r1=412367&r2=412368&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml (original)
+++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml Wed Jun 7 04:23:51 2006
@@ -124,22 +124,29 @@
</section>
<section id="local-deploy">
<title>Editing plugins sources to enhance functionality</title>
- <p>If you need to enhance an existing plugin functionality, you should not edit a standard plugin sources.</p>
- <p>First, copy the whole plugin directory either in a plugins directory in your project tree or, if the plugin is used by several projects,
- in a different location outside any project directory.</p>
- <p>Then declare the new location to make Forrest search in it. There is two cases :</p>
- <ul>
- <li>If your plugin is specific to a project, you should edit the corresponding forrest.properties to declare the new location in
- the <code>project.required.plugins.src</code> property</li>
- <li>If your plugin is shared with several project, you should edit your <code>${user.home}/forrest.properties</code></li>
- </ul>
- <warning>The order of the directories list in the property is important, if you keep the plugin name, you should add the new location
- at the beginning of the list to be sure Forrest will use your version and not the standard one.</warning>
- <fixme author="Cyriaque">We still need to describe the declaration of another remote site to store the specific plugins, with a new
- plugins descriptor file...</fixme>
- <p>Finally, you can then edit your copy !</p>
- <p>See <a href="#more">Further reading</a> for "How to build a Plugin".</p>
- </section>
+
+ <note>Until issue <a href="http://issues.apache.org/jira/browse/FOR-388">FOR-388</a> is fixed to
+ enable the use of plugins in-place, any change to sources requires you to either
+ restart forrest or to manually deploy the plugin locally with "ant local-deploy".
+ See Further reading for "How to build a Plugin". It is worth noting that if your
+ changes are to Java files you will always have to restart Forrest to ensure the
+ class loader loads your new classes.</note>
+
+ <p>If you need to add specific behaviour to an existing plugin, you should first consider
+ whether your changes will be of use to all users of the plugin or not. If they are of
+ general use then you can edit the plugin source files in their original location (i.e.
+ not in the build directory). Once you have completed your changes please
+ <a href="http://forrest.apache.org/contrib.html#patch">prepare a patch
+ and submit it for inclusion</a> in code base.</p>
+
+ <p>If your changes are specific to your own use of the plugin you can create a local
+ copy of the plugin for this. However, we strongly advise against this
+ since you will need to manually update your plugin each time a new release of the original
+ is made. In the vast majority of cases local enhancements to a plugin wil be of use
+ to the wider communtiy. Please donate back to the project and help keep it vibrant and
+ useful.</p>
+ </section>
+
<section id="no-plugins">
<title>Upgrading from a Version of Forrest Without Plugins</title>
<p>The plugin functionality was introduced in version 0.7 of Forrest.
Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Posted by Ross Gardler <rg...@apache.org>.
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 ?
...
> With respect to adding the location of the plugins to the users
> forrest.properties file I initially thought this a bad idea. However, in
> trying to explain my reasoning in this reply I realised I had
> misunderstood the point you were making. You are right to put this
> information in a user doc. I'll correct that in a few minutes.
Actually this is already in the docs - see section on "Where does
Forrest look for Plugins sources ?"
Ross
Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Posted by Cyriaque Dupoirieux <Cy...@pcotech.fr>.
le 07/06/2006 14:29 Ross Gardler a écrit :
> Cyriaque Dupoirieux wrote:
>> le 07/06/2006 13:23 rgardler@apache.org a écrit :
>>
> ...
> With respect to adding the location of the plugins to the users
> forrest.properties file I initially thought this a bad idea. However,
> in trying to explain my reasoning in this reply I realised I had
> misunderstood the point you were making. You are right to put this
> information in a user doc. I'll correct that in a few minutes.
>
> Is this OK?
Yes,
Cyriaque,
>
> Ross
>
>
>
Re: Customising plugins (Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml)
Posted by Ross Gardler <rg...@apache.org>.
Ross Gardler wrote:
> Johannes Schaefer wrote:
>
>> Ross Gardler wrote:
...
> 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>
It's also worth noting that if you add a <select> tag around the
<location> tag then processing will fall back to the standard plugin
provided resources if no suitable project resource is provided.
Ross
> [1] http://forrest.apache.org/docs_0_80/locationmap.html#namingConvention
>
> [2] http://issues.apache.org/jira/browse/FOR-588
Customising plugins (Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml)
Posted by Ross Gardler <rg...@apache.org>.
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
Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Posted by Johannes Schaefer <jo...@uidesign.de>.
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 ;-)
Johannes
> I'm -1 on appearing to encourage
> users (and this is a user doc) to fork our code.
>
> The idea of adding a plugin to a project directory also smells of bad
> practice to me. One of the goals of Forrest is to separate the concerns
> of the content designer, the content publisher and the developer. A
> plugin has, IMHO, no place inside the content. Therefore, all plugins
> should be in an external directory. Regardless, this discussion has no
> place in a users document, but should be in the developers
> documentation, so I stripped it and intend to add it to the developer docs.
>
> With respect to adding the location of the plugins to the users
> forrest.properties file I initially thought this a bad idea. However, in
> trying to explain my reasoning in this reply I realised I had
> misunderstood the point you were making. You are right to put this
> information in a user doc. I'll correct that in a few minutes.
>
> Is this OK?
>
> Ross
>
>
>
--
User Interface Design GmbH
Teinacher Str. 38, 71634 Ludwigsburg
Fon: +49-7141-37700-0
Fax: +49-7141-37700-99
Email: jschaefer@uidesign.de
Internet: www.uidesign.de
Geschäftsstellen:
Teinacher Str. 38, 71634 Ludwigsburg
Truderinger Str. 330, 81825 München
Friedrichsring 46, 68161 Mannheim
Buch "User Interface Tuning" von Joachim Machate & Michael Burmester
www.user-interface-tuning.de
Attraktivität von interaktiven Produkten messen mit
www.attrakdiff.de
Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Posted by Ross Gardler <rg...@apache.org>.
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'm -1 on appearing to encourage
users (and this is a user doc) to fork our code.
The idea of adding a plugin to a project directory also smells of bad
practice to me. One of the goals of Forrest is to separate the concerns
of the content designer, the content publisher and the developer. A
plugin has, IMHO, no place inside the content. Therefore, all plugins
should be in an external directory. Regardless, this discussion has no
place in a users document, but should be in the developers
documentation, so I stripped it and intend to add it to the developer docs.
With respect to adding the location of the plugins to the users
forrest.properties file I initially thought this a bad idea. However, in
trying to explain my reasoning in this reply I realised I had
misunderstood the point you were making. You are right to put this
information in a user doc. I'll correct that in a few minutes.
Is this OK?
Ross
Re: svn commit: r412368 - /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Posted by Cyriaque Dupoirieux <Cy...@pcotech.fr>.
le 07/06/2006 13:23 rgardler@apache.org a écrit :
> Author: rgardler
> Date: Wed Jun 7 04:23:51 2006
> New Revision: 412368
>
> URL: http://svn.apache.org/viewvc?rev=412368&view=rev
> Log:
> put back warning about the need to restart forrest or locally deploy edited plugins and encourage people to contribute back rather than fork our code.
>
> Modified:
> forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
>
> Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
> URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml?rev=412368&r1=412367&r2=412368&view=diff
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml (original)
> +++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml Wed Jun 7 04:23:51 2006
> @@ -124,22 +124,29 @@
> </section>
> <section id="local-deploy">
> <title>Editing plugins sources to enhance functionality</title>
> - <p>If you need to enhance an existing plugin functionality, you should not edit a standard plugin sources.</p>
> - <p>First, copy the whole plugin directory either in a plugins directory in your project tree or, if the plugin is used by several projects,
> - in a different location outside any project directory.</p>
> - <p>Then declare the new location to make Forrest search in it. There is two cases :</p>
> - <ul>
> - <li>If your plugin is specific to a project, you should edit the corresponding forrest.properties to declare the new location in
> - the <code>project.required.plugins.src</code> property</li>
> - <li>If your plugin is shared with several project, you should edit your <code>${user.home}/forrest.properties</code></li>
> - </ul>
> - <warning>The order of the directories list in the property is important, if you keep the plugin name, you should add the new location
> - at the beginning of the list to be sure Forrest will use your version and not the standard one.</warning>
> - <fixme author="Cyriaque">We still need to describe the declaration of another remote site to store the specific plugins, with a new
> - plugins descriptor file...</fixme>
> - <p>Finally, you can then edit your copy !</p>
> - <p>See <a href="#more">Further reading</a> for "How to build a Plugin".</p>
> - </section>
> +
> + <note>Until issue <a href="http://issues.apache.org/jira/browse/FOR-388">FOR-388</a> is fixed to
> + enable the use of plugins in-place, any change to sources requires you to either
> + restart forrest or to manually deploy the plugin locally with "ant local-deploy".
> + See Further reading for "How to build a Plugin". It is worth noting that if your
> + changes are to Java files you will always have to restart Forrest to ensure the
> + class loader loads your new classes.</note>
> +
> + <p>If you need to add specific behaviour to an existing plugin, you should first consider
> + whether your changes will be of use to all users of the plugin or not. If they are of
> + general use then you can edit the plugin source files in their original location (i.e.
> + not in the build directory). Once you have completed your changes please
> + <a href="http://forrest.apache.org/contrib.html#patch">prepare a patch
> + and submit it for inclusion</a> in code base.</p>
> +
> + <p>If your changes are specific to your own use of the plugin you can create a local
> + copy of the plugin for this. However, we strongly advise against this
> + since you will need to manually update your plugin each time a new release of the original
> + is made. In the vast majority of cases local enhancements to a plugin wil be of use
> + to the wider communtiy. Please donate back to the project and help keep it vibrant and
> + useful.</p>
> + </section>
> +
>
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 ?
Cyriaque,
> <section id="no-plugins">
> <title>Upgrading from a Version of Forrest Without Plugins</title>
> <p>The plugin functionality was introduced in version 0.7 of Forrest.
>
>
>
>