Skip to end of metadata
Go to start of metadata

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 setPageManager() method and pageManager field (more information on dependency injection)
  • in your action's execute() method, retrieve the desired pages using the pageManager object and store them in a field in your class called calculatedPages
  • add a method to your action, getCalculatedPages(), which returns the list of pages
  • in your Velocity template, use $action.calculatedPages to 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:

Variable

Description

Class Reference

$action

The current WebWork action

Your action class, normally a subclass of ConfluenceActionSupport

$i18n

$i18n.getText() should be used for plugin internationalisation.

I18NBean

$dateFormatter

Provides a date and time formatter suitable for the exporting user's locale and environment.

DateFormatter

$req

The current servlet request object (if available)

HttpServletRequest

$req.contextPath

The current context path. Used for creating relative URLs: <a href="$req.contextPath/dashboard.action">Dashboard</a>.

String

$baseUrl

The base URL of the Confluence installation. Used for creating absolute URLs in email and RSS: <a href="$baseUrl/dashboard.action">Back to Confluence</a>.

String

$res

The current servlet response object (should not be accessed in Velocity)

HttpServletResponse

$settingsManager

Can retrieve the current global settings with $settingsManager.getGlobalSettings()

SettingsManager

$generalUtil

A GeneralUtil object, with useful utility methods for URL encoding etc

GeneralUtil

$action.remoteUser, $remoteUser

The currently logged in user, or null if anonymous user.

User

$userAccessor

For retrieving users, groups and checking membership

UserAccessor

$permissionHelper

Can be used to check permissions, but it is recommended that you check permission in your action

PermissionHelper

$attachmentManager

Retrieving attachments

AttachmentManager

$spaceManager

Space operations

SpaceManager

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

Icon

From Confluence 5.2 onwards Soy templates are used instead of Velocity for email notifications.

If customising the Velocity templates for Confluence's email notifications, the following items are available in addition to the default context above.

Variable

Description

Class Reference

$stylesheet

Default stylesheet CSS contents

String

$contextPath

Same as $req.contextPath in the default context

String

$subject

The email notification subject

String

$wikiStyleRenderer

Wiki rendering support

WikiStyleRenderer

$renderContext

Notification render context for use with $wikiStyleRenderer

RenderContext

$report

Daily report (only for digest notifications)

ChangeDigestReport

$showDiffs

Whether this notification should include diffs

boolean

$showFullContent

Whether this notification should include full page content

boolean

$diffRenderer

Diff rendering support

StaticHtmlChangeChunkRenderer

$diff

Diff for the notification, if enabled

ConfluenceDiff

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.

Related Pages

4 Comments

  1. Anonymous

    Hello All,

    I am not bale to use "$baseUrl" object in my velocity template. It returns a null string.
    I am using the Default Velocity Context as shown below:
    Map<String, Object> contextMap = MacroUtils.defaultVelocityContext();

    I am able to retrieve all the objects that I store in the contextMap. Apart from it I am able to get the value for "$req.contextPath" in my velocity template.
    My requirement is to use the $baseUrl object in my velocity template.
    Kindly see if I am missing anything or suggest any alternative to it.

    Thanks,
    Karan

    1. Anonymous

      You can use $bootstrap.getBaseUrl() for this purpose.

      Dorwin D'souza

      dorwindsouza@ yahoo . com

  2. $dateFormatter isn't available in macro templates (java macros or user macros), you'll need to access it via: $action.dateFormatter

  3. Anonymous

    Hello,

    I would get the complete url width Velocity script but without success...

    For example : [http://ww.confluenceroot.com/display/welcome/Home|http://ww.confluenceroot.com/display/welcome/Home] ...

    For the moment i use " $bootstrap.getBaseUrl() " but it isn't what i want.

    Does Someone have an idea ?

    Thanks

    Julien