How to create a Template Bundle Plugin in Confluence
July 12th, 2010 by Micha KopsSince Confluence 3.2. there is a new plugin module type that allows you to deploy templates in a bundle via the plugin API.
In addition it is possible to assign these templates to specific spaces and preview available templates in the Confluence administration area.
So let’s build some sample templates..
Creating a Template Bundle Plugin
Creating a template bundle is easy – just create a class implementing TemplatePackage – there are two methods: one returns a list of bundled PageTemplate Objects the other the name for the template bundle.
Here we go..
- Create a new Maven project using the following command on the console or your IDE e.g. Eclipse with the Maven plugin installed
- Your pom.xml could look like this:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <parent> <groupId>com.atlassian.confluence.plugin.base</groupId> <artifactId>confluence-plugin-base</artifactId> <version>25</version> </parent> <modelVersion>4.0.0</modelVersion> <groupId>com.hascode.confluence.plugin</groupId> <artifactId>template-bundle-sample</artifactId> <version>0.1</version> <name>hasCode.com - Template Bundle Sample</name> <packaging>atlassian-plugin</packaging> <properties> <atlassian.plugin.key>com.hascode.confluence.plugin.template-bundle-sample</atlassian.plugin.key> <!-- Confluence version --> <atlassian.product.version>3.1</atlassian.product.version> <!-- Confluence plugin functional test library version --> <atlassian.product.test-lib.version>1.4.1</atlassian.product.test-lib.version> <!-- Confluence data version --> <atlassian.product.data.version>3.1</atlassian.product.data.version> </properties> <description>hasCode.com - Template Bundle Tutorial</description> <url>https://www.hascode.com</url> <dependencies> <dependency> <groupId>com.atlassian.confluence.plugins</groupId> <artifactId>templates-framework</artifactId> <version>0.4</version> <scope>provided</scope> </dependency> </dependencies> <organization> <name>hasCode.com</name> <url>https://www.hascode.com</url> </organization> <repositories> <repository> <id>maven.repo.remote</id> <url>http://www.ibiblio.org/maven</url> </repository> </repositories> </project>
- Define the template bundle in the atlassian-plugin.xml
<atlassian-plugin key="${atlassian.plugin.key}" name="Template Bundle Samples" pluginsVersion="2"> <plugin-info> <description>hasCode.com - Template Bundle Tutorial</description> <version>${project.version}</version> <vendor name="hasCode.com" url="https://www.hascode.com"/> </plugin-info> <component name="Templates: Default Package" key="templates" public="true" > <interface>com.atlassian.confluence.plugin.templates.export.TemplatePackage</interface> </component> </atlassian-plugin>
- Create a new package e.g. com.hascode.confluence.plugin.template and a class implementing com.atlassian.confluence.plugin.templates.export.TemplatePackage named MyTemplatePackage
package com.hascode.confluence.plugin.template; import java.util.ArrayList; import java.util.List; import com.atlassian.confluence.pages.templates.PageTemplate; import com.atlassian.confluence.plugin.templates.export.TemplatePackage; import com.atlassian.confluence.plugin.templates.export.TemplatePackageException; public class MyTemplatePackage implements TemplatePackage { public List<PageTemplate> getAvailableTemplates() throws TemplatePackageException { List<PageTemplate> templates = new ArrayList<PageTemplate>(); PageTemplate t = new PageTemplate(); t.setName("Some sample template"); t.setContent("This is a test"); t.setDescription("This sample template prints some sample text"); t.setLabels("test"); templates.add(t); return templates; } public String getPackageName() { return "A nice template package bundle"; } }
- This is a very simple way to create a template – in a real scenario we are going to use templates – so this is the updated class using a velocity template to render its content
package com.hascode.confluence.plugin.template; import java.util.ArrayList; import java.util.List; import java.util.Map; import com.atlassian.confluence.pages.templates.PageTemplate; import com.atlassian.confluence.plugin.templates.export.TemplatePackage; import com.atlassian.confluence.plugin.templates.export.TemplatePackageException; import com.atlassian.confluence.renderer.radeox.macros.MacroUtils; import com.atlassian.confluence.user.AuthenticatedUserThreadLocal; import com.atlassian.confluence.util.velocity.VelocityUtils; public class MyTemplatePackage implements TemplatePackage { private static final String SAMPLE_TEMPLATE = "plugins/template-sample-demo/notes.vm"; public List<PageTemplate> getAvailableTemplates() throws TemplatePackageException { List<PageTemplate> templates = new ArrayList<PageTemplate>(); final Map<String, Object> context = MacroUtils.defaultVelocityContext(); context.put("author", AuthenticatedUserThreadLocal.getUser()); final String content = VelocityUtils.getRenderedTemplate( SAMPLE_TEMPLATE, context); PageTemplate t = new PageTemplate(); t.setName("Sample notes"); t.setDescription("A sample template that inserts the author's name"); t.setContent(content); templates.add(t); return templates; } public String getPackageName() { return "A nice template package bundle"; } }
- This is the velocity file notes.vm in a directory i created named src/main/resources/plugins/template-sample-demo/
Hello $author.getName(), lorem ipsum..
- If you build and deploy the plugin to your Confluence you should be able to see the plugin in the Confluence administration area: Configuration >> Import Templates
- Some screenshots from my system showing the template preview
Form Field Markup
There are three input methods that allows the template developer to define data a user that created a new page using the template is asked for:
- Text Fields: The following code creates a text field assigned to the variable called USERNAME: @USERNAME@
- Text Areas: This code creates a 4×15 text area for a variable called COMMENT: @COMMENT|textarea(4,15)@
- Select Box: This code creates a select box with a list of three months assigned to the variable MONTHS: @MONTHS|list(Jan,Feb,Mar)@
Now lets create a sample template using variables: Edit the notes.vm template:
Hello $author.getName(), @NOTE|textarea(5,10)@ lorem ipsum..
Now build, deploy, activate the templates and take a look at the screenshots from my confluence
Tutorial Sources
*Update*: I have added some sources for a simple template bundle plugin that I have created using the Atlassian Plugin SDK.
Please feel free to view or download them from my Bitbucket repository or check them out using Mercurial/hg:
hg clone https://bitbucket.org/hascode/confluence-template-bundle-example
Resources
- Confluence Documentation: Creating a template bundle
- Confluence Documentation: Form Field Markup for Templates
- Confluence Documentation: Adding a template
- Confluence Documentation: Creating a page using a template
- Atlassian Blog: Increase wiki adoption with page templates
Tags: Confluence, example, maven, plugin, template bundle, tutorial, velocity
July 13th, 2010 at 9:49 am
Sehr cool. Das werden wir sicher mit in unser Dienstleistungsangebot aufnehmen.
Wie gut, dass wir gute Entwickler haben, die die Sache schon durchdrungen haben. Von 1 bis 5 habe ich nur “Bahnhof Kofferklau” verstanden. :-)
October 9th, 2012 at 11:46 pm
Hello,
I am using Atlassian Plugin SDK Version 3.11, will it still work?
I can’t seem to retrieve dependency for templates-framework.
Thank you,
James
October 10th, 2012 at 7:08 pm
Hi James,
that’s an interesting question therefore I’ve tested the first example from the tutorial using the plugin sdk 3.11 and got no problem there .. I’ve put the sources on my Bitbucket repository – please feel free to take a look: https://bitbucket.org/hascode/confluence-template-bundle-example
I have used a newer version of the template-framework here – 0.12 – but version 0.4 is also available and listed on atlassian’s nexus: https://maven.atlassian.com/index.html#nexus-search;quick~templates-framework
Hope i could help!
September 13th, 2016 at 12:20 am
Attempted to implement via Confluence 5, but it seems like things have changes quite a bit… Might be wrong though. Any chance of getting at 2016 update?
Love your work and thanks!
September 14th, 2016 at 9:56 am
Hi Marshall B,
simply update the amps.version property to you AMPS version – I’m currently using 6.2.6 (run atlas-version to find out) and this settings seems to be working for me:
<amps.version>6.2.6</amps.version>
March 19th, 2020 at 4:30 pm
Same problem as Marshall B but for Confluence 7 :/
Any Change of getting at 2020 update ?
Thanks <3