I've just released the first version of my jQuery macro for Confluence.
It can be found here: http://confluence.atlassian.com/display/DISC/jQuery+User+Macro
It allows you, the Confluence user, to use jQuery in your own pages, comments, and user macros - with the following advantages:
- You can use $ and/or jQuery syntax.
- It does not interfere/conflict with Confluence's version of jQuery.
- Multiple versions of jQuery can be referenced on a single page.
- Easy to reference plugins.
Examples
A couple of examples showing how to call the macro using wiki mark-up.
{jquery}
$(function() {
$("#elementId").hide();
});
{jquery}
{jquery:plugins=http://....jquery.plugin.js}
$("#elementId").pluginMethod();
{jquery}
There are more examples at the dedicated macro page (link at the top of this post).
Why a user macro? Why not a native plugin?
I am not a Java developer, so I implemented this as a user macro using HTML, javascript, and Velocity. This brings some small advantages and disadvantages compared to developing it as a native Confluence plugin:
- When developing a user macro you only have access to a small number of Confluence objects, but I also see this as a huge benefit - as I am far less likely to tightly-couple myself to a specific version of Confluence, hence the macro is less likely to break when I upgrade Confluence.
- Another disadvantage of writing a user macro is that each time you use it in a page, it is completely unaware of the other instances in the same page. For example, if I call this macro a second time - the macro itself is completely unaware that it has previously been called. This causes a problem - I do not want the page to load jQuery (and referenced plugins) multiple times.. to get around this I had to write some javascript to check if jQuery had already been loaded before dynamically loading jQuery.
How do I specify the type of body?
You have the choice of three different body formats: javascript, wiki mark-up, or HTML. The macro defaults to javascript, but you can specify the format using the 'markup' parameter. There are examples on the dedicated macro page (link at the top of this post).
How do I reference plugins?
You just specify a 'plugins' parameter with a comma-delimited list of plugin URLs.
How is it possible to use multiple versions of jQuery?
You are able to specify the version of jQuery using the 'version' parameter, and if not specified the macro defaults to the latest version of jQuery. The macro then loads this version of jQuery and gives it a unique "namespace". Each mention of jQuery in the macro body is then transformed to correspond to the namespaced version of jQuery. This results in the ability to reference different versions of jQuery, and also not conflict with the jQuery library directly used by Confluence itself.
What next?
I still need to flesh the documentation out a bit more, but once I've finished the documentation I'll try posting some more examples - and maybe even some user macros that utilise this macro. Also a colleague of mine, Charles Hall, will be giving a presentation on jQuery macros and Confluence at this year's Atlassian Summit, so if you are one of the lucky ones attending - make sure you don't miss his presentation!
Subscribe