Web Panel Renderer Plugin Module
Atlassian Plugin Framework 2.5 and later.
Purpose of this Module Type
The Web Panel Renderer plugin module allows plugins to define custom renderer engines for web panels. (Web panels are bits of HTML that will be inserted into a page.)
The root element for the Web Panel Renderer plugin module is
web-panel-renderer. It allows the following attributes and child elements for configuration:
|Description||The class which implements com.atlassian.plugin.web.renderer.WebPanelRenderer. This class is responsible for turning a web panel's content into proper HTML. See the plugin framework guide to creating plugin module instances.|
|Description||Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled').|
|Description||The localisation key for the human-readable name of the plugin module.|
In the example,
|Description||The human-readable name of the plugin module. Used only in the plugin's administrative user interface.|
|Description||Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.|
Writing a Custom Renderer
To create your own renderer you should create a class that implements com.atlassian.plugin.web.renderer.WebPanelRenderer.
As an example we will create a plugin for the Atlassian Reference Application (version 2.5.0 or higher). We will create a web panel template renderer for FreeMarker templates, which is a format that is not supported by the Atlassian Plugin Framework out of the box. We will then also add a web panel that uses a FreeMarker template.
Using the Atlassian Plugin SDK, create a new plugin for the Reference Application and make sure the generated
pom.xmlfile uses version 2.5.0 or higher:
Add the FreeMarker library to the Maven dependencies:
Create your renderer class:
Note how the
WebPanelRendererinterface declares two render methods: one that takes the name of a template file and one that takes the whole template as a String. In this example we have only implemented the former method. The latter is left as an exercise for you. The consequence of this is that we will not be able to embed our FreeMarker content in
Add the new renderer to
Add a web panel to the Reference Application's administration page that uses this new renderer:
Add your FreeMarker template:
- Start up the Reference Application using the command:
$ atlas-mvn refapp:run)
- Go to:
You may have noticed how the configuration for our FreeMarker's template loader uses a
freemarker.cache.ClassTemplateLoader instance which expects templates to be on the classpath. To do this, FreeMarker's
ClassTemplateLoader constructor takes a
Class instance and then calls
Class.getResource() when it needs to load a template.
In our example we use
FreeMarkerWebPanelRenderer.class, which means that our renderer is limited to rendering templates that live in its own plugin JAR file. This is sufficient for this tutorial which has the renderer, the web panel and the template all in the same plugin. However, it would not work when the renderer is shared with other plugins and needs to render a template that lives in another plugin JAR.
If you want to build a shared FreeMarker renderer this way, you would have to implement your own
freemarker.cache.TemplateLoader. Instead of taking a
Class instance, your template loader would take the
ClassLoader that is returned by
To keep the example clear and simple, we have chosen to accept this limitation. However, note that it has been addressed properly in the full source code that is available below.
To access the full source code for this plugin, you can: