Creating a Template Bundle
This tutorial applies to Confluence 3.2 - Confluence 4.3
(As of Confluence 5.0 plugin developers can bundle templates as part of their add-ons. See Preparing for Confluence 5.0 for details)
Level of experience:
Intermediate. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'. This one is at 'intermediate' level. If you have never developed a plugin before, you may find this one a bit difficult.
|Status:||LEGACY This tutorial applies to Confluence versions that have reached end of life.|
A template is a pre-defined page that can be used as a prototype when creating new pages. Templates are useful for giving pages a common style or format. Templates are written in regular Confluence wiki markup, using special markup to define form fields that need to be filled in. A template bundle is essentially a collection of templates packaged up into a plugin.
The templates framework plugin bundled with Confluence 3.2 allows custom template bundles to be deployed to a Confluence instance by creating a standard Atlassian Plugin that depends on the templates framework. Once you have created and deployed a custom template bundle to a Confluence instance, you will be able to import the templates to use globally or within specific spaces.
On this page:
If you are unfamiliar with plugin development, we recommend that you read the guide to developing with the Atlassian Plugin SDK before you read this document. You may also want to read Common Coding Tasks for an overview of the plugin framework. Some experience with Maven is assumed for plugin development. If you haven't used Maven before, you may want to read the Maven documentation to familiarise yourself with it.
Creating a Template Bundle
1. Archetype Your Plugin
Create a new plugin confluence plugin with the
atlas-create-confluence-plugin command. We will define this plugin as a dependency of the templates framework. The functionality it will provide is an implementation of the
TemplatePackage interface which provides a
java.util.List<PageTemplate> to the framework.
The implementation of how your plugins are stored are completely up to you, the example at the end of this page uses an XML file and JAXB.
2. Define The Dependencies
We have to add both the maven dependency to your
pom.xml and a component in the
Add this dependency to your
pom.xmlfile for the plugin:
Define this component in your
In this example the
com.atlassian.confluence.plugin.templates.packages.DefaultTemplatesPackage class is our plugin implementation, change this to your plugin class. The
<interface>com.atlassian.confluence.plugin.templates.export.TemplatePackage</interface> line should not be changed as this is the dependency the Atlassian Plugins Framework uses to register your plugin with the templates framework.
3. Implement The Interface
For the plugin to function as a templates bundle, we must implement the
TemplatePackage interface that is exported by the templates framework. This allows the plugin to provide a list of templates to the framework.
The interface defines two methods:
getAvailableTemplates() method will provide the template data to the framework in the form of
PageTemplate instances. When you instantiate these instances you should set the following members of the instance with your template data:
name- not null
content- not null
The order of the returned list is not important, as this list will be sorted by the template name before it is rendered.
4. Install The Template Bundle
The template bundle should be installed as a normal plugin, the Atlassian Plugins Framework will take care of registering it with the templates framework. After it is installed, the template bundle will be available under the
Import Templates administration menu item (see Importing Templates).
The example provided here is only applicable to the
DefaultTemplatesPackage that is bundled with Confluence 3.2. This plugin stores the templates as an XML file and uses JAXB to load in the file.
The code samples below are intended to be used as references only, as there are a number of ways that template bundles can be built.
Screenshot: Example directory structure for template bundle
Click to expand any code sample below.