Confluence Docs 3.0 : Web Resource Plugins This page last changed on Sep 07, 2009 by ggaskell. 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: Purpose of this Module Type Configuration Attributes Elements Example Referring to Web Resources Batched Mode Non-Batched Mode Notes Web Resource Contexts ## 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
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. I.e. the description of the resource. |
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
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>confluence.web.resources:ajs</dependency>` Note: This element is only available from 2.2. | 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" 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 `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
        }
    }
### Batched Mode The default mode for serving web resources in Plugins 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 fomat:
    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:
    <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>
### Non-Batched Mode Prior to Plugins 2.2, each resource defined was served separately. To revert to this non-batched mode, you can either use the system property {{plugin.webresource.batching.off=true }}to turn off batching system wide or define a 'batch' parameter on each resource like so:
    <resource type="download" name="scriptaculous.js" location="includes/js/effects/scriptaculous.js" >
       <param name="batch" value="false"/>
    </resource>
URLs for non batched resources are in the following fomat:
    SERVER_ROOT/s/BUILD_NUM/PLUGIN_VERSION/SYSTEM_COUNTER/_/download/resources/PLUGIN_KEY:MODULE_KEY/RESOURCE_NAME
For the above scriptaculous example with batching turned off, 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 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. The currently available contexts are:
Context | Description
--- | ---
main | Everywhere except administration screens
admin | Administration screens. Use with care because poorly formed CSS or JavaScript can prevent access to administer Confluence.
dashboard | Dashboard
editor | Anywhere an editor appears (fixed in 3.1 to work in comment editor).
page | Any page-related screen like view, edit, attachments, info; but not blog post, space or global screens.
blogpost | Any blog-related screen like view, edit, attachments, info; not page, space or global screens.
space | Any space-related screen, like those found in the top section of the Browse menu.
Technical note: the 'page', 'blogpost' and 'space' contexts correspond to the usage of the 'page.vmd', 'blogpost.vmd' and 'space.vmd' decorators in Confluence. 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 allows you to provide plugins that dynamically create HTML using JavaScript on any page in Confluence. For example, the 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 lot of screens to Confluence, 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:
    #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 you namespace your new contexts in this way so as not to clash with any future contexts in Confluence or other plugins. ##### RELATED TOPICS Adding Plugin and Module Resources Including Javascript and CSS resources Writing Confluence Plugins Installing and Configuring Plugins Manually Information sourced from Plugin Framework documentation

Document generated by Confluence on Nov 05, 2009 23:34