This page last changed on Dec 02, 2008 by smaddox.

Please take a look at our overview of how and why you should include Javascript and CSS resources into your plugin. The page below gives specific details of the Web Resource plugin module type.

Including your web resource in a specific context
In Confluence 2.10 we added the ability to specify web resources like CSS and JavaScript to be included in specific contexts of Confluence. Please see below for the currently available contexts and more information.

On this page:

Error formatting macro: toc: java.lang.NullPointerException

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.

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.  
disabled   Indicate whether the plugin module should be disabled by default (value='true') or enabled by default (value='false'). false
i18n-name-key   The localisation key for the human-readable name of the plugin module.  
key The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes you will need to uniquely identify a module. Do this with the module complete key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred. I.e. the identifier of the web resource.
N/A
name   The human-readable name of the plugin module. I.e. the human-readable name of the web resource. The plugin key
singleton   Indicates whether this plugin module should only have one instance of its class (value='true') or may have more than one instance (value='false').
Support for this attribute varies between applications (JIRA, Confluence, etc).
false
system   Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). 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. I.e. the description of the resource.  
param   Parameters for the plugin module. Use the 'key' attribute to declare the parameter key, then specify the value in either the 'value' attribute or the element body. This element may be repeated. An example is the configuration link described in Adding a Configuration UI for your Plugin. N/A
resource 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 Plugin and Module Resources 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

Example

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

<atlassian-plugin name="Hello World Resource" key="example.plugin.helloworld" pluginsVersion="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 WebResourceManager and call the requireResource() method. The reference to WebResourceManager can be injected into your constructor:

public MyServlet extends HttpServlet 
{
    private WebResourceManager webResourceManager;
    public MyServlet(WebResourceManager webResourceManager) 
    {
        this.webResourceManager = webResourceManager;
    }

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

The URL for a downloadable resource is application specific. For JIRA it would be as follows:

{server root}/s/{build num}/{plugin version}/{system counter}/c/download/resources/{plugin key}:{module key}/{resource name}

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

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

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 Confluence 2.10 we added the ability to specify web resources like CSS and JavaScript to be included in specific contexts of Confluence. The currently available contexts are:

  • admin
  • main
  • dashboard
  • editor
  • page
  • blogpost
  • space

To configure your web resource to be included for example in the 'space' and 'page' contexts you add <context> child elements to your <web-resource> element in your atlassian-plugin.xml:

<web-resource name="Resources" key="resources">
        <resource name="foo.js" type="download" location="/resources/foo.js">
        </resource>
        <context>space</context>
        <context>page</context>
</web-resource>

Using web resource contexts is a great way to provide plugins that dynamically create HTML using JavaScript. At Atlassian we built a plugin which listens to a particular keyboard shortcut to open a little search box on top the Confluence UI.

RELATED TOPICS

Adding Plugin and Module Resources
Including Javascript and CSS resources
Writing Confluence Plugins
Installing and Configuring Plugins Manually

Document generated by Confluence on Dec 03, 2008 15:14