Develop Pluggable Placeholders

Pluggable Placeholder allow to extend the render contexts. This comes handy when you need special placeholders that are not build into Scroll Viewport.

To plug 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.

Create a Pluggable Placeholder

Creating a pluggable placeholder involves two steps: Developing a Java class that represents the placeholder, and registering that class as global Velocity context item in the plugin descriptor.

The big benefit about this approach is that you can easily integrate Scroll Viewport with your own add-on without dealing with out OSGi imports and exports. Just add a Java class to your add-on that accesses your add-on's infrastructure and return what ever data you want to expose to Scroll Viewport templates.

You can find an example Placeholder in our Bitbucket repository.

Develop the placeholder Java class

Developing the Java class can be as simple as the following.

CODE

package test.placeholder;
 
public class PluggablePlaceholder {
    public String getValue() {
        return "value";
    }
}

Register the placeholder as velocity context item

Next you have to register the Java class as velocity context item, with the context-key starting with 'vprt-'.

atlassian-plugin.xml

CODE

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

Scroll Viewport will only pick up velocity context items which have a context key starting with 'vprt-'. Thus, make sure that the value of the context-key attribute starts with 'vprt-'.

Use pluggable placeholder in template

The pluggable placeholder will be available in the template rendering context with the key excluding 'vprt-'. For example:

CODE

<html>
    [...]
    <body>
        Output: $pluggablePlaceholder.value
    <body>
</html>

Questions

If you have questions about this guide, please ask them on the Viewport Developers group.