Search code examples
velocityconfluence

How do I get a list of the Velocity objects and APIs usable in user macros in Atlassian Confluence?

I need to write some user macros in Atlassian Confluence. It uses the Apache Velocity templating engine. How can I find which APIs are available in that context?

For example, one community-provided macro uses objects like $spaceManager. How can I enumerate all of the objects that are available, and also get documentation for their methods?

The page on the Atlassian site listing the objects is incomplete: not only does it only list a small fraction of the true objects available, it's also not specific to the user macro context, or even to my specific version of Confluence. (For example, user macros are given a different Velocity context than Velocity used in other plugin points and have different objects available, and the objects available in Confluence 5.1 are different from those available in Confluence 5.6.)

There are similar questions on the Atlassian Answers site, but none point to complete API and type references.

Solution

  • The official list of Velocity objects visible in Confluence is listed on Atlassian's site, but as you may have noticed, it is far from complete.

    With JIRA, there is a trick that one can use to list all objects in the current Velocity context:

    #foreach($p in $ctx.keySet().toArray())                                
        $p.toString() - $ctx.get($p).getClass().getName().toString() 
#end

    Unfortunately, the JIRA trick above does not work for Confluence because Confluence does not expose the ctx map.

    Luckily, you mentioned that you are writing user macros, so not all is lost! Using another trick to access objects that are not normally available in the default context, you can punch a hole through to the class that provides the Velocity context for user macros and give yourself a copy. Combining the two approaches, we get the following for Confluence:

    #set($macroUtilClass=$action.class.forName('com.atlassian.confluence.renderer.radeox.macros.MacroUtils'))
#set($getContextMethod=$macroUtilClass.getDeclaredMethod('defaultVelocityContext',null))
#set($ctx=$getContextMethod.invoke(null))

#foreach($p in $ctx.keySet().toArray())
$p.toString() - $ctx.get($p).getClass().getName().toString()<br/>
#end

    This gives you a list of all objects available and their corresponding types, like this:

    res - com.atlassian.confluence.web.filter.DebugFilter$LoggingResponseWrapper
bootstrap - com.atlassian.confluence.setup.DefaultBootstrapManager
settingsManager - com.atlassian.confluence.setup.settings.DefaultSettingsManager
userAccessor - com.sun.proxy.$Proxy54
seraph - com.atlassian.confluence.util.SeraphUtils
xsrfTokenGenerator - com.atlassian.xwork.SimpleXsrfTokenGenerator
...

    To find the methods available through each of those objects, you will need to look up the corresponding JavaDocs by the class name. I find that Google is often the fastest path to done, but you can also go directly to the JavaDocs (for example, for the SpaceManager) and then root around in the other packages or adjust the URL to match the class you want. You will also want to adjust the "latest" in the URL to correspond to the actual version of Confluence you have installed. Lastly, a few of the classes are hidden behind proxies (like userAccessor above), but the variable name often matches the class name, so these are usually easy to figure out.

    Note that this example is specifically tailored for user macros. The objects available in other Velocity contexts will certainly be different.