Ryan ThomasAtlassian

Confluence PatternsGetting the most out of your add-on

May 2013

About Me

• OnDemand Team Lead

• Ex-Confluence Developer

• From Sydney, Australia

• rthomas@atlassian.com

• @RyanAtlassian

About Me

In Context

In Context Notification

In Context

You’re Too Big

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

What is a design pattern?

“a design pattern is a general reusable solution to a commonly occurring problem”

What is a design pattern?

In ContextEditor Pattern

In Context Pattern

Making sure the object your macro creates is contextual inside of the editor!

In Context Pattern

Making sure the object your macro creates is contextual inside of the editor!

In Context Pattern 1

A vanilla macro placeholder does not give enough context about the macro.

In Context Pattern 1

A vanilla macro placeholder does not give enough context about the macro.

Use an Image Based Placeholder for your macro.

In Context Pattern 1

In Context Pattern 1

In Context Pattern 1• Image Based Placeholders allow you to

dynamically generate an image to use for rendering in the editor.

• Easy to retrofit to your existing macros.

https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as+a+Macro+Placeholder+in+the+Editor

In Context Pattern 1• Image Based Placeholders allow you to

dynamically generate an image to use for rendering in the editor.

• Easy to retrofit to your existing macros.

https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as+a+Macro+Placeholder+in+the+Editor

In Context Pattern 2

Your macro augments or modifies the properties of images.

In Context Pattern 2

Your macro augments or modifies the properties of images.

Instead of using a macro, add this functionality to the Image Property Dialog.

In Context Pattern 2

In Context Pattern 2

In Context Pattern 2• Allows you to extend the Image Property

Dialog

• Use it when your macro modifies the properties of images and you wish for more seamless integration with the editor.

https://developer.atlassian.com/display/CONFDEV/Extending+the+Image+Properties+Dialog

In Context Pattern 3

Your macro generates a link when rendered.

In Context Pattern 3

Your macro generates a link when rendered.

Extend the Link Browser Dialog to add the functionality here, instead of using a macro.

In Context Pattern 3

In Context Pattern 3

Select a repository...

https://developer.atlassian.com/display/CONFDEV/Extending+the+Confluence+Insert+Link+Dialog

In Context Pattern 3• Useful for complex links, or links that

require a lot of parameters.

• Useful for links that have some administration setup

• Simplifies the user experience.

You would like to capture data a user pastes into the Confluence editor, to better represent it.

In Context Pattern 4

You would like to capture data a user pastes into the Confluence editor, to better represent it.

Extend the editor autoconvert to convert user-pasted data into any editor content you like.

In Context Pattern 4

In Context Pattern 4• Register a paste handler

• Can convert to images or arbitrary wiki content, not just macros!

In Context Pattern 4• Register a paste handler

• Can convert to images or arbitrary wiki content, not just macros!

https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert

In Context PatternUse Case Plugin

PointMore Info

Macro generates an image Image Based Placeholder

https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as+a+Macro+Placeholder+in+the+Editor

Macro modifies images Extend the Image Dialog

https://developer.atlassian.com/display/CONFDEV/Extending+the+Image+Properties+Dialog

Macro create a link Extend the Link Dialog

https://developer.atlassian.com/display/CONFDEV/Extending+the+Confluence+Insert+Link+Dialog

Capture user-pasted content

Extend Autoconvert https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert

You’re Too BigEditor Pattern

Your macro has too many parameters, or you wish to provide a custom user experience.

You’re Too Big Pattern

Your macro has too many parameters, or you wish to provide a custom user experience.

Write a custom editor dialog for your macro.

You’re Too Big Pattern

You’re Too Big Pattern

You’re Too Big Pattern

You’re Too Big Pattern

You’re Too Big Pattern

AJS.bind(“init.rte”, function() {

AJS.MacroBrowser.setMacroJsOverride(“myMacro”, { opener: function(macro) { // Dialog drawing code goes here... } }

}

Easy to do!

You’re Too Big Pattern

https://developer.atlassian.com/display/AUI/Dialog

• Use AJS.MacroBrowser.setMacroJsOverride to override the editor functionality for a macro & display your own dialog.

• Do this when you have too many parameters, or you want a custom editor experience.

You’re Too Big Pattern

https://developer.atlassian.com/display/AUI/Dialog

• Use AJS.MacroBrowser.setMacroJsOverride to override the editor functionality for a macro & display your own dialog.

• Do this when you have too many parameters, or you want a custom editor experience.

Think of the 90%Editor Pattern

The 90% PatternThink of the 90% use case!

The 90% PatternThink of the 90% use case!

You are building a macro with a number of common parameters.

The 90% Pattern 1

You are building a macro with a number of common parameters.

Add them to the macro property panel.

The 90% Pattern 1

The 90% Pattern 1Extend the property panel with common parameters

The 90% Pattern 1Extend the property panel with common parameters

Colour preset buttons

The 90% Pattern 1Extend the property panel with common parameters

Colour preset buttons

Text input field

AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId", function(e, macroNode) {     updateMacro(macroNode, "paramValue"); });

var updateMacro = function(macroNode, param) {    var $macroDiv = AJS.$(macroNode);    AJS.Rte.getEditor().selection.select($macroDiv[0]);    AJS.Rte.BookmarkManager.storeBookmark();     var macroRenderRequest = {        contentId: Confluence.Editor.getContentId(),        macro: {            name: "status-light",            params: {"percentage": param},            defaultParameterValue: "",            body : ""        }    };     tinymce.confluence.MacroUtils.insertMacro(macroRenderRequest);};

AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId", function(e, macroNode) {     updateMacro(macroNode, "paramValue"); });

https://developer.atlassian.com/display/CONFDEV/Extending+the+Macro+Property+Panel

Your macro has many required parameters, trying to cater to every eventuality.

The 90% Pattern 2

Your macro has many required parameters, trying to cater to every eventuality.

Think about the parameters you’re making required!

The 90% Pattern 2

The 90% Pattern 2

The status macro does it wrong!

The 90% Pattern 2

• These will cause the macro edit dialog to always be displayed

• Is the field actually required, or could you set a sensible default for it?

• Using sensible defaults can lead to a smoother user experience

Think about required parameters!

NotificationAdmin Pattern

Notification Pattern

Notification Pattern

You have configuration needed to be done by an administrator.

Notification Pattern 1

You have configuration needed to be done by an administrator.

Create an Administration Task Item so that admins can track and complete the config.

Notification Pattern 1

Notification Pattern 1

Notification Pattern 1

<web-item key="plugin-admin-task" section="system.admin.tasks/general" weight="150">

<label key="plugin.admin.task.title"/> <description key="plugin.admin.task.description"/> <link id="configure-mail">/admin/mail/viewmailservers.action</link> <condition class="com.atlassian.examples.DefaultMailServerExistsCondition" invert="true"/></web-item>

Add a web-item to the system.admin.tasks/general section

atlassian-plugin.xml

Notification Pattern 1• Ensure your addon is correctly configured

by creating an administrator task for it

• Admin tasks display in the Confluence Administration page.

• The can be checked off as completed by administrators

https://developer.atlassian.com/display/CONFDEV/Creating+an+Admin+Task

You want to keep your users informed of what’s new when they install your plugin.

Notification Pattern 2

You want to keep your users informed of what’s new when they install your plugin.

Configure a post-install-url for your plugin.

Notification Pattern 2

Notification Pattern 2

Notification Pattern 2<plugin-info> <description>${project.description}</description> <version>${project.version}</version> <vendor name="${project.organization.name}" url="${project.organization.url}"/>

<param name="configure.url">/plugins/servlet/configureServlet</param> <param name="post.install.url">/plugins/servlet/installServlet</param> <param name="post.update.url">/plugins/servlet/installServlet</param></plugin-info>

atlassian-plugin.xml

Notification Pattern 2• Specifies a page that appears after

installation, or update

• Keep administrators up to date with the latest features of your addon

• Only appears when installed via Atlassian Marketplace

https://developer.atlassian.com/display/UPM/Plugin+Metadata+Files+used+by+UPM+and+Marketplace

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

In Context

You’re Too Big The 90%

Notification

https://developer.atlassian.com/

Thank you!