This page last changed on Dec 16, 2007 by mryall.
Good style for web applications requires that Javascript and CSS for web pages are kept separate to the HTML they enhance. Confluence itself is moving towards this model, and the tools that Confluence uses to do this are also available to plugin developers.
 | This functionality is only available in Confluence 2.8 and later. |
Including a custom Javascript or CSS file from a plugin
In your atlassian-plugin.xml, you should add a new [web resource plugin] in this format:
<atlassian-plugin key="com.example.confluence.plugin.special" name="My Special Plugin" i18n-name-key="com.example.confluence.plugin.name">
<web-resource key="mechanical-parts" name="Mechanical Parts" i18n-name-key="com.example.confluence.plugin.special.mechanical.parts.name">
<resource type="download" name="widgets.js" location="/js/widgets.js"/>
<resource type="download" name="sprockets.css" location="/styles/sprockets.css"/>
</web-resource>
</atlassian-plugin>
For each resource, the location of the resource should match the path to the resource in your plugin JAR file. For example, 'widgets.js' in the above plugin JAR would be at /js/widgets.js. Resource paths are namespaced to your plugin, so they can't conflict with resources in other plugins with the same location (unlike say i18n or Velocity resources). However, you may find it convenient to use a path name which is specific to your plugin to be consistent with these other types.
Then, in a Velocity template that requires that Javascript file, you use the #requireResource macro, with the plugin key followed by a colon and the key of the web-resource:
#requireResource("com.example.confluence.plugin.special:mechanical-parts")
In the HTML header of any page containing that Velocity template, all resources included in the web-resource plugin will be written out as script or link tags to include the relevant resource:
<html>
<head>
<script type="text/javascript" src="/s/.../_/download/com.example.confluence.plugin.special:mechanical-parts/widgets.js"></script>
<link type="text/css" rel="stylesheet" src="/s/.../_/download/com.example.confluence.plugin.special:mechanical-parts/spockets.css">
</head>
</html>
Only one instance of each script or stylesheet will be included, and they will appear in the order they are requested in the Velocity rendering process.
Including a Javascript library provided by Confluence
Confluence currently includes several Javascript libraries which can be used by plugins. The versions of these libraries are subject to change, but only across major versions of Confluence.
In the Confluence source code, these libraries are included in a plugin XML file called web-resources.xml.
Library |
Web resource key |
Current version |
Details |
Scriptaculous |
confluence.web.resources:scriptaculous |
1.5rc3 |
Includes effects, dragdrop, controls and util. |
Prototype |
confluence.web.resources:prototype |
1.4.0_pre11 |
Version found in the scriptaculous lib directory. Also includes a domready extension, see domready.js. |
YUI Core, DOM, Events |
confluence.web.resources:yui |
2.2.2 |
|
DWR |
confluence.web.resources:dwr |
1.1.4 |
Includes engine and util. |
To include one of these libraries in all pages in which your Velocity template appear, simply use the #requireResource macro as above. For example, if your macro requires Scriptaculous, add the following to its Velocity template:
See also
Confluence Plugin Guide
Writing Confluence Plugins
|