Skip to end of metadata
Go to start of metadata
Icon

As of the upcoming Confluence 5.0 this feature will be deprecated. We will be releasing a new create experience which will enable plugin developers to bundle templates as part of their add-ons. See Preparing for Confluence 5.0 for details.

Applicable:

This tutorial applies to Confluence 3.2.

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.

 

 

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:

Required Knowledge

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.

Incorrect Confluence version in plugin archetype

Icon

If you are not using the latest Atlassian Plugin Development Kit, your plugin archetype may be created with an incorrect Confluence version. Please check your pom.xml and update the product (Confluence) version to 3.2 or later, or update your PDK to the latest version and create a new plugin archetype.

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 atlassian-plugin.xml file.

  • Add this dependency to your pom.xmlfile for the plugin:

  • Define this component in your atlassian-plugins.xmlfile:

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:

and

The 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
  • description
  • labels

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).

Example Code

 

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

(tick) Click to expand any code sample below.

Framework Interface - TemplatePackage.java
Example Implementation - DefaultTemplatesPackage.java
JAXB XSD Schema
Maven2 changes for XSD generation
Example templates.xml data