Write an intermediate blueprint plugin

Overview of the tutorial

If you successfully completed Write a simple Confluence blueprint plugin you have a functional but basic blueprint plugin. In this tutorial, you create a blueprint that populates its template with data. You can populate a template by implementing a ContextProvider class in your plugin. You can also populate a template by creating an interactive wizard using JavaScript. In this tutorial, you do both.

Before you begin

Before starting this tutorial, be sure you've completed Write a simple Confluence blueprint plugin tutorial first.

Plugin source

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, run the following command:

1

git clone https://bitbucket.org/atlassian_tutorial/confluence-populated-blueprint.git

Step 1. Add a variable and some instructional text to the template 

In this step, you'll add a variable to the template you created in the Write a simple Confluence blueprint plugin.  If you don't have that code, you can can download the source as a ZIP archive of the project to use.

1. Open Terminal and navigate to the root of the project.

2. In the src/main/resources/templates/mytemplate.xml file replace the Enter your name here text with a variable:

   1

   <td><at:var at:name="vName"/></td>

3. To make it instructional, add a placeholder around the Enter today's date here text.

   1

   <td><ac:placeholder>Enter today's date here</ac:placeholder></td>

   The following code snippet shows the table with the previous example added.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

   <table>
     <tbody>
       <tr>
         <th>Name</th>
         <th>Date</th>
       </tr>
       <tr>
         <td><at:var at:name="vName"/></td>
         <td><ac:placeholder>Enter today's date here</ac:placeholder></td>
       </tr>
     </tbody>
   </table>

4. Save and close the file.

1
<at:var at:name="myNameWithSomeXhtmlInIt" at:rawxhtml="true"/>

Step 2. Add a new dependency to the pom.xml file

In this step, you'll add new dependencies to your pom.xml file. The confluence-create-content-plugin provides the blueprint API. To interact with the API, you need to add a dependency in your project's pom.xml.

1. In the pom.xml file in your project's root, add dependency element to the confluence-create-content-plugin artifact. 
   Make sure you added it in the <dependencies/> section.

   1
   2
   3
   4
   5
   6

   <dependency>
      <groupId>com.atlassian.confluence.plugins</groupId>
      <artifactId>confluence-create-content-plugin</artifactId>
      <version>${create.content.version}</version>
      <scope>provided</scope>
   </dependency>

2. Scroll to file's end and find the <properites/> block.

3. Add the create-content-version  element.

   1

   <create.content.version>7.0.0</create.content.version>

   Here is example of the whole pom.xml file, including the previous element.

   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
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <groupId>com.example.plugins.tutorial.confluence.simplebp</groupId>
       <artifactId>simplebp</artifactId>
       <version>1.0-SNAPSHOT</version>
       <organization>
           <name>Example Company</name>
           <url>http://www.example.com/</url>
       </organization>
       <name>simplebp</name>
       <description>This is the com.example.plugins.tutorial.confluence.simplebp:simplebp plugin for Atlassian Confluence.</description>
       <packaging>atlassian-plugin</packaging>
       <dependencies>
           <dependency>
               <groupId>junit</groupId>
               <artifactId>junit</artifactId>
               <version>4.10</version>
               <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>com.atlassian.confluence</groupId>
               <artifactId>confluence</artifactId>
               <version>${confluence.version}</version>
               <scope>provided</scope>
           </dependency>
           <dependency>
               <groupId>com.atlassian.confluence.plugins</groupId>
               <artifactId>confluence-create-content-plugin</artifactId>
               <version>${create.content.version}</version>
               <scope>provided</scope>
           </dependency>
           <dependency>
               <groupId>com.atlassian.plugin</groupId>
               <artifactId>atlassian-spring-scanner-annotation</artifactId>
               <version>${atlassian.spring.scanner.version}</version>
               <scope>compile</scope>
           </dependency>
           <dependency>
               <groupId>com.atlassian.plugin</groupId>
               <artifactId>atlassian-spring-scanner-runtime</artifactId>
               <version>${atlassian.spring.scanner.version}</version>
               <scope>runtime</scope>
           </dependency>
           <dependency>
               <groupId>javax.inject</groupId>
               <artifactId>javax.inject</artifactId>
               <version>1</version>
               <scope>provided</scope>
           </dependency>
           <!-- WIRED TEST RUNNER DEPENDENCIES -->
           <dependency>
               <groupId>com.atlassian.plugins</groupId>
               <artifactId>atlassian-plugins-osgi-testrunner</artifactId>
               <version>${plugin.testrunner.version}</version>
               <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>javax.ws.rs</groupId>
               <artifactId>jsr311-api</artifactId>
               <version>1.1.1</version>
               <scope>provided</scope>
           </dependency>
           <dependency>
               <groupId>com.google.code.gson</groupId>
               <artifactId>gson</artifactId>
               <version>2.2.2-atlassian-1</version>
           </dependency>
       </dependencies>
       <build>
           <plugins>
               <plugin>
                   <groupId>com.atlassian.maven.plugins</groupId>
                   <artifactId>maven-confluence-plugin</artifactId>
                   <version>${amps.version}</version>
                   <extensions>true</extensions>
                   <configuration>
                       <productVersion>${confluence.version}</productVersion>
                       <productDataVersion>${confluence.data.version}</productDataVersion>
                       <enableQuickReload>true</enableQuickReload>
                       <enableFastdev>false</enableFastdev>
   
                       <!-- See here for an explanation of default instructions: -->
                       <!-- https://developer.atlassian.com/docs/advanced-topics/configuration-of-instructions-in-atlassian-plugins -->
                       <instructions>
                           <Atlassian-Plugin-Key>${atlassian.plugin.key}</Atlassian-Plugin-Key>
   
                           <!-- Add package to export here -->
                           <Export-Package>
                               com.example.plugins.tutorial.confluence.simplebp.api,
                           </Export-Package>
   
                           <!-- Add package import here -->
                           <Import-Package>
                               org.springframework.osgi.*;resolution:="optional",
                               org.eclipse.gemini.blueprint.*;resolution:="optional",
                               *
                           </Import-Package>
   
                           <!-- Ensure plugin is spring powered -->
                           <Spring-Context>*</Spring-Context>
                       </instructions>
                   </configuration>
               </plugin>
   
               <plugin>
                   <groupId>com.atlassian.plugin</groupId>
                   <artifactId>atlassian-spring-scanner-maven-plugin</artifactId>
                   <version>${atlassian.spring.scanner.version}</version>
                   <executions>
                       <execution>
                           <goals>
                               <goal>atlassian-spring-scanner</goal>
                           </goals>
                           <phase>process-classes</phase>
                       </execution>
                   </executions>
                   <configuration>
                       <scannedDependencies>
                           <dependency>
                               <groupId>com.atlassian.plugin</groupId>
                               <artifactId>atlassian-spring-scanner-external-jar</artifactId>
                           </dependency>
                       </scannedDependencies>
                       <verbose>false</verbose>
                   </configuration>
               </plugin>
           </plugins>
       </build>
       <properties>
            <confluence.version>6.7.1</confluence.version>
            <confluence.data.version>6.7.1</confluence.data.version>
            <create.content.version>7.0.0</create.content.version>
            <amps.version>6.3.15</amps.version>
            <plugin.testrunner.version>1.2.3</plugin.testrunner.version>
            <atlassian.spring.scanner.version>1.2.13</atlassian.spring.scanner.version>
            <!-- This key is used to keep the consistency between the key in atlassian-plugin.xml and the key to generate bundle. -->
            <atlassian.plugin.key>${project.groupId}.${project.artifactId}</atlassian.plugin.key>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <maven.compiler.source>1.8</maven.compiler.source>
            <maven.compiler.target>1.8</maven.compiler.target>
       </properties>
   </project>

4. Save and close the pom.xml file.

Step 3. Implement a simple ContextProvider

In this step, you create a simple implementation of a com.atlassian.plugin.web.ContextProvider interface by extending the com.atlassian.confluence.plugins.createcontent.api.contextproviders.AbstractBlueprintContextProvider. You can inject any components available to the Confluence plugin system into your ContextProvider.  After you add the provider Java code, you need to specify where it is located for the plugin system. You do this in the content-template module of your atlassian-plugin.xml file.

1. Create a MyContextProvider.java file in the src/main/java/com/example/plugins/tutorial/confluence/simplebp directory. 

2. Your class should extend com.atlassian.confluence.plugins.createcontent.api.contextproviders.AbstractBlueprintContextProvider. The AbstractBlueprintContextProvider implements ContextProvider and provides additional Blueprint-specific behaviour.

   1
   2
   3
   4
   5
   6
   7
   8

   package com.example.plugins.tutorial.confluence.simplebp;
   
   import com.atlassian.confluence.plugins.createcontent.api.contextproviders.AbstractBlueprintContextProvider;
   import com.atlassian.confluence.plugins.createcontent.api.contextproviders.BlueprintContext;
   
   public class MyContextProvider extends AbstractBlueprintContextProvider {
   
   }

3. Override the updateBlueprintContext() method:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

   package com.example.plugins.tutorial.confluence.simplebp;
   
   import com.atlassian.confluence.plugins.createcontent.api.contextproviders.AbstractBlueprintContextProvider;
   import com.atlassian.confluence.plugins.createcontent.api.contextproviders.BlueprintContext;
   
   public class MyContextProvider extends AbstractBlueprintContextProvider {
       @Override
       protected BlueprintContext updateBlueprintContext(BlueprintContext blueprintContext) {
           blueprintContext.put("vName", "Sherlock");
           return blueprintContext;
       }
   }

4. Save and close the file.

5. Open the atlassian-plugin.xml file and find the content-template module. Add a context-provider sub-element.

   1
   2
   3
   4

   <content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
     <resource name="template" type="download" location="/templates/mytemplate.xml" />
     <context-provider class="com.example.plugins.tutorial.confluence.simplebp.MyContextProvider"/>
   </content-template>

   The following code sample shows the full file, including previous sub-element.

   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>
   
       <!-- Blueprint -->
       <blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name"/>
   
       <!-- 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>
   
       <!-- Template for Blueprint -->
       <content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
           <resource name="template" type="download" location="/templates/mytemplate.xml" />
           <context-provider class="com.example.plugins.tutorial.confluence.simplebp.MyContextProvider"/>
       </content-template>        
   </atlassian-plugin>

6. Save and close the file.

Step 4. Test your plugin 

At this point, you've added some instructional text, a form field, and a way to fill out the field.  Now is a good point to test your code.

1. 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. Once the process completes, you'll see a something similar to the following message:

   1
   2
   3

   [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.

2. Log into the instance as user admin with a password admin.
   The Confluence Dashboard appears.

3. Click Spaces  > Demonstration Space.
   The system places you in the space home. 
4. Click Create. The system displays the Create dialog.
5. Select your blueprint and create a new page.
   You'll see the new page filled with the context and instructional text you defined.
6. To rebuild your plugin, run the atlas-package command that triggers QuickReload.

Step 5. Add a Soy template and support it with JavaScript

In this example, you write a basic Soy (Closure) template file.  A Soy template file is a way of dynamically building an HTML file and UI. Atlassian Soy is Atlassian's implementation of Google Closure. You'll use the Soy template to write a wizard for your blueprint.  This tutorial doesn't really describe in depth on Soy or Closure; you can learn more about them here. After you describe your wizard in Soy, you should update atlassian-plugin.xml to reference it. Also we add some code to simplebp.js to react on wizard's events.

1. Add a soy subdirectory to the src/main/resources directory.

2. Create a file called simplebp.soy in this new directory.

3. Add the following content to the simplebp.soy file and save it.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14

   {namespace MyPlugin.Blueprints.Simple}
   /**
   * A form that accepts a person's name
   */ 
   {template .page1Form}
       <form action="#" method="post" class="aui">
         <fieldset>
           <div class="field-group">
               <label for="vname">{getText('my.blueprint.form.label.title.vName')}</label>
               <input id="vname" class="text" type="text" name="vName">
           </div>
         </fieldset>
       </form>
   {/template}

   The template defines a single page, page1Form, that contains a one-field form. You'll reference the namespace value from your JavaScript and later from the atlassian-plugin.xml file. You'll also specify a label value that you need to add to your i18n strings.

4. In the simplebp.properties file, add the my.blueprint.form.label.title.

   1
   2

   my.blueprint.form.label.title.vName=Name
   my.blueprint.wizard.page1.title=Simplebp WIZARD

   The following code sample shows the entire file, including previous title.

   1
   2
   3
   4
   5

   my.blueprint.title=Sample Template
   my.create-link.title=My Sample Template
   my.create-link.description=Create a new SimpleBB template
   my.blueprint.form.label.title.vName=Name
   my.blueprint.wizard.page1.title=Simplebp WIZARD

5. Save and close the simplebp.properties file.

6. In the top of the src/main/resources/js/simplebp.js file in your project, call the setWizard(() JavaScript API:

   1

   Confluence.Blueprint.setWizard('com.example.plugins.tutorial.confluence.simplebp.simplebp:create-by-sample-template', function(wizard) {});

   The setWizard(() method takes the fully qualified pathname to the web-item that creates the blueprint link. The fully qualified pathname uses the following this format:
   ${project.groupId}.${artifactId}:web-item-name.
   Your atlassian-plugin.xml file defines the project's groupId and artifactId values.

7. Save and close the simplebp.js file.

Step 6. Update the atlassian-plugin.xml file and test

In the previous steps, you added some dependencies to your pom.xml file. You also used a Soy template to specify a Wizard page and wrote a JavaScript file to listen its events. In this step, you'll update the web-resource component in your atlassian-plugin.xml file to access the dependencies. Then you'll modify the content-template module to remove the context-provider element. The user fills in the Name in the wizard. You'll also add a dialog-wizard element to the <blueprint/> module. The dialog-wizard element describes each dialog-page in your wizard. A dialog-page  has three required attributes:

When you are done updating your atlassian-plugin.xml file, you'll run your plugin and see the Wizard in action.

1. In the src/main/resources/atlassian-plugin.xml file, find the <web-resource/> module.
   The SDK atlas-create-confluence-plugin command generates this module for you. 

2. Add a <dependency> element for the confluence-create-content-plugin.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

   <!-- add our web resources -->
   <web-resource key="simplebp-resources" name="simplebp Web Resources">
       <dependency>com.atlassian.auiplugin:ajs</dependency>
       <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</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>

3. Add a <transformation/> module for soy.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18

   <!-- add our web resources -->
   <web-resource key="simplebp-resources" name="simplebp Web Resources">
       <dependency>com.atlassian.auiplugin:ajs</dependency>
       <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</dependency>
   
       <transformation extension="soy">
           <transformer key="soyTransformer">
               <functions>com.atlassian.confluence.plugins.soy:soy-core-functions
               </functions>
           </transformer>
       </transformation>
   
       <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>

4. Right before the /images entry, inside web-resource, add an entry for Soy template.
   When, specifying the name value, add .js to the template name. This notifies the plugin system that your Soy resource transforms to Javascript on the client. Make sure to append .js to the template name. For example, our simplebp.soy should look like simplebp.soy.js.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19

   <!-- add our web resources -->
   <web-resource key="simplebp-resources" name="simplebp Web Resources">
       <dependency>com.atlassian.auiplugin:ajs</dependency>
       <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</dependency>
   
       <transformation extension="soy">
           <transformer key="soyTransformer">
               <functions>com.atlassian.confluence.plugins.soy:soy-core-functions
               </functions>
           </transformer>
       </transformation>
   
       <resource type="download" name="simplebp.css" location="/css/simplebp.css" />
       <resource type="download" name="simplebp.js" location="/js/simplebp.js" />
       <resource type="download" name="simplebp.soy.js" location="/soy/simplebp.soy" />
       <resource type="download" name="images/" location="/images" />
   
       <context>simplebp</context>
   </web-resource>

5. To include your resources in create content dialog, inside context tag replace auto generated value simplebp with create-content.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19

   <!-- add our web resources -->
   <web-resource key="simplebp-resources" name="simplebp Web Resources">
       <dependency>com.atlassian.auiplugin:ajs</dependency>
       <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</dependency>
   
       <transformation extension="soy">
           <transformer key="soyTransformer">
               <functions>com.atlassian.confluence.plugins.soy:soy-core-functions
               </functions>
           </transformer>
       </transformation>
   
       <resource type="download" name="simplebp.css" location="/css/simplebp.css" />
       <resource type="download" name="simplebp.js" location="/js/simplebp.js" />
       <resource type="download" name="simplebp.soy.js" location="/soy/simplebp.soy" />
       <resource type="download" name="images/" location="/images" />
   
       <context>create-content</context>
   </web-resource>

6. In the <blueprint/> module, define the dialog-wizard. Make sure that template-key points to your Soy template.

   1
   2
   3
   4
   5
   6

   <!-- Blueprint -->
   <blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name">
       <dialog-wizard key="simplebp-wizard">
            <dialog-page id="page1Id" template-key="MyPlugin.Blueprints.Simple.page1Form" title-key="my.blueprint.wizard.page1.title" last="true"/>
       </dialog-wizard>
   </blueprint>

7. Comment out the context-provider where it appears in the content-template module.

   1
   2
   3
   4
   5

   <!-- Template for Blueprint -->
   <content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
       <resource name="template" type="download" location="/templates/mytemplate.xml" />
   <!-- <context-provider class="com.example.plugins.tutorial.confluence.simplebp.MyContextProvider" /> -->
   </content-template>

   The following code snippet shows the full file, including the previous module.

   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
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47

   <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>
           <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</dependency>
           <transformation extension="soy">
               <transformer key="soyTransformer">
                   <functions>com.atlassian.confluence.plugins.soy:soy-core-functions
                   </functions>
               </transformer>
           </transformation>
           <resource type="download" name="simplebp.css" location="/css/simplebp.css" />
           <resource type="download" name="simplebp.js" location="/js/simplebp.js" />
           <resource type="download" name="simplebp.soy.js" location="/soy/simplebp.soy" />
           <resource type="download" name="images/" location="/images" />
           <context>create-content</context>
       </web-resource>
       <!-- Blueprint -->
       <blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name">
           <dialog-wizard key="simplebp-wizard">
               <dialog-page id="page1Id" template-key="MyPlugin.Blueprints.Simple.page1Form" title-key="my.blueprint.wizard.page1.title" last="true"/>
           </dialog-wizard>
       </blueprint>
       <!-- 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>
   
       <!-- Template for Blueprint -->
       <content-template key="simplebp-template" i18n-name-key="my.blueprint.title">
           <resource name="template" type="download" location="/templates/mytemplate.xml" />
   <!--         <context-provider -->
   <!--             class="com.example.plugins.tutorial.confluence.simplebp.MyContextProvider" /> -->
       </content-template>
   </atlassian-plugin>

8. Save and close the atlassian-plugin.xml file.

9. To rebuild the plugin, run the following command.

   1

   atlas-package

10. Test your blueprint in Confluence to view your wizard.
     

Step 7.  Add a description to your blueprint

Although the Wizard form is quite simple, a complex or multi-page Wizard can benefit from some explanatory text. In this step, you add description-header-key and a description-content-key to display this explanatory text. 

1. Edit the atlassian-plugin.xml file.

2. Add two attributes to the dialog-page element.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

   <blueprint key="my-blueprint" content-template-key="simplebp-template" index-key="my-index" i18n-name-key="my.blueprint.name">
     ...
     <dialog-wizard key="simplebp-wizard">
       <dialog-page id="page1Id"
                    template-key="MyPlugin.Blueprints.Simple.page1Form"
                    title-key="my.blueprint.wizard.page1.title"
                    description-header-key="my.blueprint.wizard.page1.desc.header"
                    description-content-key="my.blueprint.wizard.page1.desc.content"
                    last="true" />
     </dialog-wizard>
   </blueprint>

3. Save and close the atlassian-plugin.xml file.

4. In the simplebp.properties file, add an entry for the description title and content.

   1
   2
   3
   4
   5
   6
   7

   my.blueprint.title=Sample Template
   my.create-link.title=My Sample Template
   my.create-link.description=Create a new SimpleBB template
   my.blueprint.form.label.title.vName=Name
   my.blueprint.wizard.page1.title=Simplebp WIZARD
   my.blueprint.wizard.page1.desc.header=About this blueprint
   my.blueprint.wizard.page1.desc.content=Use this blueprint to create a table with your name and email.

5. Save and close the simplebp.properties file.

6. To rebuild your plugin, run the following command, and QuickReload will automatically reinstall it for you.

   1

   atlas-package

    

Step 8. Add validation to your template

Using the setWizard() JavaScript API you can add fuller interaction to your wizard.  For example, you can use this API to validate values entered in a wizard's forms. For validation, you use the submit hook to check the fields on a page.  The submit hook takes the id value of the dialog-page and a state object.   Values from the wizard's form are properties of the state.pageDataobject.  Do the following to validate the entry of the Name field in your wizard:

1. In the resources/js/simplebp.js file, add the hook to the setWizard(){} body.

   1
   2
   3
   4
   5
   6
   7
   8
   9

   Confluence.Blueprint.setWizard('com.example.plugins.tutorial.confluence.simplebp.simplebp:create-by-sample-template', function(wizard) {
        wizard.on('submit.page1Id', function(e, state) {   
            var vName = state.pageData.vName;
            if (!vName){
                alert('Please provide a name value.');
                return false;
            }
        });
    });

   This hook checks to make sure the field is not empty.

2. Save and close the simplebp.js file.

3. Rebuild your plugin using the following command:

   1

   atlas-package

4. Test your work.

Next steps

You can continue onto the next tutorial, Write an advanced blueprint plugin to learn how to construct multiple page tutorials and add event listeners.