Creating and shipping a Template as Confluence Plugin

This page describes how to create a new template and then ship it as a standalone Confluence plugin.

Prerequisites

A recent version (>= 2.0) of the Scroll Wiki Exporter product that you want to create the template for.
The Scroll base plugin that provides the template extension points for Scroll products. You can download it here: scroll-base-1.1.jar

Creating the template

To create the template you will need to do the following steps:

Place the files you want to include in your template (CSS, images ...) into the correct folder hierarchy.
Create the plugin descriptor containing the template definition.
Package everything together.

Organizing the files

You should create a new folder for your template somewhere. Into this directory place all files that should be included in the template. You may place all files freely into sub-directories if you wish to. In this example we place all images into the "images" folder and the velocity file for the page (see below) into "vm", as shown in the image to the left. Our CSS styles are stored in the top level file "style.css"

Please note that the following page.vm file is only suitable for the EclipseHelp exporter. For other exporters please see the respective documentation space.

The following shows the contents of the page.vm file. Simply copy the text into a new text file and save it as "page.vm" somewhere inside your template plugin folder (e.g. in the "vm" directory).
Please note that you need to adapt the page.vm file and add your custom CSS files. The modified page.vm file must be registered as resource of type "template-part", see below.

#if($renderStart)
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>$stringEscapeUtils.escapeHtml($element.Title)</title>

    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <meta content="Scroll Wiki EclipseHelp Exporter" name="generator"/>

    <link type="text/css" rel="stylesheet" href="css/style.css" />
</head>
<body>
    <div class="container">
        <div class="header"></div>

        <div id="$encodingUtils.safeUrlEncode($element.anchorId)" class="content">
            <h1>$stringEscapeUtils.escapeHtml($element.Title)</h1>
#else
        </div>
    
        <div class="footer"></div>
    </div>
</body>
</html>
#end

Writing the plugin descriptor file

The following shows the contents of the "atlassian-plugin.xml" file. Simply copy the text into a new text file and save it as "atlassian-plugin.xml" in the root directory of your template plugin.

<atlassian-plugin key="com.k15t.scroll.external.templates" name="Example templates" plugins-version="2">
    <plugin-info>
        <description>This plugins contains some example templates.</description>
        <version>1.0</version>
        <vendor name="K15t Software GmbH" url="http://www.k15t.com" />
    </plugin-info>

    <scroll-template key="my-first-template" name="My first template">
        <resource type="template-part" name="page" location="vm/page.vm" />
        <resource type="static-resource" name="css/style.css" location="style.css" />
        <resource type="static-resource" name="logos/logo.gif" location="images/logo.gif" />

        <param name="copyDefaultResources">true</param>
        <param name="compatibleExporters">com.k15t.scroll.scroll-eclipsehelp:eclipsehelp-exporter</param>
    </scroll-template>    
</atlassian-plugin>

The atlassian-plugin.xml file tells Confluence what your plugin contains.

In the XML element atlassian-plugin you need to adapt two attributes:

key contains the plugin key. This one identifies the plugin and must be unique. Usually one use the organization domain name in reverse direction for that, but it is your choice. Just make sure it doesn't contain special characters and that it will not conflict with other plugins.
name contains the human readable name of the plugin.
plugins-version must always be set to "2".

In the XML element plugin-info you need to enter some metadata about your plugin:

The description may also contain longer texts.
The version should be of the form x, x.y or x.y.z with x,y and z being numbers.
You may enter your organization's name and website URL in the attributes of the vendor element.

The scroll-template element defines your new template:

key contains the module key. This one identifies the plugin module and must be unique within this plugin. You should only use letters and "-" characters here.
name contains the human readable name of your template. This text will be displayed on the export dialog when choosing a template.

Inside the scroll-template element you can place multiple resource and param elements.

Template Resources

Using template resources you can add files to your template, e.g images and CSS:

The type attribute must always be "static-resource" for such files.
The name attribute defines where the file will be placed inside the export archive and may also contain relative paths. Example: Considering the example file from above, the style.css file would need to reference the logo file with the location "logos/logo.gif".
The location attribute defines where the file is located inside your Confluence plugin. Example: The CSS file in the example above must be placed on the top level of the plugin archive, the image file inside the folder "images".

Template Parameters

Template parameters allow you to further customize your template. Currently only these parameters are supported:

Parameter name Parameter value

copyDefaultResources Can be either true or false. If set to true, the resource files of the default template shipped with the Scroll Wiki Exporter product are included when exporting with your template. This parameter is optional and defaults to true if not specified.

compatibleExporters Must contain the full keys of the exporters that this template is compatible with. This also defines for which exporters the template appears on the export UI. The full exporter keys for the Scroll Wiki Exporter products are com.k15t.scroll.scroll-pdf:pdf-exporter, com.k15t.scroll.scroll-html:html-exporter, com.k15t.scroll.scroll-eclipsehelp:eclipsehelp-exporter and so on. The template from the example above is only compatible with (and displayed on the export UI of) the EclipseHelp exporter.Separate multiple values with a comma. If you don't specify this parameter, your template will be marked as compatible with all exporters (even if the template's contents are not actually compatible).

Packaging the plugin

To finally complete your template plugin you only need to use any ZIP tool to create a ZIP file of the plugin contents. Make sure to include all files inside your template directory, but not the template directory itself. See the picture above for the correct folder hierarchy inside the archive. Then make sure to rename the filename extension to "jar" before uploading your template plugin.