Creating custom Velocity context items

Custom Velocity context items allow you to extend the available placeholders that can be used within our Scroll Exporters. This comes handy when you need special placeholders that are not build in, or want to refer to other plugins. The big benefit about this approach is that you can easily integrate your Scroll Exporter with your own add-on without dealing with OSGi imports and exports. Just add a Java class to your add-on that accesses your add-on's infrastructure and refer to this data with a placeholder in your template.

Before you begin: To define in your own placeholder, you have to develop a Confluence plugin, that contains a velocity context item module.

Prerequisite

This article assumes that you have some knowledge about plugin development with the Atlassian SDK.

Creating a pluggable placeholder involves three steps:

Develop the Placeholder Java Class

The first step is to define the Java class for your placeholder in your plugin code.

For example:

CODE

package test.placeholder;
   public class PluggablePlaceholder {
    public boolean isConfidential(String spacekey) {
        return ...;
    }
}

Register the Placeholder as Velocity Context Item

After you've created your Java Class, you have to register this class as velocity context item in the atlassian-plugin.xml of your plugin.

Info

Make sure that the value of the context-key attribute starts with 'exp-', as our Scroll Exporter will only pick up velocity context items which have a context key starting with 'exp-'.

For example:

atlassian-plugin.xml

CODE

<atlassian-plugin ...>
    [...]
   <velocity-context-item key="pluggablePlaceholder"
         name="Pluggable Placeholder" context-key="exp-myPlaceholder"
         class="test.placeholder.PluggablePlaceholder"
         global="true"/>
</atlassian-plugin>

Use the placeholder in Template

After you've created the Java class and registered the placeholder, it can be used in your template be used in your template.

Info

Make sure to refer to the placeholder without the 'exp-' prefix.

For example:

In your template

CODE

#if ($myPlaceholder.isConfidential($space.key))
  <p>Confidential</p>
#end