Rate this page:
Applicable: | This tutorial applies to Confluence Server 5.9.1 and higher. |
Level of experience: | Beginner. |
Time estimate: | It should take you less than 1 hour to complete this tutorial. |
To complete this tutorial, you should:
If you want to skip ahead or check your work when you finish, you can find the plugin source code on Atlassian Bitbucket. Alternatively, you can download the source as a ZIP archive. To clone the repository, issue the following command:
1
git clone https://bitbucket.org/atlassian_tutorial/confluence-simple-blueprint.git
In this step, you'll generate skeleton code for your plugin. Since you won't need many of the skeleton files, you also delete those unused files in this step.
To create a plugin skeleton, run the following command:
1
atlas-create-confluence-plugin
The atlas-
commands are part of the Atlassian Plugin SDK, and automate some of the work of plugin development for you.
To identify your plugin enter the following information:
group-id |
|
artifact-id |
|
version |
|
package |
|
Confirm your entries when prompted.
The SDK creates your project skeleton and puts it in a simplebp
directory.
Navigate to the simplebp
directory created in the previous step.
Delete the test directories.
Setting up blueprint testing is not part of this tutorial. Use the following command to delete the generated test skeleton:
1 2
rm -rf ./src/test/java
rm -rf ./src/test/resources/
Delete the unneeded Java class files.
A basic blueprint doesn't require you to write any Java code. Use the following command to delete the generated Java class skeleton:
1
rm -rf ./src/main/java/com/example/plugins/tutorial/confluence/simplebp/*
Import the project into your favorite IDE
At this point, you haven't actually done anything but create a skeleton plugin. You can run that skeleton in Confluence anyway. In this step, you do just that.
To start a local Confluence instance, run the following command:
1
atlas-run
This command takes a minute or so to run. It builds your plugin code, starts a Confluence instance, and installs your plugin. When the process has finished, you see many status lines on your screen concluding with something like the following:
1 2 3 4 5
[INFO] [talledLocalContainer] INFO: Starting Coyote HTTP/1.1 on http-1990
[INFO] [talledLocalContainer] Tomcat 8.x started on port [1990]
[INFO] confluence started successfully in 132s at http://localhost:1990/confluence
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit
You'll see the output includes a URL for the Confluence instance.
Log into the instance as user admin
using a password of admin
.
The Confluence Dashboard appears.
A template is an XML file that describes a page using Confluence source format. The simplest blueprints need only an XHTML template to do something cool.
In this step, use Confluence to design a simple template, and then use the Confluence Source Editor add-on to copy the source format.
In your browser where Confluence is running do the following:
Add a two column table to the page.
Name | Date |
---|---|
Enter your name here. | Enter today's date here. |
Enter a title of your page Template Content, and then click Save.
The storage format of the page opens in a new browser window. It should look like:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
<p class="auto-cursor-target"><br/></p>
<table>
<colgroup>
<col/>
<col/>
</colgroup>
<tbody>
<tr>
<th>Name</th>
<th>Date</th>
</tr>
<tr>
<td>Enter your name here.</td>
<td>Enter today’s date here.</td>
</tr>
</tbody>
</table>
<p><br/></p>
Leave it open for now.
Your plugin must include the template file in its directory structure. By convention, a template is a plugin resource so a good place to store your template is in the resource
directory. At this point, you have Confluence with the source content displayed. So, open a second Terminal window on your local machine and do the following:
simplebp
project directory.Create a templates
subdirectory in resources
.
1
mkdir src/main/resources/templates
Create a mytemplate.xml
file in your newly created templates
directory.
mytemplate.xml
file for editing.Copy the storage format into the mytemplate.xml
file and close the browser window.
1 2 3 4 5 6 7 8 9 10 11 12
<table>
<tbody>
<tr>
<th>Name</th>
<th>Date</th>
</tr>
<tr>
<td>Enter your name here</td>
<td>Enter today's date here</td>
</tr>
</tbody>
</table>
Save and close the mytemplate.xml
file.
In this step, you'll modify the generated simplebp.properties file that supports internationalization. You'll also add an image to your project to represent your blueprint in the Create dialog. In your Terminal, do the following:
src/main/resources/simplebp.properties
fileReplace the auto-generated properties with following:
1 2 3 4
my.blueprint.name=Example Blueprint
my.blueprint.title=Sample Template
my.create-link.title=My Sample Template
my.create-link.description=Create a new SimpleBP template
You can change the title of the template or the description to anything you want.
Save and close the simplebp.properties
file.
src/main/resources/images
directory.Check your work.
At this point, your project's src/main/resources directory should contain the following files:
1 2 3 4 5 6 7 8 9 10 11 12
|____atlassian-plugin.xml
|____css
| |____simplebp.css
|____images
| |____myblueprint.png
| |____pluginIcon.png
| |____pluginLogo.png
|____js
| |____simplebp.js
|____simplebp.properties
|____templates
| |____mytemplate.xml
Each blueprint relies on three component modules:
Module | Purpose |
---|---|
content-template | Describes the templates available with your plugin. You must have one of these. You can have multiple if your plugin includes multiple templates. |
blueprint | Identifies the blueprint. |
web-item | Adds the option for your blueprint to the **Create** dialog. |
To add the modules to the file, on your plugin project root, do the following:
src/main/resources/atlassian-plugin.xml
file.Add a content-template
module for your template.
1 2 3 4
<!-- Template for Blueprint -->
<content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
<resource name="template" type="download" location="/templates/mytemplate.xml" />
</content-template>
Add a blueprint
module for your template.
1 2 3 4
``` xml
<!-- Blueprint -->
<blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name"/>
```
Add a link for your template to the Create dialog.
1 2 3 4 5 6
<!-- Add to the Create Menu -->
<web-item key="create-by-sample-template" i18n-name-key="my.create-link.title" section="system.create.dialog/content">
<description key="my.create-link.description" />
<resource name="icon" type="download" location="/images/myblueprint.png" />
<param name="blueprintKey" value="my-blueprint" />
</web-item>
Check your work.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
<plugin-info>
<description>${project.description}</description>
<version>${project.version}</version>
<vendor name="${project.organization.name}" url="${project.organization.url}" />
<param name="plugin-icon">images/pluginIcon.png</param>
<param name="plugin-logo">images/pluginLogo.png</param>
</plugin-info>
<!-- add our i18n resource -->
<resource type="i18n" name="i18n" location="simplebp"/>
<!-- add our web resources -->
<web-resource key="simplebp-resources" name="simplebp Web Resources">
<dependency>com.atlassian.auiplugin:ajs</dependency>
<resource type="download" name="simplebp.css" location="/css/simplebp.css"/>
<resource type="download" name="simplebp.js" location="/js/simplebp.js"/>
<resource type="download" name="images/" location="/images"/>
<context>simplebp</context>
</web-resource>
<!-- Template for Blueprint -->
<content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
<resource name="template" type="download" location="/templates/mytemplate.xml" />
</content-template>
<!-- Add to the Create Menu -->
<web-item key="create-by-sample-template" i18n-name-key="my.create-link.title" section="system.create.dialog/content">
<description key="my.create-link.description" />
<resource name="icon" type="download" location="/images/myblueprint.png" />
<param name="blueprintKey" value="my-blueprint" />
</web-item>
<!-- Blueprint -->
<blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name"/>
</atlassian-plugin>
Save and close your atlassian-plugin.xml
file.
Now, you are ready to build your plugin and see it in action.
Rebuild your plugin from the command line using the following command that triggers QuickReload.
1
atlas-package
Make sure you are still in the Demonstration Space.
Now that you know how to create blueprint plugin you’re ready to take it to the next level. Check out the tutorial for building an intermediate blueprint plugin or try to write a Confluence Space blueprint.
Rate this page: