Skip to end of metadata
Go to start of metadata


Confluence 1.4 and later


Velocity Context plugin modules enable you to add components to Confluence's velocity context, making those components available in templates rendered from decorators, themes, XWork actions or macros.

Velocity Context Plugin Module

Each component module adds a single object to Confluence's default velocity context. This context is the collection of objects that are passed to each velocity template during rendering of macros, decorators, themes and XWork actions. This allows you to create helper objects that perform tasks too complex to represent in Velocity templates.

The objects are autowired by Spring before being added to the context.

Here is an example atlassian-plugin.xml file containing a single velocity context module:

  • the name attribute represents how this component will be referred to in the Confluence interface.
  • the key attribute represents the internal, system name for your component.
  • the context-key attribute represents the variable that will be created in Velocity for this item. So if you set a context-key of myVelocityHelper, the object will be available as $myVelocityHelper in Velocity templates
  • the class attribute represents the class of the component to be created.

(info) Note: Every velocity context module needs a unique key, or Confluence will not be able to render the module.

  • No labels


  1. Can you give a short example for this plugin, e.g. implemented Java code?


  2. Is there a list of objects that are in "Confluence's default velocity context" ?


    I found exactly what I want, but for JIRA (sad) at field Velocity context unwrapped maybe that'll be enough...

    Update Update

    There is a list of "Available objects" on the User Macro page 

    1. Hi RefuX,

      I have added a comment regarding the page that provide a list of default/available objects for Velocity template here.
      Hope the information helps.


  3. Anonymous

    I cannot seem to access my Velocity context plugin module from the Page.pdfexport.vm velocity macro file.

    I can access if from other velocity macros though.

    Any thoughts?  Thanks

    1. Hi there,

      I am afraid that, a customized velocity context plugin is not possible to use in a *.pdfexport.vm file nor a *.htmlexport.vm file currently. However, I have raised a bug report regarding this in our Issue Tracker that can be accessed via:

      Feel free to add yourself as a watcher so that you will be notified if there are any updates in the bug report. Also, you may want to add comments in the issue reported to truly reflect the problem that you are having.


  4. Anonymous

    A piece of java code is valuable since I have no idea how to inplement MyVelocityHelper at all. extend a class. implement a interface. no at all.

    1. You don't need to extend or implement anything. The only requirement listed is "The class must have a no-argument constructor, or it will not be able to be instantiated by Confluence."

      The class is simply created using the no arg constructor and placed in the Velocity context. You are then free to call any methods on the object that are available via reflection.

  5. Once the plugin with the Velocity Context component has been installed, it appears that it is necessary to restart Confluence in order for a component reference to work correctly.

    Can you confirm that this is the case? Is there a fix for this issue?


  6. Hi,

    We are using the velocity context helper in our custom theme plugin.
    This is the code in atlassian-plugin.xml

    When i use this in Confluence 3.0.1, after every server restart, the velocity plugin module gets disabled.
    This is the atlassian-confluence.log error:

    I have the same code working fine in Confluence 2.6.0.
    Can you advise me regarding this issue.