Web resource

JIRA plugins may define downloadable resources. If your plugin requires JIRA to serve additional static Javascript or CSS files, you will need to use downloadable web resources to make them available. Web resources differ from Downloadable Plugin Resources in that web resources are added at the top of the page in the header.

Purpose of this Module Type

Web Resource plugin modules allow plugins to define downloadable resources. If your plugin requires the application to serve additional static Javascript or CSS files, you will need to use downloadable web resources to make them available. Web resources are added at the top of the page in the header with the cache-related headers set to never expire. In addition, you can specify web resources like CSS and JavaScript to be included in specific contexts within the application.

Configuration

The root element for the Web Resource plugin module is web-resource. It allows the following attributes and child elements for configuration:

Attributes

1
2
<component-import key="appProps"
interface="com.atlassian.sal.api.ApplicationProperties"/>

*key attribute is required

Elements

1
2
<transformation extension="txt">
<transformer key="template" />
</transformation>

*resource element is required

Example

Here is an example atlassian-plugin.xml file containing a single web resource:

1
2
<atlassian-plugin name="Hello World Resource" key="example.plugin.helloworld" plugins-version="2">
    <plugin-info>
        <description>A basic web resource module test</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <web-resource key="scriptaculous" name="Scriptaculous" >
        <resource type="download" name="scriptaculous.js" location="includes/js/effects/scriptaculous.js" />
        <resource type="download" name="effects.js" location="includes/js/effects/effects.js" />
    </web-resource>
</atlassian-plugin>

Referring to Web Resources

In your plugin, you need to refer to a PageBuilderService and call the requireResource() method. A reference to a PageBuilderService can be injected into your constructor:

1
2
public MyServlet extends HttpServlet
{
    private PageBuilderService pageBuilderService;

    public MyServlet(PageBuilderService pageBuilderService)
    {
        this.pageBuilderService = pageBuilderService;
    }

    protected final void doGet(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) throws IOException
    {
        //should be the full module key for the <webreference> module.
        pageBuilderService.assembler().resources().requireWebResource("example.plugin.helloworld:scriptaculous");
        // more code
    }
}

Web Resource Contexts

In version 2.5 and later of the Plugin Framework, you can automatically include web resources like CSS and JavaScript on all screens of a specific type in the application. These are called 'web resource contexts'. The currently available contexts are:

The above contexts are applicable to all Atlassian applications. In addition to these application-independent contexts, each Atlassian application can also supply its own application-specific contexts.

Example: To configure your web resource to be included in every page (both administration and non-administration pages), add <context> child elements to your <web-resource> element in your atlassian-plugin.xml:

1
2
<web-resource name="Resources" key="resources">
       <resource name="foo.js" type="download" location="resources/foo.js"/>
       <context>atl.general</context>
</web-resource>

Using web resource contexts allows you to provide plugins that dynamically create HTML using JavaScript on any page in the application. For example, the Confluence Content Navigation Plugin includes a snippet of JavaScript on every page in the application, which listens for a particular keyboard shortcut to open a little search box on top the Confluence UI.

Introducing new contexts

If your plugin adds a number of screens to the application, you may find it useful to introduce a new web resource context for your plugin that your plugin web resources (or any other plugin web resource) can hook into, to be automatically included on these screens.

To introduce a new context in your plugin Velocity templates, you can call the requireResourcesForContext() method on the WebResourceManager object from your Velocity templates:

1
2
$webResourceManager.requireResourcesForContext("com.acme.plugin.fancy-context")

This will include any resource in the page that specifies a context like this in its definition: <context>com.acme.plugin.fancy-context</context>.

We recommend that you namespace your new contexts in this way so as not to clash with any future contexts in the applications themselves or in other plugins.

Batched Mode

The default mode for serving web resources in Plugin Framework 2.2 is batched mode. Batched mode refers to the serving of multiple plugin resources (of the same type) in one request. For example, the two scriptaculous web resources defined above would be served in one request, containing both scriptaculous.js and effects.js. Hence, batching reduces the number of HTTP requests that web browsers need to make to load a web page.

URLs for batched resources are in the following format:

1
2
SERVER_ROOT/s/BUILD_NUM/PLUGIN_VERSION/SYSTEM_COUNTER/_/download/batch/js/PLUGIN_KEY:MODULE_KEY/BATCHNAME.js
SERVER_ROOT/s/BUILD_NUM/PLUGIN_VERSION/SYSTEM_COUNTER/_/download/batch/css/PLUGIN_KEY:MODULE_KEY/BATCHNAME.css

For the above scriptaculous example, the following code will be inserted in the header of the page:

1
2
<script type="text/javascript"
  src="http://jira.example.com/s/170/1.0/1/_/download/batch/js/jira.extra.impresence:scriptaculous/jira.extra.impresence:scriptaculous.js"></script>

Transforming Web Resources

!!! Transformers are only available in Plugin Framework 2.5 and later.

The plugin framework provides web resource transformers that you can use to manipulate static web resources before they are batched and delivered to the browser.

To use a web resource transformer, you need the following elements in your atlassian-plugin.xml file:

• The transformer module: A <web-resource-transformer> element, defining the transformer plugin module. This module can be in the same plugin as the web resource, or in a different plugin.
• Transformation elements in the web resource module: A <transformation> element and its child <transformer> element inside the <web-resource> block, making a particular transformer available to the web resource in the plugin.

For a complete description and example, please refer to the page on Web Resource Transformer plugin modules.

Notes

• Since the resources are returned with headers that tell the browser to cache the content indefinitely, during development, you may need to hold down the "shift" key while reloading the page to force the browser to re-request the files.

Use this element to make a particular transformer available to the web resource in the plugin. Example:

Web Resource Contexts in JIRA

You can automatically include web resources like CSS and JavaScript on all screens of a specific type in the application. These are called 'web resource contexts'. Above we described the generic contexts supplied by the Atlassian Plugin Framework for use across all Atlassian applications.

In addition to the generic contexts described above, JIRA provides the following JIRA-specific contexts:

Example: To configure your web resource to be included on the JIRA user profile page and View Issue page, add <context> child elements to the <web-resource> element in your atlassian-plugin.xml:

1
2
<web-resource name="Resources" key="resources">
        <resource name="foo.js" type="download" location="resources/foo.js">
        </resource>
        <context>jira.userprofile</context>
        <context>jira.view.issue</context>
</web-resource>

Introducing New Contexts in JIRA

If your plugin adds a number of screens to JIRA, it might be annoying to put many #requireResource() declarations in each Velocity template. An alternative is to introduce a new web resource context for your plugin which your plugin web resources (or any other plugin web resource) can hook into, to be automatically included on these screens.

To introduce a new context in your plugin Velocity templates, you can call the #requireResourcesForContext() Velocity macro:

1
2
#requireResourcesForContext("com.acme.plugin.fancy-context")

This will include any resource in the page that specifies a context like this in its definition: <context>com.acme.plugin.fancy-context</context>.

We recommend that you namespace your new contexts in this way so as not to clash with any future contexts in JIRA or other plugins.

RELATED TOPICS

About JIRA Plugin Development.

For more information about the atlassian-plugin.xml file, see the Configuring the app descriptor page.