How do you enable a richer experience for users of your plugin? With the impending release of Confluence 4.0 we will show you not only how to make your plugins Confluence 4.0 compatible but how to dress them up to take advantage of all the new plugin points Confluence 4.0 has to offer, allowing you to give your users a richer editing experience. Ryan Thomas, Confluence Developer

2. Confluence 4.0
Integrating your plugin as a first class citizen
Ryan Thomas
Developer, Atlassian
http://atlss.in/confluence4
#atlascamp 2

3. About Me
3

4. About Me
• Confluence Developer
3

5. About Me
• Confluence Developer
• Worked on 4.0 since January
2010
3

6. About Me
• Confluence Developer
• Worked on 4.0 since January
2010
• Managed a lot of the ecosystem
integration
3

7. About Me
• Confluence Developer
• Worked on 4.0 since January
2010
• Managed a lot of the ecosystem
integration
• Deployed 4.0 to the Atlassian
internal instances
3

8. Agenda
4

9. Agenda
4

10. Agenda
• Editor Plugin Points
4

11. Agenda
• Editor Plugin Points
• Transformer Pipeline
4

12. Agenda
• Editor Plugin Points
• Transformer Pipeline
• XHTML in Macros
4

13. Agenda
• Editor Plugin Points
• Transformer Pipeline
• XHTML in Macros
• Demonstration
4

14. Editor Terminology
5

15. Editor Terminology
Rich Text Editor
5

16. Editor Terminology
Toolbar
5

17. Editor Terminology
Insert Menu
5

18. Editor Terminology
Formatting Menu
5

19. Editor Terminology
5

20. Editor Terminology
Macro Placeholder
5

21. Editor Terminology
Macro Property Panel
5

22. Formatting Menu
6

23. Formatting Menu
6

24. Formatting Menu
• Plug into the Formatting menu
in the Toolbar
6

25. Formatting Menu
• Plug into the Formatting menu
in the Toolbar
• Allows you to interact with the
TinyMCE formatting styles
6

26. Formatting Menu
• Plug into the Formatting menu
in the Toolbar
• Allows you to interact with the
TinyMCE formatting styles
• Done as a web-item
6

27. Formatting Menu
7

28. Formatting Menu
<web-item key="editor-awesome-format" name="Awesome Format"
section="system.editor.more.formats" weight="10">
<label key="my.plugin.awesome.format"/>
<link linkId="my-awesome-format"/>
</web-item>
7

29. Formatting Menu
<web-item key="editor-awesome-format" name="Awesome Format"
section="system.editor.more.formats" weight="10">
<label key="my.plugin.awesome.format"/>
<link linkId="my-awesome-format"/>
</web-item>
$("#my-awesome-button").click(function(){
tinymce.activeEditor.execCommand("FormatBlock",
false, "samp");
});
7

30. Formatting Menu
<web-item key="editor-awesome-format" name="Awesome Format"
section="system.editor.more.formats" weight="10">
<label key="my.plugin.awesome.format"/>
<link linkId="my-awesome-format"/>
</web-item>
system.editor.more.formats
$("#my-awesome-button").click(function(){
tinymce.activeEditor.execCommand("FormatBlock",
false, "samp");
});
7

31. Insert Menu
8

32. Insert Menu
8

33. Insert Menu
• Add your macro to the Insert menu in
the Toolbar
8

34. Insert Menu
• Add your macro to the Insert menu in
the Toolbar
• Default behaviour opens Macro
Browser
8

35. Insert Menu
• Add your macro to the Insert menu in
the Toolbar
• Default behaviour opens Macro
Browser
• Done as a web-item
8

36. Insert Menu
9

37. Insert Menu
<web-item key="editor-my-macro"
name="Insert Menu Link - My Macro"
section="system.editor.featured.macros.default"
weight="100">
<label key="my.plugin.macro"/>
<link linkId="mymacro"/>
</web-item>
9

38. Insert Menu
<web-item key="editor-my-macro"
name="Insert Menu Link - My Macro"
section="system.editor.featured.macros.default"
weight="100">
<label key="my.plugin.macro"/>
<link linkId="mymacro"/>
</web-item>
system.editor.featured.macros.default
9

39. Overriding The Macro Browser
10

40. Overriding The Macro Browser
• Want to use a custom dialog?
10

41. Overriding The Macro Browser
• Want to use a custom dialog?
• Want to perform some action before opening the Macro
Browser?
10

42. Overriding The Macro Browser
• Want to use a custom dialog?
• Want to perform some action before opening the Macro
Browser?
• Want your macro to appear as a native Confluence
component?
10

43. Overriding The Macro Browser
11

44. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
11

45. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
• This will affect all the following areas:
11

46. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
• This will affect all the following areas:
• Insert Menu
11

47. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
• This will affect all the following areas:
• Insert Menu
• Autocomplete
11

48. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
• This will affect all the following areas:
• Insert Menu
• Autocomplete
• Property panel Edit button
11

49. Overriding The Macro Browser
AJS.MacroBrowser.setMacroJsOverride('my-macro', {opener:
function(macro) {
// Custom logic goes here
}
});
• This will affect all the following areas:
• Insert Menu
• Autocomplete
• Property panel Edit button
• Manually selecting inside the macro browser
11

50. Image Macro Placeholders
12

51. Image Macro Placeholders
12

52. Image Macro Placeholders
• Replaces the Macro Placeholder
12

53. Image Macro Placeholders
• Replaces the Macro Placeholder
• Plugins can generate their own
image, or reference static images
12

54. Image Macro Placeholders
• Replaces the Macro Placeholder
• Plugins can generate their own
image, or reference static images
• Only applicable to Bodiless Macros
12

55. Image Macro Placeholders
• Replaces the Macro Placeholder
• Plugins can generate their own
image, or reference static images
• Only applicable to Bodiless Macros
• Macro Placeholder chrome can be
applied optionally
12

56. Image Macro Placeholders
• Replaces the Macro Placeholder
• Plugins can generate their own
image, or reference static images
• Only applicable to Bodiless Macros
• Macro Placeholder chrome can be
applied optionally
12

57. Image Macro Placeholders
• Replaces the Macro Placeholder
• Plugins can generate their own
image, or reference static images
• Only applicable to Bodiless Macros
• Macro Placeholder chrome can be
applied optionally
12

58. Image Macro Placeholders
13

59. Image Macro Placeholders
public interface EditorImagePlaceholder
{
ImagePlaceholder getImagePlaceholder(
Map<String, String> parameters,
ConversionContext context);
}
13

60. Image Macro Placeholders
public interface EditorImagePlaceholder
{
ImagePlaceholder getImagePlaceholder(
Map<String, String> parameters,
ConversionContext context);
}
public interface ImagePlaceholder
{
String getUrl();
Dimensions getDimensions();
boolean applyPlaceholderChrome();
}
13

61. Macro Property Panel
14

62. Macro Property Panel
14

63. Macro Property Panel
14

64. Macro Property Panel
• Provides contextual actions for
the macro
14

65. Macro Property Panel
• Provides contextual actions for
the macro
• Provides Edit and Remove
buttons
14

66. Macro Property Panel
• Provides contextual actions for
the macro
• Provides Edit and Remove
buttons
• Custom buttons for your macros
14

67. Macro Property Panel
• Provides contextual actions for
the macro
• Provides Edit and Remove
buttons
• Custom buttons for your macros
14

68. Macro Property Panel
15

69. Macro Property Panel
atlassian-plugin.xml
<xhtml-macro key="status" name="status" ...>
<!-- SNIP -->
<property-panel>
<spacer/>
<button id="Grey" label=""/>
<button id="Red" label=""/>
<button id="Yellow" label=""/>
<button id="Green" label=""/>
<spacer/>
</property-panel>
</xhtml-macro>
15

70. Macro Property Panel
16

71. Macro Property Panel
AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("Grey",
function(e, macroNode) {
// Custom button logic goes here
updateMacro(macroNode, "Grey"); // Plugin function
});
See complete example here:
https://bitbucket.org/rthomas/confluence-status-macro/
16

72. Parameter Placeholder
17

73. Parameter Placeholder
17

74. Parameter Placeholder
17

75. Parameter Placeholder
17

76. Parameter Placeholder
17

77. Parameter Placeholder
17

78. Parameter Placeholder
17

79. Parameter Placeholder
18

80. Parameter Placeholder
<parameters>
<default>
<option key="showValueInPlaceholder" value="true" />
</default>
<parameter name="key" type="string">
<option key="showKeyInPlaceholder" value="false" />
<option key="showValueInPlaceholder" value="true" />
</parameter>
<parameter name="server" type="string">
<option key="showKeyInPlaceholder" value="false" />
<option key="showValueInPlaceholder" value="false" />
</parameter>
</parameters>
18

81. Editor Plugin Points
19

82. Editor Plugin Points
19

83. Editor Plugin Points
• Formatting Menu
19

84. Editor Plugin Points
• Formatting Menu
• Insert Menu & Overrides
19

85. Editor Plugin Points
• Formatting Menu
• Insert Menu & Overrides
• Image Placeholders
19

86. Editor Plugin Points
• Formatting Menu
• Insert Menu & Overrides
• Image Placeholders
• Macro Property Panel
19

87. Editor Plugin Points
• Formatting Menu
• Insert Menu & Overrides
• Image Placeholders
• Macro Property Panel
• Parameter Placeholder
19

88. Transformer Pipeline
20

89. Transformer Pipeline
20

90. Transformer Pipeline
• Confluence 4.0 contains a
completely new rendering engine
20

91. Transformer Pipeline
• Confluence 4.0 contains a
completely new rendering engine
• Part of this engine is the
Transformer Pipeline
20

92. Transformer Pipeline
• Confluence 4.0 contains a
completely new rendering engine
• Part of this engine is the
Transformer Pipeline
• This is available to all plugins
20

93. Transformer Pipeline
21

94. Transformer Pipeline
• Confluence 4.0 stores its data in XHTML, this is known
as Storage Format - (No more wiki-markup! )
21

95. Transformer Pipeline
• Confluence 4.0 stores its data in XHTML, this is known
as Storage Format - (No more wiki-markup! )
• We have three formats, however only the Storage
Format is persisted
21

96. Transformer Pipeline
• Confluence 4.0 stores its data in XHTML, this is known
as Storage Format - (No more wiki-markup! )
• We have three formats, however only the Storage
Format is persisted
• View Format: HTML
21

97. Transformer Pipeline
• Confluence 4.0 stores its data in XHTML, this is known
as Storage Format - (No more wiki-markup! )
• We have three formats, however only the Storage
Format is persisted
• View Format: HTML
• Editor Format: HTML with data attributes
21

98. Transformer Pipeline
22

99. Transformer Pipeline
• The pipeline controls the rendering of Confluence
content from one format to another
22

100. Transformer Pipeline
• The pipeline controls the rendering of Confluence
content from one format to another
• There are three pipelines inside of the rendering
engine:
22

101. Transformer Pipeline
• The pipeline controls the rendering of Confluence
content from one format to another
• There are three pipelines inside of the rendering
engine:
• Storage to View (viewing a page)
22

102. Transformer Pipeline
• The pipeline controls the rendering of Confluence
content from one format to another
• There are three pipelines inside of the rendering
engine:
• Storage to View (viewing a page)
• Storage to Edit (editing a page)
22

103. Transformer Pipeline
• The pipeline controls the rendering of Confluence
content from one format to another
• There are three pipelines inside of the rendering
engine:
• Storage to View (viewing a page)
• Storage to Edit (editing a page)
• Edit to Storage (saving a page)
22

104. Transformer Pipeline

105. Transformer Pipeline
Storage
Format
View Edit
Format Format
23

106. Transformer Pipeline
24

107. Transformer Pipeline
• Why?
24

108. Transformer Pipeline
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
24

109. Transformer Pipeline
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
• Inject content
24

110. Transformer Pipeline
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
• Inject content
• Modify content
24

111. Transformer Pipeline
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
• Inject content
• Modify content
• Remove content
24

112. Transformer Pipeline
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
• Inject content
• Modify content
• Remove content
24

113. Transformer Pipeline
With great power
• Why?
• Allows a plugin developers to intercept the Confluence
content before or after Confluence operates on it
• Inject content
• Modify content
comes
• Remove content
great responsibility
24

114. The New Macro Interface
25

115. The New Macro Interface
• Confluence 4.0 introduces a new Macro
interface
25

116. The New Macro Interface
• Confluence 4.0 introduces a new Macro
interface
• Required for 4.0 integration
25

117. The New Macro Interface
• Confluence 4.0 introduces a new Macro
interface
• Required for 4.0 integration
• Default Macro body is rendered! (i.e. View
Format - HTML)
25

118. The New Macro Interface
• Confluence 4.0 introduces a new Macro
interface
• Required for 4.0 integration
• Default Macro body is rendered! (i.e. View
Format - HTML)
• How do you avoid this?
25

119. The New Macro Interface
26

120. The New Macro Interface
@Override
public String execute(
Map<String, String> parameters, String body, ConversionContext context)
throws MacroExecutionException {
26

121. The New Macro Interface
@Override
public String execute(
Map<String, String> parameters, String body, ConversionContext context)
throws MacroExecutionException {
@Override
@RequiresFormat(Format.Storage)
public String execute(
Map<String, String> parameters, String body, ConversionContext context)
throws MacroExecutionException {
26

122. The New Macro Interface
27

123. The New Macro Interface
• If you intend to output the body - You need to
render it!
27

124. The New Macro Interface
• If you intend to output the body - You need to
render it!
• Confluence provides an easy mechanism to do
this
27

125. The New Macro Interface
• If you intend to output the body - You need to
render it!
• Confluence provides an easy mechanism to do
this
• The XhtmlContent spring bean
27

126. The New Macro Interface
• If you intend to output the body - You need to
render it!
• Confluence provides an easy mechanism to do
this
• The XhtmlContent spring bean
• Storage Format to View
27

127. The New Macro Interface
• If you intend to output the body - You need to
render it!
• Confluence provides an easy mechanism to do
this
• The XhtmlContent spring bean
• Storage Format to View
• Wiki Markup to Storage Format
27

128. The New Macro Interface
28

129. The New Macro Interface
private final XhtmlContent xhtmlContent;
public MyAwesomeMacro(XhtmlContent xhtmlContent) {
this.xhtmlContent = xhtmlContent;
}
28

130. The New Macro Interface
private final XhtmlContent xhtmlContent;
public MyAwesomeMacro(XhtmlContent xhtmlContent) {
this.xhtmlContent = xhtmlContent;
}
@Override
@RequiresFormat(Format.Storage)
public String execute(Map<String, String> parameters, String body,
ConversionContext context) throws MacroExecutionException {
try {
return xhtmlContent.convertStorageToView(body, context);
}
...
28

131. Demo
29

132. Demo
Eric Chiang
29

133. Gliffy Confluence Plugin
Confluence 3.5
30

134. Gliffy Confluence Plugin
Confluence 3.5 Confluence 4.0
31

135. Macro Override
• <web-resource>
• editor scope
• Overrides default macro with our own function (insert menu and autocomplete)
• function gliffyCreateEdit()
• Constructs an AUI Dialog
• Ajax calls (getting templates, recent diagrams)
• Launches the Gliffy editor
32

136. Macro Image Placeholder
• Shows an attachment as an image
or renders it thru a pipeline
33

137. Property Panel
• Edit button (macro override)
• Image resize buttons
• Border button
• More button
AUI Dialog
34

138. Property Panel - Image Resize
• Simple macro re-render
35

139. Insert Menu
• web-item
36

140. Thanks Eric
37

141. Thanks Eric
• Insert Menu Web Item
37

142. Thanks Eric
• Insert Menu Web Item
• Macro Override
37

143. Thanks Eric
• Insert Menu Web Item
• Macro Override
• Property Panel
37

144. Thanks Eric
• Insert Menu Web Item
• Macro Override
• Property Panel
• Image Macro Placeholder
37

145. Passing The Torch
38

146. Passing The Torch
38

147. Passing The Torch
• Confluence Ecosystem
Integration
38

148. Passing The Torch
• Confluence Ecosystem
Integration
• Technical Point of Contact
inside Confluence
38

149. Passing The Torch
• Confluence Ecosystem
Integration
• Technical Point of Contact
inside Confluence
• Introducing......
38

150. Joseph Clark
38

151. Joseph Clark
• Confluence Team Lead
38

152. Joseph Clark
• Confluence Team Lead
• 2 Years on the Team
38

153. Joseph Clark
• Confluence Team Lead
• 2 Years on the Team
• .NET Background
38

154. Joseph Clark
• Confluence Team Lead
• 2 Years on the Team
• .NET Background
• All-round awesome fellow!
38

155. Joseph Clark
• Confluence Team Lead
• 2 Years on the Team
• .NET Background
• All-round awesome fellow!
• jclark@atlassian.com
38

156. Get Started Today
39

157. Get Started Today
39

158. Get Started Today
• Try out your plugin in
Confluence 4.0
39

159. Get Started Today
• Try out your plugin in
Confluence 4.0
• Play with the new plugin
points
39

160. Get Started Today
• Try out your plugin in
Confluence 4.0
• Play with the new plugin
points
• Check out the documentation
http://atlss.in/confluence4
39

161. Questions
?
Joseph Clark
jclark@atlassian.com
Ryan Thomas
rthomas@atlassian.com
http://atlss.in/confluence4
#atlascamp
40

162. Thank you!