Introduction to Blueprints
A Confluence Blueprint gives users a way to create new pages based on pre-defined content. Users view the blueprints available in an installation through the Create dialog. As plugin developers you can hook into the Create dialog to add your own blueprints. With Confluence 5.3+ you can now also write Space Blueprints to provide users a way to create new spaces.
Basic blueprints can simply help create new pages with pre-defined content from a template, static or dynamic. Blueprints don't limit you to just pre defining content and is really up to your imagination. You can take user input in a dialog wizard and pre populate content, settings or just develop templates with placeholder text (only visible in the editor) to assist users creating certain types of documents.
See the Write a simple Confluence Blueprint plugin tutorial to build a simple blueprint plugin.
If you want to see some example code, the Hello Blueprint now contains a space blueprint. The source code is available on Atlassian Bitbucket: https://bitbucket.org/atlassian/hello-blueprint. To clone the repository, issue the following command:
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 develop a Confluence Blueprint. It contains the following topics:
Plugin module types used in blueprints
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
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:
Note this assumes you have a
i18n.properties file and
basic.xml file in your plugin's resources directory.
Each blueprint depends on a template with pre-defined 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
content-template element. The file can contain any valid Confluence storage format markup. The template file can live anywhere in your plugin project, by convention though, you should place it in a subdirectory of the src/main/resources folder. For example, you might create a
src/main/resources/templates/basic.xml file with the following content:
Content templates can provide instructional text to the user, which is a placeholder only visible in the editor. Once users easily click on the placeholder to start typing and the placeholder text will be replaced. The purpose of such text, is to guide the user in the information that is required for the template. You can also use instructional text to trigger an
@mention prompt for user selection. In the following example we have two placeholders, one that is static text (replaced by internationalisation) and the other which will trigger an
@mention prompt when clicked.
The user will see this in the editor:
Each Blueprint type will automatically have an index page 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
index-key attribute on the
blueprint module. Index pages are created when the first blueprint of that type is created for a space e.g. when the first Meeting Note blueprint page is created in a space, the Meeting Notes index page will also be 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. If you would like to customize and override this default, you can do this by specifying a
index-template-key attribute on the
blueprint module and referencing a content template in your plugin. For example:
Note that by default, index page titles are the same as the Blueprint name (that appears in the Create dialog). If you'd like to override the title, in the
blueprint element specify an attribute "
Internationalization, translation, and blueprints
You specify the internationalized plugin name and description with the i18n keys. These keys appears in the component modules you use to define your blueprint. You specify these keys in the
You must reference this file in your
atlassian-plugin.xml descriptor using:
If you generated your plugin with an
atlas-create-product-plugin command, the generation creates this file for you and the necessary references in the
In your blueprint templates, you can use at:i18n elements for translation strings. The key refers to a key in your plugin's i18n
Translations of Blueprint templates occur when the Blueprint is created by the user. However, if a user customizes the Blueprint template, it is translated in the globally configured language and then subsequent creations of that Blueprint will be bound to that language.
Testing your Confluence Blueprint
Once you install a blueprint plugin into Confluence, you can test it using the following steps:
- Open Confluence in your browser.
- Press the Create button.
Confluence displays the Create dialog.
- Locate your new blueprint in the dialog and select it.
Selecting this item and pressing next should take you to the Editor screen, pre-loaded with your template.
- Saving the new page to view it.
An index page should be created for you, with a shortcut to it in the Space sidebar. Visit the index page and make sure your newly created page appears there. To customize your Blueprint as a space admin, go to Space Tools (in the sidebar) And choose Content Tools > Templates.