<img height="1" width="1" style="display:none;" alt="" src="https://px.ads.linkedin.com/collect/?pid=299788&amp;fmt=gif">

Introduction to Confluence Blueprints

Confluence, Atlassian, Atlassian Tools, Software Solutions

By Robert Hall

This post will introduce Confluence Blueprints and how to build them using a simple example. As with previous posts on Atlassian plugin development--here and here--this uses the Atlassian SDK to develop a plugin (Add-On) that implements a Blueprint. Blueprints are a relatively new Confluence feature--in essence, they combine the power of Atlassian plugins with the dynamic content of templates.

Blueprints?

Blueprints in Confluence are a set of page templates packaged in a plugin that allow the user to create, organize and manage content. Consider spaces that have sets of pages with similar, repeated content. Blueprints provide an easy means to keep the base content in one place (a template), create multiple pages using it, and customize each either through wizards that collect user input, the Confluence page editor, or from other sources (external systems, other Confluence pages, etc--data pulled in via the plugin). This post will examine a 'simple sample' Blueprint that is deployed in a plugin and uses wizard screens to allow the user to select the template they wish to utilize and provide customization data. Note that this post focuses on Confluence Page Blueprints--since Confluence 5.3, Space Blueprints have also been supported. Space Blueprints will be the subject of a future post. Note also that like plugins, Blueprints are used only with on-premise installed Confluence, not the On-Demand version.

Build Process

Building a Confluence Blueprint is much the same as building a Confluence plugin. As was shown here, use the Atlassian SDK command 'atlas-create-plugin' to create the basic structure of your project--a pom.xml file, atlassian-plugin.xml, and some placeholder generated Java classes.

Configuration

The basic structure of a Blueprint project is that of a plugin project created with the Atlassian SDK. The key distinctions are primarily entries in atlassian-plugin.xml. A key declaration is the blueprint tag. In our SimpleSample example we have:
[html]
&amp;amp;amp;lt;!--
blueprint groups together the main blueprint concepts:
index-key: (required) this is the name of the label that will be added to all content created from this blueprint, and used to
bring this content together on the index page.
index-template-key: (optional) this is the moduleKey of the &amp;amp;amp;lt;content-template&amp;amp;amp;gt; that will be used to create an index page.
If none is provided, a default template will be used.
create-result: (optional) can be assigned the value of &amp;amp;amp;quot;view&amp;amp;amp;quot; or &amp;amp;amp;quot;edit&amp;amp;amp;quot;.
&amp;amp;amp;quot;view&amp;amp;amp;quot;: cause the editor to be bypassed - the required content will be created and the user immediately redirected to viewing it
&amp;amp;amp;quot;edit&amp;amp;amp;quot;: user will be sent to the editor pre-filled
i18n-index-title-key: (optional) the i18n key for the title of the index page. Defaults to create-dialog-web-item name if none specified.
--&amp;amp;amp;gt;
&amp;amp;amp;lt;blueprint key=&amp;amp;amp;quot;simplesample-blueprint&amp;amp;amp;quot; name=&amp;amp;amp;quot;Simple Sample Blueprint&amp;amp;amp;quot; i18n-name-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.name&amp;amp;amp;quot;
create-result=&amp;amp;amp;quot;edit&amp;amp;amp;quot;
index-template-key=&amp;amp;amp;quot;simplesample-blueprint-index&amp;amp;amp;quot;
i18n-index-title-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.index.page.title&amp;amp;amp;quot;
index-key=&amp;amp;amp;quot;simplesample-blueprint&amp;amp;amp;quot;
how-to-use-template=&amp;amp;amp;quot;Confluence.Blueprints.Hello.howToUse&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;!--
The content-template-key element(s) are the moduleKey(s) of the &amp;amp;amp;lt;content-template&amp;amp;amp;gt;(s) that will be used to
create a page / content from. These elements are required so that the templates can be edited from the
Space/Site Templates-admin screens.
--&amp;amp;amp;gt;
&amp;amp;amp;lt;content-template ref=&amp;amp;amp;quot;simplesample-blueprint-content-template-a&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;content-template ref=&amp;amp;amp;quot;simplesample-blueprint-content-template-b&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;!--
The dialog-wizard element defines a set of Wizard pages that will be shown when the User selects this
Blueprint. Pages will be shown to the user in the order they are defined, but this can be changed in the
Wizard JavaScript hooks (see simplesample-blueprint-wizard.js).
--&amp;amp;amp;gt;
&amp;amp;amp;lt;dialog-wizard key=&amp;amp;amp;quot;file-list-blueprint-wizard&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;!--
dialog-page defines a single page of the Wizard. This page can contain a description that is displayed
at the right-hand-side of it. This element contains the following attributes:
- id - the id of this page, used with JavaScript hooks
- template-key - the fully-qualified path to a Soy template provided by this plugin (see web-resource)
- title-key - the i18n key for the title that will be displayed at the top of the Wizard page
- description-header-key - (optional) if specified, the i18n key for the heading above the description
- description-content-key - (optional) if specified, the i18n key for the description content. This
is required for the Description panel to appear in the page.
- last - (optional) if set to &amp;amp;amp;quot;true&amp;amp;amp;quot;, the Wizard will be complete when this page is submitted. This is
useful if the Wizard can have multiple paths. The last defined dialog-page gets this value set
to &amp;amp;amp;quot;true&amp;amp;amp;quot; by default.
--&amp;amp;amp;gt;
&amp;amp;amp;lt;dialog-page id=&amp;amp;amp;quot;choosePathPageId&amp;amp;amp;quot;
template-key=&amp;amp;amp;quot;Confluence.Blueprints.Hello.choosePathForm&amp;amp;amp;quot;
title-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.choose.title&amp;amp;amp;quot;
description-header-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.choose.heading&amp;amp;amp;quot;
description-content-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.choose.description&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;dialog-page id=&amp;amp;amp;quot;helloFormPageId&amp;amp;amp;quot;
template-key=&amp;amp;amp;quot;Confluence.Blueprints.Hello.helloFormPage&amp;amp;amp;quot;
title-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.hello.title&amp;amp;amp;quot;
description-header-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.hello.heading&amp;amp;amp;quot;
description-content-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.hello.description&amp;amp;amp;quot;
last=&amp;amp;amp;quot;true&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;dialog-page id=&amp;amp;amp;quot;searchFormPageId&amp;amp;amp;quot;
template-key=&amp;amp;amp;quot;Confluence.Blueprints.Hello.searchFormPage&amp;amp;amp;quot;
title-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.search.title&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;dialog-page id=&amp;amp;amp;quot;doSearchPageId&amp;amp;amp;quot;
template-key=&amp;amp;amp;quot;Confluence.Blueprints.Hello.doSearchPage&amp;amp;amp;quot;
title-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.dialog.search.title&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;/dialog-wizard&amp;amp;amp;gt;
&amp;amp;amp;lt;/blueprint&amp;amp;amp;gt;
[/html]
Key aspects of the blueprint declaration are the index-template-key and index-key which identify the page used to generate an index page (a page in the space with a listing of pages created by the blueprint); the content-template references which are used to refer to the content template pages used -- this example has two such pages; and the dialog-wizard declaration. The dialog-wizard is composed of one or more dialog pages -- the dialogs are used to guide the user when they create a page and gather information from the user used in the generated pages.
The content-template declarations for the two pages and index page are as follows:
[html]
&amp;amp;amp;lt;!--
content-template defines an XML resource in Confluence Storage-Format.
key: (required) referenced by the respective &amp;amp;amp;lt;blueprint&amp;amp;amp;gt;
i18n-name-key: (optional) used only when viewing this plugin in the Plugin Manager
description: (optional) used only when viewing this plugin in the Plugin Manager
resource: (required) the XML file containing the template content
context-provider: (optional) if present, will provide extra key-value pairs to be substituted against
&amp;amp;amp;lt;at:var&amp;amp;amp;gt; instances in the template
--&amp;amp;amp;gt;
&amp;amp;amp;lt;content-template key=&amp;amp;amp;quot;simplesample-blueprint-content-template-a&amp;amp;amp;quot;
i18n-name-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.content.template.a.name&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;description key=&amp;amp;amp;quot;confluence.simplesample.blueprint.content.template.a.description&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;resource name=&amp;amp;amp;quot;template&amp;amp;amp;quot; type=&amp;amp;amp;quot;download&amp;amp;amp;quot; location=&amp;amp;amp;quot;com/isostech/confluence/plugins/simplesample_blueprint/xml/content-template-a.xml&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;context-provider class=&amp;amp;amp;quot;com.isostech.confluence.plugins.simplesample_blueprint.SimpleSampleContextProvider&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;/content-template&amp;amp;amp;gt;
&amp;amp;amp;lt;content-template key=&amp;amp;amp;quot;simplesample-blueprint-content-template-b&amp;amp;amp;quot;
i18n-name-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.content.template.b.name&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;description key=&amp;amp;amp;quot;confluence.simplesample.blueprint.content.template.b.description&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;resource name=&amp;amp;amp;quot;template&amp;amp;amp;quot; type=&amp;amp;amp;quot;download&amp;amp;amp;quot; location=&amp;amp;amp;quot;com/isostech/confluence/plugins/simplesample_blueprint/xml/content-template-b.xml&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;/content-template&amp;amp;amp;gt;
&amp;amp;amp;lt;content-template key=&amp;amp;amp;quot;simplesample-blueprint-index&amp;amp;amp;quot;
i18n-name-key=&amp;amp;amp;quot;confluence.simplesample.blueprint.index.template.name&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;description key=&amp;amp;amp;quot;confluence.simplesample.blueprint.index.template.description&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;resource name=&amp;amp;amp;quot;template&amp;amp;amp;quot; type=&amp;amp;amp;quot;download&amp;amp;amp;quot; location=&amp;amp;amp;quot;com/isostech/confluence/plugins/simplesample_blueprint/xml/index.xml&amp;amp;amp;quot;/&amp;amp;amp;gt;
&amp;amp;amp;lt;/content-template&amp;amp;amp;gt;
[/html]

Example

In this example, the 'Simple Sample Blueprint', a Blueprint plugin is used to enable creating Confluence pages with content taken from one or more templates. The pages are created via a wizard that collects attributes that will be used to customize the templates, as well as pulling data from the plugin, such as the date or formatted text.
After building a Jar file for the Blueprint Plugin, it is deployed to Confluence as follows:
Login to the Jira instance via a web browser (usually localhost:2990/jira) with administrative user rights and install the plugin (in Adminstration->Manage Add Ons->).
Atlassian Plugin Development
After deploying, the Blueprint plugin is now available for use. In a given space, select 'Create' to create a new page and select 'Simple Sample Blueprint'. This will launch a multi-page wizard to guide the user.
atlassian plugin development
The first page of the wizard becomes available, and is simply informative about the SimpleSample Blueprint.
atlassian plugin development
The second page in the wizard gives the user a choice in path -- to create the Simple Sample template or a search page.
atlassian plugin development
The third page of the wizard collects information from the user such as the page title, user name, and a selection of which template to use:
atlassian plugin development
The third page of the wizard has the user input data entered and selected.
atlassian plugin development
Once the wizard completes, the blueprint plugin uses the selected template and user data with the resulting template opening in the Confluence editor. Several artifacts visible in this template example will be discussed below.
atlassian plugin development
The saved page looks as follows:
atlassian plugin development
The index page shows this list of pages, including the new one:
atlassian plugin development
As can be seen in the result, the title the user entered is used for the page and the user name is displayed. Also displayed is the date and other data, including a list with checkboxes.
To insert the title, user name and current date into the page, the macro syntax on the template is as follows:
[html]
&amp;amp;amp;lt;ac:macro ac:name=&amp;amp;amp;quot;info&amp;amp;amp;quot;&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:parameter ac:name=&amp;amp;amp;quot;title&amp;amp;amp;quot;&amp;amp;amp;gt;&amp;amp;amp;lt;at:var at:name=&amp;amp;amp;quot;panelTitle&amp;amp;amp;quot; /&amp;amp;amp;gt;&amp;amp;amp;lt;/ac:parameter&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:rich-text-body&amp;amp;amp;gt;
&amp;amp;amp;lt;p&amp;amp;amp;gt;User: &amp;amp;amp;lt;at:var at:name=&amp;amp;amp;quot;name&amp;amp;amp;quot; /&amp;amp;amp;gt;&amp;amp;amp;lt;/p&amp;amp;amp;gt;
&amp;amp;amp;lt;p&amp;amp;amp;gt;&amp;amp;amp;lt;at:var at:name=&amp;amp;amp;quot;friendlyDate&amp;amp;amp;quot; /&amp;amp;amp;gt;&amp;amp;amp;lt;/p&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:rich-text-body&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:macro&amp;amp;amp;gt;
[/html]
The variable 'panelTitle' was taken from a wizard form variable with JavaScript, as was the user name in the variable 'name'. The date in variable 'friendlyDate' came from a Java method in one of the plugin Java classes that gets the current date.
For the list with checkboxes, the macro syntax is:
[html]
&amp;amp;amp;lt;ac:task-list&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-status&amp;amp;amp;gt;incomplete&amp;amp;amp;lt;/ac:task-status&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-body&amp;amp;amp;gt;Task 1&amp;amp;amp;lt;/ac:task-body&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-status&amp;amp;amp;gt;incomplete&amp;amp;amp;lt;/ac:task-status&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-body&amp;amp;amp;gt;Task 2&amp;amp;amp;lt;/ac:task-body&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-status&amp;amp;amp;gt;incomplete&amp;amp;amp;lt;/ac:task-status&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-body&amp;amp;amp;gt;Task 3&amp;amp;amp;lt;/ac:task-body&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-status&amp;amp;amp;gt;incomplete&amp;amp;amp;lt;/ac:task-status&amp;amp;amp;gt;
&amp;amp;amp;lt;ac:task-body&amp;amp;amp;gt;Task 4&amp;amp;amp;lt;/ac:task-body&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:task&amp;amp;amp;gt;
&amp;amp;amp;lt;/ac:task-list&amp;amp;amp;gt;
[/html]
Additional artifacts include 'placeholder' fields for gathering user input on the page while editing. These are called out with:
[html]
&amp;amp;amp;lt;ac:placeholder&amp;amp;amp;gt;This is an example of instruction text that will get replaced when a user selects the text and begins typing.&amp;amp;amp;lt;/ac:placeholder&amp;amp;amp;gt;
[/html]

Conclusions

This post just touched on some of the basics of what can be done with Confluence Blueprints. The Blueprint paradigm provides yet another powerful tool in the Atlassian developer toolbox by providing a means of generating dynamic content and flexible presentation for Confluence pages.

Links

Working with Blueprints
Confluence Blueprints Development Guide
Confluence Blueprints Tutorial

TAGS: Confluence, Atlassian, Atlassian Tools, Software Solutions

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Subscribe to Our Newsletter

Recent Blog Posts