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"/>
	<velocity-allowlist key="velocity-allowlist">
		<method>test.placeholder.PluggablePlaceholder#getValue()</method>
	</velocity-allowlist>
</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-'.

From Confluence 9.0, all method invocations in Velocity templates are subject to a strict method allowlist. Any attempted method invocations which are not allowlisted will result in a log warning and the method invocation being blocked.

All the methods defined in your placeholder need to be allowlisted by using the velocity-allowlist item as seen in the snippet above. More info on the velocity allowlist configuration can be found here.

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.