Skip to end of metadata
Go to start of metadata

Available:

JIRA 3.7 and later

Changed:

In JIRA 4.2 and later, JIRA-specific web resource contexts were added.
In JIRA 4.4 and later, the jira.create.issue JIRA-specific web resource context was added.

 

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.

On this page:

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

Name

Required

Description

Default

class

 

The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances.

 

state

 

Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled').

enabled

i18n-name-key

 

The localisation key for the human-readable name of the plugin module.

 

key

(tick)

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.
<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case.

That is, the identifier of the web resource.

N/A

name

 

The human-readable name of the plugin module. That is, the human-readable name of the web resource.

The plugin key

system

 

Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.false

Elements

Name

Required

Description

Default

description

 

The description of the plugin module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body. That is, the description of the resource.

 

resource

(tick)

A resource for this plugin module. This element may be repeated. A 'resource' is a non-Java file that a plugin may need in order to operate. Refer to Adding Resources to your Project for details on defining a resource.Currently, supported file types are .css and .js.
For web resources, the type attribute must be 'download'.

N/A

dependency

 

Dependencies for the web resource module. A web resource can depend on other web resource(s) to be available. Dependencies are defined in the format 'pluginKey:webResourceKey' e.g. <dependency>com.atlassian.auiplugin:ajs</dependency>
Note: This element is only available in Plugin Framework 2.2 and later.

N/A

context

 

Use this element to include web resources like CSS and JavaScript on all screens of a specific type in the application. See below.
Note: This element is only available in Plugin Framework 2.5 and later.

 

transformation

 

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

For a complete description, please refer to the page on Web Resource Transformer Plugin Modules.
Note: This element is only available in Plugin Framework 2.5 and later.

 

condition

 

Use this element to define when this web resource should display or not.  See Web Item Conditions for more information.
Note: This element is only available in Plugin Framework 2.7 or later.

 

Example

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

Referring to Web Resources

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

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:

Context

Description

atl.general

Everywhere except administration screens.

Icon

An issue prevents this context from working in the JIRA login page in JIRA 5.x and later. See https://jira.atlassian.com/browse/JRA-27960 for more information and a work-around.

atl.admin

Administration screens. Use with care because poorly formed CSS or JavaScript can prevent access to administering the application.

atl.userprofile

User profile screens.

atl.popup

Browser pop-up windows. This will open a new window for things like OAuth authorisation, and similar purposes.

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:

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:

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:

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

Icon

Batched resource URLs do not include any URL path prefixes that were specified in the individual <resource> names. This can cause problems if a resource refers to another resource by a relative URL.

For instance, if your web resource contains a stylesheet with the name "css/styles.css", and that stylesheet uses an image from the same web resource whose name is "images/foo.png", you could use the relative URL ../images/foo.png if batch mode is off; but with batch mode on, the stylesheet will no longer have css/ in its URL, so the relative URL will be wrong. (The absolute URL of the image remains the same, since images are not affected by batching.)

The plugin framework attempts to help by rewriting URLs in stylesheets to be relative to the server root, but there is a known issue that prevents this from working correctly. Therefore, if you do not know whether batch mode will be on or off, avoid using a subpath prefix in the name attribute of any resource that contains relative URL references. In the above example, the stylesheet's name would be simply "styles.css" and the relative image URL would be images/foo.png. The location attribute, since it refers to the location of the actual file before any batching or URL rewriting takes place, does not need to change.


Transforming Web Resources

(info) 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.

Web Resource Contexts in JIRA

(info) Available in JIRA 4.2 and later.

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:

Context

Description

jira.error

Applies to the 500 page and sitemesh error decorators.

jira.admin

Anywhere in the admin section.

jira.general

Applies to every page in JIRA.

jira.popup

Popups such as the userpicker popup.

jira.userprofile

A user's own profile page.

jira.dashboard

A dashboard page in JIRA.

jira.browse

Applies to all the specific 'jira.browse' pages below.

jira.browse.component

The browse components page for a project.

jira.browse.project

The browse project page for a single project.

jira.browse.projects

The browse all projects page.

jira.browse.version

The browse versions page for a project.

jira.view.issue

The view issue page in JIRA.

jira.create.issue
(only available in JIRA 4.4 and later)

The create issue page in JIRA.

jira.navigator.advanced

Includes web-resources on the advanced view of the issue navigator

jira.navigator.simple

Includes web-resources on the simple view of the issue navigator

atl.error

Error messages and pages.

atl.dashboard

Dashboard pages.

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:

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:

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
Managing JIRA's Plugins

Information sourced from Plugin Framework documentation

  • No labels

5 Comments

  1. If you are trying to use a web resource inside of a vm file, use $requestContext.baseUrl just like you would use _ATLASSIAN_BASE_URL_ inside of a gadget.xml file. It took me a while to figure that out.

    1. Anonymous

      That is cool, here is another quetion, what happens if you want to use _ATLASSIAN_BASE_URL_ on a .js web resource? y particulary want to create the entire gadget on another js file but i need _ATLASSIAN_BASE_URL_

      1. Anonymous

        I have the same kind of problem : I need to get the jira context directly from a .js web resource without building a gadget...and I can't get the _ATLASSIAN_BASE_URL_ variable...How can I do that? 

        1. Anonymous

          problem solved : the global variable "contextPath" is loaded by default by Jira so I can get the jira context directly from JS resource ;)

  2. Anonymous

    Jira Web Resource Contexts make life much easier. They are very useful especially to include additional stuff like scripts.

    Be aware, that there are some more contexts available than documented here. For example there is a jira.navigator context you can use instead of jira.navigator.simple AND jira.navigator.advanced, a context jira.inline.dialog and if you use Greenhopper there is also a context com.atlassian.greenhopper.plugin-context for all your agile views.

    Of cause plugins can introduce their own contexts, so offering a complete list of all contexts in your concrete Jira instance is not possible. Nevertheless if you have a source code license, you can find them by your own! Look for the class com.atlassian.plugin.webresource.WebResourceManagerImpl in atlassian-plugins-webresource-x.x.x.jar and find the method requireResourcesForContext. You can create a breakpoint there and add a condition like this:

    From now on all contexts your Jira instance asks for are printed out to the console. Notice that this makes your system slow. Simply disable it after finding the right strings.

    Cheers,
    Stefan