This page last changed on Dec 02, 2008 by smaddox.
Confluence plugins may define downloadable resources. If your plugin requires Confluence to serve additional static files such as images, Javascript or CSS, you will need to use downloadable plugin resources to make them available.
On this page:
Error formatting macro: toc: java.lang.NullPointerException
Purpose of a Resource
A 'resource' is a non-Java file that a plugin may need in order to operate. Examples of possible resources might be:
- A Velocity file used to generate HTML for a macro or layout plugin module in Confluence.
- A CSS file required by a theme layout plugin module.
- An image referenced from within a layout plugin module.
- A macro help file.
- A localisation property file.
Resource definitions can be either a part of the plugin, or part of a particular plugin module.
Example of a Resource Definition
Here is a sample resource definition:
<resource type="velocity" name="template" location="com/example/plugin/template.vm"/>
<resource type="i18n" name="i18n" location="resources/exampleplugin" />
<resource type="download" name="style.css" location="com/example/plugin/style.css">
<property key="content-type" value="text/css"/>
</resource>
Contents of the Resource Definition
A resource has a name, a type and a location. The resource definition maps an arbitrary resource name to the location of that resource in the server's classpath.
Element |
Attribute |
Description |
<resource> |
|
This block defines the resource. For example: <resource type="velocity" name="template" location="com/example/plugin/template.vm"/> |
<resource> |
name |
The name of the resource defines how the plugin module can locate a particular resource. Must be specified if 'namePattern' is not. |
<resource> |
namePattern |
The pattern to use when loading a directory resource. |
<resource> |
type |
The type of a resource tells the module how that resource can be used. The values allowed are different for each application.
A module can look for resources of a certain type or name. For example, a layout plugin requires that its help file is a file of type velocity and name help.
Refer to the examples of resource types below. |
<resource> |
location |
The location of a resource tells the plugin where the resource can be found in the jar file. (Resources are loaded by Java's classpath resource loader.)
- The full path to the file (without a leading slash) is required.
- Must end in a '/' when using the 'namePattern' attribute to load multiple resources in a directory.
|
<property> |
key/value |
Resources may contain arbitrary key/value pairs. For example: <property key="content-type" value="text/css"/> |
<param> |
name/value |
Resources may contain arbitrary name/value pairs. For example: <param name="content-type" value="image/gif"/>. Refer to the list of values for the param element below |
Example of Resource Type: Downloadable Plugin Resources
The simplest kind of resource, supported with all plugin module types, is of type download, which makes a resource available for download from the application at a particular URL.
<resource type="download" name="aimon.gif" location="templates/extra/impresence/aimon.gif">
<param name="content-type" value="image/gif"/>
</resource>
See Downloadable Plugin Resources.
Values for Param Element
These are the common name/value pairs supported by the <param> element.
Name |
Value (Example) |
Description |
content-type |
image/gif |
Specify a MIME content type. |
media |
print |
Declare the media type for CSS resources. This is supported by Web Resource plugin modules.
For example, requesting this resource will insert a <link> in the HTML header, with a media value of 'print':
<web-resource key="mechanical-parts" name="Mechanical Parts"
i18n-name-key="com.example.confluence.plugin.special.mechanical.parts.name">
<resource type="download" name="sprockets.css" location="styles/sprockets.css">
<param name="media" value="print"/>
</resource>
</web-resource>
|
ieonly |
true |
Specify that the resource should be wrapped in an Internet Explorer conditional comment. This is supported by Web Resource plugin modules.
For example, the web resource declaration below says that the resource should be wrapped in an Internet Explorer conditional comment, which means it will only be used by Internet Explorer. This is useful for IE-specific styling to work around browser bugs.
<web-resource key="mechanical-parts" name="Mechanical Parts"
i18n-name-key="com.example.confluence.plugin.special.mechanical.parts.name">
<resource type="download" name="sprockets-ie.css" location="styles/sprockets.css">
<param name="ieonly" value="true"/>
</resource>
</web-resource>
The HTML output when this resource is included will be something like this:
<!--[if IE]>
<link type="text/css" rel="stylesheet" media="all"
href="/s/1418/13/1.0/_/download/resources/plugin.example:mechanical-parts/sprocket-ie.css" />
<![endif]-->
The ieonly parameter also works for JavaScript resources.
|
title |
(Your title) |
The value given here will form the title attribute of the CSS <link> tag. |
RELATED TOPICS
Writing Confluence Plugins
|