\n","Batched resource URLs do not include any URL path prefixes that were specified in the individual "," Available: Atlassian Plugin Framework 1.x and later. Changed: 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. 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. 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. The root element for the Web Resource plugin module is Name* Description class state (default: enabled) i18n-name-key key name (default: the plugin key) The human-readable name of the plugin module. That is, the human-readable name of the web resource. location The location into which this web item should be placed. system (default: false) *key attribute is required Name* Description description resource dependency context 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. condition Use this element to define when this web resource should display or not. See Web Item Conditions for more information. *resource element is required Here is an example In your plugin, you need to refer to a 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. 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 Using web resource contexts allows you to provide plugins that dynamically create HTML using JavaScript on any page in the application. 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 This will include any resource in the page that specifies a context like this in its definition: 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. 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: Batched resource URLs do not include any URL path prefixes that were specified in the individual For instance, if your web resource contains a stylesheet with the name 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 !!! 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 For a complete description and example, please refer to the page on Web Resource Transformer plugin modules. Use this element to make a particular transformer available to the web resource in the plugin. Example: 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'. 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, Confluence provides the following Confluence-specific contexts: 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. 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 Example: To configure your web resource to be included in the 'space' and 'page' contexts, add If your plugin adds a number of screens to Confluence, it might be annoying to put many To introduce a new context in your plugin Velocity templates, you can call the This will include any resource in the page that specifies a context like this in its definition: We recommend that you namespace your new contexts in this way so as not to clash with any future contexts in Confluence or other plugins. Adding Plugin and Module Resources Rate this page:
\nIncluding Javascript and CSS resources
\nWriting Confluence Plugins","Rate this page:","Unusable","Poor","Okay","Good","Excellent","ChangelogSystem statusPrivacyNotice at CollectionDeveloper TermsTrademarkCookie preferences© 2024 Atlassian"]}
Web Resource module
Purpose of this Module Type
Configuration
web-resource
. It allows the following attributes and child elements for configuration:Attributes
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. Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled'). The localisation key for the human-readable name of the plugin module. 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.
That is, the identifier of the web resource.1
2
<web-resource key="resoureceKey">
...
</web-resource>
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins. Elements
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. Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled'). 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.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.1
2
<transformation extension="txt">
<transformer key="template" />
</transformation>
Note: This element is only available in Plugin Framework 2.5 and later.
Note: This element is only available in Plugin Framework 2.7 or later.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="resoureceKey" name="Resource" >
<resource type="download" name="resourece.js" location="includes/js/effects/resourece.js" />
<resource type="download" name="effects.js" location="includes/js/effects/effects.js" />
</web-resource>
</atlassian-plugin>
Referring to Web Resources
PageBuilderService
and call the requireResource()
method. A reference to a PageBuilderService
can be injected into your constructor:1
2
@Named
public MyServlet extends HttpServlet {
@ConfluenceImport
private PageBuilderService pageBuilderService;
@Inject
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:resoureceKey");
// more code
}
}
Web Resource Contexts
<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>
Introducing new contexts
requireResourcesForContext()
method on the WebResourceManager
object from your Velocity templates:1
2
$webResourceManager.requireResourcesForContext("com.acme.plugin.fancy-context")
<context>com.acme.plugin.fancy-context</context>
.Batched Mode
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
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>
<resource>
names. This can cause problems if a resource refers to another resource by a relative URL."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.)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
atlassian-plugin.xml
file:
<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>
element and its child <transformer>
element inside the <web-resource>
block, making a particular transformer available to the web resource in the plugin.Notes
Web Resource Contexts in Confluence
editor-content Inside the editor content iframe used by the editor. macro-browser Macro browser specific resources. Included after the editor resources. preview Inside the preview pane of the macro browser page.vmd
, blogpost.vmd
and space.vmd
decorators in Confluence.<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>space</context>
<context>page</context>
</web-resource>
Introducing New Contexts in Confluence
#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.#requireResourcesForContext()
Velocity macro:1
2
#requireResourcesForContext("com.acme.plugin.fancy-context")
<context>com.acme.plugin.fancy-context</context>
.RELATED TOPICS
Including Javascript and CSS resources
Writing Confluence Plugins