How to create a Template Bundle Plugin in Confluence

July 12th, 2010 by

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

  1. Create a new Maven project using the following command on the console or your IDE e.g. Eclipse with the Maven plugin installed
  2. 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>http://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>http://www.hascode.com</url>
     </organization>
     <repositories>
     <repository>
     <id>maven.repo.remote</id>
     <url>http://www.ibiblio.org/maven</url>
     </repository>
     </repositories>
     
    </project>
  3. 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="http://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>
  4. 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";
     }
     
    }
  5. 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";
     }
     
    }
  6. 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..
  7. 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
  8. 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

Tags: , , , , , ,

3 Responses to “How to create a Template Bundle Plugin in Confluence”

  1. Martin Seibert Says:

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

  2. James Star Says:

    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

  3. micha kops Says:

    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!

Leave a Reply

Please leave these two fields as-is:

Protected by Invisible Defender. Showed 403 to 81,014 bad guys.

Search
Categories