1. Confluence Patterns
Getting the most out of your add-on
Ryan Thomas
Atlassian
May 2013

2. About Me

3. About Me
• OnDemand Team Lead
• Ex-Confluence Developer
• From Sydney, Australia
• rthomas@atlassian.com
• @RyanAtlassian

5. In Context

6. In Context
Notification

7. In Context
You’re Too Big
Notification

8. In Context
You’re Too Big
Notification
The 90%

9. In Context
You’re Too Big
Notification
The 90%

10. What is a design pattern?

11. What is a design pattern?
“a design pattern is a general reusable solution to
a commonly occurring problem”

12. In Context
Editor Pattern

13. In Context Pattern
Making sure the object your macro creates is
contextual inside of the editor!

14. In Context Pattern
Making sure the object your macro creates is
contextual inside of the editor!

15. In Context Pattern 1
A vanilla macro placeholder does not give enough
context about the macro.

16. In Context Pattern 1
A vanilla macro placeholder does not give enough
context about the macro.
Use an Image Based Placeholder for your macro.

17. In Context Pattern 1

18. In Context Pattern 1

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

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

21. In Context Pattern 2
Your macro augments or modifies the properties
of images.

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

23. In Context Pattern 2

24. In Context Pattern 2

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

26. In Context Pattern 3
Your macro generates a link when rendered.

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

28. In Context Pattern 3

29. In Context Pattern 3
Select a repository...

30. 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.
https://developer.atlassian.com/display/CONFDEV/Extending+the+Confluence+Insert+Link+Dialog

31. In Context Pattern 4
You would like to capture data a user pastes into
the Confluence editor, to better represent it.

32. 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 userpasted data into any editor content you like.

33. In Context Pattern 4
• Register a paste handler
• Can convert to images or arbitrary wiki
content, not just macros!

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

35. In Context Pattern
Use Case
Plugin
Point
Macro generates an image
Image Based
Placeholder
Macro modifies images
Extend the Image
Dialog
Macro create a link
Extend the Link
Dialog
Capture user-pasted
content
Extend
Autoconvert
More Info
https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as
+a+Macro+Placeholder+in+the+Editor
https://developer.atlassian.com/display/CONFDEV/Extending+the+Image
+Properties+Dialog
https://developer.atlassian.com/display/CONFDEV/Extending+the
+Confluence+Insert+Link+Dialog
https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert

36. You’re Too Big
Editor Pattern

37. You’re Too Big Pattern
Your macro has too many parameters, or you wish
to provide a custom user experience.

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

39. You’re Too Big Pattern

40. You’re Too Big Pattern

41. You’re Too Big Pattern

42. You’re Too Big Pattern
Easy to do!
AJS.bind(“init.rte”, function() {
AJS.MacroBrowser.setMacroJsOverride(“myMacro”, {
opener: function(macro) {
// Dialog drawing code goes here...
}
}
}

43. You’re Too Big Pattern
• 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.
https://developer.atlassian.com/display/AUI/Dialog

44. You’re Too Big Pattern
• 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.
https://developer.atlassian.com/display/AUI/Dialog

45. Think of the 90%
Editor Pattern

46. The 90% Pattern
Think of the 90% use case!

47. The 90% Pattern
Think of the 90% use case!

48. The 90% Pattern 1
You are building a macro with a number of
common parameters.

49. The 90% Pattern 1
You are building a macro with a number of
common parameters.
Add them to the macro property panel.

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

51. The 90% Pattern 1
Extend the property panel with
common parameters
Colour preset buttons

52. The 90% Pattern 1
Extend the property panel with
common parameters
Text input field
Colour preset buttons

53. 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(),
AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId",
macro: {
function(e, macroNode) {
name: "status-light",
updateMacro(macroNode, "paramValue");
params: {"percentage": param},
}
defaultParameterValue: "",
);
body : ""
}
};
tinymce.confluence.MacroUtils.insertMacro(macroRenderRequest);
};

54. AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId",
function(e, macroNode) {
updateMacro(macroNode, "paramValue");
}
);
https://developer.atlassian.com/display/CONFDEV/Extending+the+Macro+Property+Panel

55. The 90% Pattern 2
Your macro has many required parameters, trying
to cater to every eventuality.

56. The 90% Pattern 2
Your macro has many required parameters, trying
to cater to every eventuality.
Think about the parameters you’re making required!

57. The 90% Pattern 2
The status macro does it wrong!

58. The 90% Pattern 2
Think about required parameters!
• 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

59. Notification
Admin Pattern

60. Notification Pattern

61. Notification Pattern

62. Notification Pattern 1
You have configuration needed to be done by an
administrator.

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

64. Notification Pattern 1

65. Notification Pattern 1
Add a web-item to the
system.admin.tasks/general section
<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>
atlassian-plugin.xml

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

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

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

69. Notification Pattern 2

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

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

73. In Context
You’re Too Big
Notification
The 90%

74. In Context
You’re Too Big
Notification
The 90%

75. In Context
You’re Too Big
Notification
The 90%

76. In Context
You’re Too Big
Notification
The 90%

77. In Context
You’re Too Big
Notification
The 90%

78. In Context
You’re Too Big
Notification
The 90%

79. In Context
Notification
https://developer.atlassian.com/
You’re Too Big
The 90%

80. Thank you!