Downloadable plugin resources

Jira plugins may define downloadable resources. If your plugin requires Jira to serve additional static files such as images, JavaScript or CSS, you will need to use downloadable plugin resources to make them available.

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:

1
2
<!-- A resource has a type, a name and a location. The resource definition maps -->
<!-- some arbitrary resource name to where that resource would be located in    -->
<!-- the server's classpath -->
<resource type="velocity" name="template" location="com/example/plugin/template.vm"/>

<!-- For the localisation property file below, it must be named exampleplugin.properties -->
<!-- located under the resources folder -->
<resource type="i18n" name="i18n" location="exampleplugin" />

<!-- Resources may contain arbitrary key/value pairs -->
<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.

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.

1
2
<resource type="download" name="aimon.gif" location="templates/extra/impresence/aimon.gif">
   <param name="content-type" value="image/gif"/>
</resource>

Example of Resource Type: Stylesheet referring to Images

Stylesheets for your plugin may often refer to images also in your plugin. In which case you would have to make both the stylesheet and image(s) downloadable.

1
2
<resource type="download" name="my-images/" location="com/example/plugin/myimages"/>
<resource type="download" name="my-style.css" location="com/example/plugin/my-style.css"/>

Note: If you have multiple stylesheets and javascript resources defined, you should put the resource defintions in a Web Resource Module.

To refer to your plugin images in a stylesheet, use a relative path based on the resource name defined for the image (which is 'my-images' in this case).

my-style.css

1
2
 .my-class {
   background-image: url(my-images/mypicture.gif);
}

To reference images already available in an application, you will need to go up three parent directories like so:

1
2
.my-class {
   background-image: url(../../../images/icons/confluence-logo.gif);
}

Values for Param Element

These are the common name/value pairs supported by the <param> element.

Name & Value: content-type | image/gif

Description: Specify a MIME content type. 

---

Name & Value: media | print

Description: 

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': 

1
2
<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>

Name & Value: allow-public-use | true

Description: 

Declare that the resource can be used publicly, the default value is false. Sets the Access-Control-Allow-Origin header to '*'. It's always needed when accessing fonts resources through CDN and may be needed on other resources when your plugin accesses them in a non-standard way.

1
2
<web-resource key="mechanical-parts-font" name="Mechanical Parts Font"
    i18n-name-key="com.example.confluence.plugin.special.mechanical.parts.font.name">
    <resource type="download" name="font.woff" location="fonts/sprockets.woff">
        <param name="allow-public-use" value="true"/>
    </resource>
</web-resource>

Name & Value: ieonly | true 

Description: 

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. 

1
2
<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: 

1
2
<!--[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. 

---

Name & Value: conditionalComment | lt IE 9 

Description:  

Specify that the resource should be wrapped in an Internet Explorer conditional comment, and should be used when targeting specific versions of Internet Explorer. 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 versions of Internet Explorer less than 9. This is useful for IE version-specific styling to work around browser bugs. 

1
2
<web-resource key="mechanical-parts" name="Mechanical Parts"
    i18n-name-key="com.example.confluence.plugin.special.mechanical.parts.name">
    <resource type="download" name="sprockets-lt-ie9.css" location="styles/sprockets-lt-ie9.css">
        <param name="conditionalComment" value="lt IE 9"/>
    </resource>
</web-resource>

The HTML output when this resource is included will be something like this: 

1
2
<!--[if lt IE 9]>
<link type="text/css" rel="stylesheet" media="all"
    href="/s/1418/13/1.0/_/download/resources/plugin.example:mechanical-parts/sprocket-lt-ie9.css" />
<![endif]-->

The conditionalComment parameter also works for JavaScript resources. 

---

Name & Value (Example): title | (Your title) 

Description: The value given here will form the title attribute of the CSS <link> tag.