This page last changed on Jan 19, 2006 by jnolen.
Confluence plugins may define downloadable resources. If your plugin requires Confluence serve additional static files such as images, Javascript or CSS, you will need to use downloadable plugin resources to make them available.
 | Due to a bug in Confluence versions 1.4 through 1.4.2, downloadable plugin resources only function for plugins that have been deployed by copying them into confluence/WEB-INF/lib. Plugins that have been uploaded dynamically through the web interface, or copied into confluence.home/plugins will not be able to serve resources. This bug is fixed for Confluence 1.4.3. |
Defining a Single Downloadable Resource
Downloadable resources are configured to map a name of some downloadable file to its location within the plugin jar-file.
<atlassian-plugin name='IM Presence Macros' key='confluence.extra.impresence'>
<plugin-info>
<description>Macros to show online status for popular Instant Messaging services.</description>
<vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
<version>0.1</version>
</plugin-info>
<macro name='aim' class='com.atlassian.confluence.extra.impresence.AIMPresenceMacro' key='aim'>
<description>Displays an AIM status graphic.</description>
<resource type="download" name="aimon.gif" location="templates/extra/impresence/aimon.gif">
<param name="content-type" value="image/gif"/>
</resource>
</macro>
<resource type="download" name="aimoff.gif" location="templates/extra/impresence/aimoff.gif"/>
</atlassian-plugin>
- Resources can be downloaded either within a plugin module, or as a resource of the entire plugin.
- Resources are always looked up relative to a plugin module (see below). If a resource can not be found in the plugin module, it will then be looked for in the plugin itself.
- Each resource must be of type="download"
- The name of the resource is how it will be referenced from within the application
- The location of the resource is where it appears within the plugin itself
- An optional content-type parameter can be used to supply the file's MIME type
- In the absence of a content-type, the application will attempt to guess the file's type from its file extension. For common file extensions, an explicit content-type is not necessary.
Defining a Directory of Downloadable Resources
If your plugin requires a lot of resources, you may wish to expose a directory of files as resources, rather than writing definitions for each individual file.
<resource type="download" name="icons/" location="templates/extra/impresence/icons/"/>
- The name and location must both have trailing slashes
- Subdirectories are also exposed, so in the example above, icons/small/mail.gif will be mapped to the resource templates/extra/impresence/icons/small/mail.gif
Referring to Downloadble Resources
The URL for a downloadable resource is as follows:
{server root}/download/resources/{plugin key}:{module key}/{resource name}
For example:
http://confluence.example.com/download/resources/confluence.extra.impresence:aim/aimon.gif
In a velocity template, you should use the $req.contextPath property to ensure that your resources are always relative to the URL of the Confluence server:
$req.contextPath/download/resources/confluence.extra.impresence:aim/aimon.gif
So how do you access the plugin resource?
<resource type="download" name="aimoff.gif" location="templates/extra/impresence/aimoff.gif"/>
$req.contextPath/download/resources/confluence.extra.impresence:???/aimon.gif
http://confluence.example.com/download/resources/confluence.extra.impresence/aimoff.gif won't work. You need to specify a module key, but one doesn't exist in the definition.
caused by: java.lang.IllegalArgumentException: Invalid complete key specified: confluence.extra.impresence
at com.atlassian.plugin.ModuleCompleteKey.(ModuleCompleteKey.java:22)

Posted by jclark42796 at Nov 17, 2006 13:55
|
Unfortunately, you can't. Having looked at the code, I'm not sure why they chose to have this restriction, since there isn't any technical problem with it I could detect.
However, the thing is, even though the resource is not bound to a specific module, you can actually use any module in your plugin, be it a <macro>, <theme> or whatever... I usually just use the module for whatever piece of functionality which is using it at the time, and if there isn't a specific one, I pick one at random.

Posted by david@randombits.org at Nov 17, 2006 18:00
|
I see now, this seems to work
http://confluence.example.com/download/resources/confluence.extra.impresence:aim/aimoff.gif
Thanks for the help!
Jim

Posted by jclark42796 at Nov 21, 2006 13:43
|
|