Writing Soy Templates in Your Plugin
This tutorial applies to Confluence 4.3.
Level of experience:
|Status||LEGACY This tutorial applies to Confluence versions that have reached end of life.|
- Extending the Confluence Insert Link Dialog
- What are Closure Templates? (Google developer documentation)
- Closure Template Concepts (Google developer documentation)
In order to do this, you will create a very simple Confluence plugin. Your plugin will consist of the following components:
- Plugin descriptor – to enable the plugin module in Confluence.
- A Soy template.
- A little internationalisation
All these components will be contained within a single JAR file. Each component is further discussed in the examples below.
The source code of the plugin used in this tutorial is available in bitbucket. You can browse the source code here: confluence-tutorial-soy-templates.
What are Soy templates?
Step 1. Create the plugin project
Begin by creating a new Confluence plugin. You can use the Atlassian Plugin SDK to do this. (See Set up the Atlassian Plugin SDK and Build a Project for full instructions.)
In a command window, go to the directory where you want to create your plugin project, and type:
You will be prompted to enter two values, the group ID and artifact ID. For this tutorial, we used the following values:
- Group ID: com.appfusions.confluence.plugins
- Artifact ID: confluence-tutorial-soy-templates
Step 2. Create a Soy template
Create a new Soy template at src/main/resources/template.soy:
Each Soy file needs a namespace declaration at the top of the file. It must be declared before any templates are declared.
In this case, we have created a new Confluence.Templates.SoyTutorial namespace for our templates and added a template which displays an AUI-style table containing a number of attributes that a Confluence page is likely to possess.
For templates that need parameters, these must be declared in JavaDoc style immediately before the template:
Parameters use this syntax within the template:
For internationalisation, use
Here we are doing four things:
- Getting the first .page-metadata element if it exists.
- Creating an object containing only the AJS.params items that we are interested in.
- Passing these items –
selectedAjsParams– into the template –
Confluence.Templates.SoyTutorial.listSelectedAjsParams– to render the template into HTML.
- Appending the resulting HTML into the browser after the page metadata section.
Step 4. Edit the atlassian-plugin.xml file
You must now register the plugin module in your plugin descriptor,
Add the following code to your
atlassian-plugin.xml file between the
<atlassian-plugin> tags, but below the
<plugin-info> tag group.
Let's break down that XML code, by looking at the web resource module, transformers and resources in the code.
The web resource module
In the code example, the web-resource module (line) has 2 attributes:
- key="view-metadata" sets an internal name for the new item.
- name="View metadata from AJS.params" defines the default name of the item.
In the code example, there are two transformation code blocks:
- The first transformation module performs the internationalisation work.
Step 5. Add new resource files and internationalisation
To add new resource files and internationalisation, add a new file in the resources directory of your plugin, called
confluence-tutorial-soy-templates.properties, and include these lines of code:
The above keys are used in the Soy template. For example:
Additionally, add a reference the resource file in the
atlassian-plugin.xml file – add this line of code above the
<web-resource> code block:
This accesses your
confluence-tutorial-soy-templates.properties file and retrieves the text for our button label.
If you would like to know more about internationalisation, see the Confluence documentation on the topic.
Step 6. Build, install and run the plugin
Go to the root directory in your plugin project – this is the directory that contains the
pom.xml file. Type the atlas-run command, to compile the plugin project and then launch a local instance of Confluence.
Once Confluence has loaded:
Go to your web browser and access your local instance with this URL:
- Log in with username "admin" and password "admin".
- Browse to a page in the Demonstration space
Each page will now have a table above the page content, containing a selection of metadata – this has been rendered client-side using Soy templates.