Confluence has a few distinct Velocity contexts for different purposes in the application (user macros, email templates, exports), but the most commonly used context is called the "default context".
Velocity usage guidelines for plugins
To allow deprecation and code change breakages to be detected at compile time, it is recommended that where possible you add functionality which calls Confluence code in your plugin Java code (i.e. actions or components) rather than in a Velocity template. You can call any method on your plugin action from Velocity with
$action.getComplicatedCustomObject() instead of putting complicated logic in your Velocity template that is not checked by the compiler.
For example, if your plugin needs a calculate list of particular pages to display in the Velocity template, you should do the following:
- inject a PageManager into your action class by adding a
pageManagerfield (more information on dependency injection)
- in your action's
execute()method, retrieve the desired pages using the
pageManagerobject and store them in a field in your class called
- add a method to your action,
getCalculatedPages(), which returns the list of pages
- in your Velocity template, use
$action.calculatedPagesto get the calculated pages from the action and display them.
Although it is supported at the moment, you should not be performing data updates directly from Velocity code and future versions of Confluence may prevent you doing this in your plugin.
Default Velocity context
This list highlights the most important entries in the default Velocity context. The full list is defined in Confluence's source code in
velocityContext.xml. The default Velocity context is used for templates rendered by:
- Confluence WebWork actions
- macros which call MacroUtils.defaultVelocityContext()
- mail notifications (with additions – see below)
- user macros (with additions – see below).
The current WebWork action
Your action class, normally a subclass of ConfluenceActionSupport
Provides a date and time formatter suitable for the exporting user's locale and environment.
The current servlet request object (if available)
The current context path. Used for creating relative URLs:
The base URL of the Confluence installation. Used for creating absolute URLs in email and RSS:
The current servlet response object (should not be accessed in Velocity)
Can retrieve the current global settings with
The currently logged in user, or
For retrieving users, groups and checking membership
Can be used to check permissions, but it is recommended that you check permission in your action
User macro Velocity context
User macros have a Velocity context which includes all the above items and some additional entries specific to user macros. See Guide to User Macro Templates for a list of the latter.
Email notification Velocity context
If customising the Velocity templates for Confluence's email notifications, the following items are available in addition to the default context above.
Default stylesheet CSS contents
The email notification subject
Wiki rendering support
Notification render context for use with
Daily report (only for digest notifications)
Whether this notification should include diffs
Whether this notification should include full page content
Diff rendering support
Diff for the notification, if enabled
Export Velocity context
The export context does not include any of the values from the default context. See Available Velocity Contexts in Exporters for a complete list.