Confluence 5 Tips: How to Develop Confluence Blueprints Addons

Step 3 – Add a Plugin Module to the Plugin Descriptor

• the key attribute is the module key in the descriptor
• the create-result attribute defines the behavior expected upon creation of new content with the help of Blueprints. The possible values are: edit (after completion of all steps, we’ll be taken to the Editor mode), view(after creating a page, we’ll be taken to the View mode, the page is created automatically)
• the content-template-key attribute refers to the module key content-template declared later in atlassian-plugin.xml
• the index-key attribute defines the index assigned to the created page (it’s worth mentioning that the index mechanism is quite powerful but is out of scope of this tutorial).

The dialog-wizard parameter of the blueprint module defines the dynamic behavior of what a user sees when creating content with the help of your Blueprint plugin. The parameter has the following attributes:

• the id attribute is used when formatting html content as a part of a css class in the current window viewed by a user (for example, you can pile some css styles by defining the id attribute).
• the template-key attribute defined the name of a soy function for windows content dynamic generation.
• the title-key attribute is the key for a window title displayed to a user in the resource file.

The soy function we use is defined later in the web-resource module. Below is what the templates.soy file contains:

{namespace WikiMarkup.Blueprint}
/**
 * Wiki Markup form
 */
{template .form}
    <form id="wiki-markup-form" action="#" method="post">
        <div>
            {getText('wiki.markup.blueprint.dialog.form.label.page.title')}
        </div>
        <input id="page-title" type="text" name="title">
        <div>
            {getText('wiki.markup.blueprint.dialog.form.label.markup')}
        </div>
        <textarea id="wiki-markup" name="wikiMarkup"></textarea>
    </form>
{/template}

<content-template key="wiki-markup-blueprint-page" i18n-name-key="wiki.markup.blueprint.page.name">
        <resource name="template" type="download" location="xml/content-template.xml"/>
        <context-provider/>
    </content-template>

The content-template module has the following parameters:

• the key attribute is the module key in the descriptor (used in the blueprint module).
• the resource tag defines the template used for creating of a new page.
• the context-provider tag is the optional parameter that can be used for creating a page with additional variables.

Please note that the page template created from an xml file can contain dynamic variables taken from the context. In the plugin under consideration, the template looks like as follows:

<at:var at:name="wikiInXhtml" at:rawXhtml='true'/>

The variable that can be used in the template can be taken from the form filled by a user or added directly by context-provider. In this example we use context-provide that converts the wiki markup entered by a user in the enter box to the xhtml markup used in Confluence. The context-provider code is shown below:

package com.stiltsoft.confluence.plugins.blueprint.markup;

import com.atlassian.confluence.content.render.xhtml.DefaultConversionContext;
import com.atlassian.confluence.content.render.xhtml.XhtmlException;
import com.atlassian.confluence.renderer.PageContext;
import com.atlassian.confluence.xhtml.api.EditorFormatService;
import com.atlassian.plugin.PluginParseException;
import com.atlassian.plugin.web.ContextProvider;
import java.util.Map;

public class WikiMarkupProvider implements ContextProvider {

    private EditorFormatService editorFormatService;

    public WikiMarkupProvider(EditorFormatService editorFormatService) {
        this.editorFormatService = editorFormatService;
    }

    @Override
    public void init(Map<String, String> params) throws PluginParseException {
    }

    @Override
    public Map<String, Object> getContextMap(Map<String, Object> ctx) {
        try {
            String wikiMarkup = (String) ctx.get("wikiMarkup");
            String xhtml = editorFormatService.convertWikiToEdit(wikiMarkup, new DefaultConversionContext(new PageContext()));
            ctx.put("wikiInXhtml", xhtml);
        } catch (XhtmlException ignored) {
        }
        return ctx;
    }
}

And finally, let’s define the web-resource module in atlassian-plugin.xml:

    <web-resource key="blueprint-resources" name="Blueprint Resources">
        <transformation extension="js">
            <transformer key="jsI18n"/>
        </transformation>
        <transformation extension="soy">
            <transformer key="soyTransformer">
                <functions>com.atlassian.confluence.plugins.soy:soy-core-functions</functions>
            </transformer>
        </transformation>
        <resource type="download" name="wiki-markup.css" location="css/wiki-markup.css"/>
        <resource type="download" name="templates-soy.js" location="soy/templates.soy"/>
        <resource type="download" name="wiki-markup.js" location="js/wiki-markup.js"/>

        <dependency>com.atlassian.confluence.plugins.confluence-create-content-plugin:resources</dependency>
        <context>atl.general</context>
        <context>atl.admin</context>
    </web-resource>

Please note that you should set the dependency from the resources com.atlassian.confluence.plugins.confluence-create-content-plugin:resources. Besides, you should register your Blueprint plugin in wiki-markup.js as shown below:

(function ($) {
    Confluence.Blueprint.setWizard('com.stiltsoft.confluence.plugins.wiki-markup-blueprint-plugin:wiki-markup-blueprint-item', function() {
    });
})(AJS.$);

Step 4 – Use the plugin to create pages from the wiki markup

You won’t believe it, but this is almost the end of the tutorial. If you did everething right, you can install the plugin and start using it.

Moreover, you can download the plugin source code or try and go through all the steps yourself. If you have any question about plugin development for Confluence, you can contact our technical support and we will help you out.