Confluence blueprints allows users to create new pages based on predefined content. Using the Create dialog, you can view the blueprints available in an installation.
As plugin developers, you can hook into the Create dialog to add your own blueprints. With Confluence 5.3 and higher, you can also write Space blueprints to provide users a way to create new spaces.
Basic blueprints can simply help create new pages with predefined content from a template, which can be static or dynamic. Blueprints don't limit you to just predefining content and it is really up to your imagination. To assist users in creating certain types of documents, you can take user input in a dialog wizard and prepopulate content, settings, or just develop templates with placeholder text (only visible in the editor).
To build a simple blueprint plugin, see the Write a simple Confluence blueprint plugin tutorial.
If you want to see some example code, the Hello blueprint contains a space blueprint. The source code is available on Atlassian Bitbucket: https://bitbucket.org/atlassian/hello-blueprint.
To clone the repository, run the following command:
git clone https://bitbucket.org/atlassian/hello-blueprint.git
Hello Blueprint was last tested with Confluence 5.10.1 and Atlassian SDK 6.2.6.
This section introduces you to the concepts you need to know to develop a Confluence blueprint. It contains the following topics:
Confluence blueprints are built with the following plugin module types.
Identifies the blueprint and binds it to a Create dialog option.
Describes the templates available with your plugin. You must have one of these; you can have multiple if your plugin includes multiple templates.
Adds the option for your blueprint to the Create dialog.
You must specify a section of and have a element with name "" specified, where is the blueprint module key.
The icon resource should be 200 x 150 pixel PNG icon resource representing the blueprint icon.
|Define a dialog wizard for users to input data during page creation|
The following code illustrates the minimum required for a Confluence blueprint to appear in the Create dialog:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<resource type="i18n" name="i18n" location="i18n"/> <content-template key="myplugin-template"> <resource name="template" type="download" location="xml/basic.xml"/> </content-template> <web-item key="blueprint-item" i18n-name-key="my.plugin.title" section="system.create.dialog/content"> <description key="my.plugin.description"/> <resource name="icon" type="download" location="images/my-blueprint-icon.png"/> <param name="blueprintKey" value="myplugin-blueprint"/> </web-item> <blueprint key="myplugin-blueprint" index-key="myplugin-index"> <content-template ref="myplugin-template"/> </blueprint>
Note that this assumes that you have an file and file in your plugin resources directory.
Each blueprint depends on a template with predefined content, which we refer to as content templates. Any markup that can go into a Confluence page can go in your template. The template content itself must be in an XML file defined in the element. The file can contain any valid Confluence storage format markup. The template file can live anywhere in your plugin project, by convention, you should place it in a subdirectory of the folder. For example, you might create a file with the following content:
Do the following:
This is particularly useful if you want to use macros or page layouts in your template.
Content templates can provide instructional text to the user, which is a placeholder only visible in the editor. After users click the placeholder to start typing the placeholder text is replaced.
The purpose of such text is to guide the user in the information that the template requires. You can also use instructional text to trigger a prompt for user selection.
In the following example, we have two placeholders:
1 2 3 4 5 6 7 8 9 10 11 12
<table> <tbody> <tr> <th>User</th> <th colspan="1">Phone</th> </tr> <tr> <td><ac:placeholder ac:type="mention">usermention</ac:placeholder></td> <td><ac:placeholder><at:i18n at:key="my.key"/></ac:placeholder></td> </tr> </tbody> </table>
The user will see this in the editor:
Each blueprint type has an index page automatically created for each space. An index page is like a summary page which lists all the blueprints of that type in that space. It essentially relies on Confluence labels to be applied to the pages created via blueprints, which is specified by the attribute on the module.
Index pages are created when the first blueprint of that type is created for a space, for example, when the first Meeting Note blueprint page is created in a space, the Meeting Notes index page is also created. A shortcut to the index page is also created by default in the Space sidebar.
By default, the index page for blueprints includes a button to create the blueprint and a table listing out the blueprints of that type in the space.
To customize and override this default, specify an attribute on the module and reference a content template in your plugin. For example:
1 2 3 4 5 6 7 8 9
<blueprint key="myplugin-blueprint" index-key="myplugin-index" index-template-key="myplugin-index-template"/> <content-template ref="myplugin-template"/> </blueprint> <content-template key="myplugin-index-template" i18n-name-key="myplugin.templates.index.name"> <resource name="template" type="download" location="xml/index.xml"/> </content-template>
Note that by default index page titles are the same as the blueprint name (that appears in the Create dialog). To override the title, specify an attribute in the element.
You specify the internationalized plugin name and description with the keys. These keys appear in the component modules that you use to define your blueprint. Specify these keys in the file.
1 2 3 4
my.plugin.title=My Blueprint Plugin Title my.plugin.description=This is a description of my plugin myplugin.templates.content.name=My Blueprint Content Template myplugin.templates.index.name=My Blueprint Index Template
You must reference this file in your descriptor using:
<resource type="i18n" name="i18n" location="i18n"/>
If you generated your plugin with an command, the generation creates this file and the necessary references in the file.
In your blueprint templates, you can use elements for translation strings. The key refers to a key in your plugin i18n file.
<p><at:i18n at:key="my.blueprints.string" /></p>
Translations of blueprint templates occur when the blueprint is created by a user. However, if the user customizes the blueprint template, it is translated in the globally configured language and then subsequent creations of that blueprint are bound to that language.
After you install a blueprint plugin into Confluence, you can test it using the following steps: