This document discusses how to add metadata to Confluence macros to improve the user experience. It covers adding basic metadata like the macro name, description and icon to make it visible in the macro browser. It also covers adding parameter metadata to generate a user-friendly macro form. JavaScript hooks can be used to further customize the form. The presentation demonstrates these techniques through an example macro and encourages attendees to apply them to their own macros to integrate with the macro browser and improve discoverability.

1. Making Confluence
Macros Easy
(for the user)
(in 5 minutes)

2. Throw your hands in the air!
• Written a Confluence plugin?
• Written a Confluence macro?
• Added basic metadata for all macros?
• For all macro parameters?
• With a custom user interface?

3. Fear & Loathing
• Confluence 4.0 == no wiki markup editor
• Macro metadata or bust

4. Always look on the bright side
• Macro Browser is your advertisement
• Browse / Search
• No more notation guide
• Five minutes

5. What’s covered?
• Basic metadata - the browser
• Parameter metadata - the macro form
• JavaScript hook intro
• Demo (FIVE MINUTES)

6. Who’s talking?
• David Taylor
• Confluence Developer
• 3 years on front-end features
• Co-wrote the Macro Browser

7. Macro Browser
History 101

8. June 2009 - Confluence 3.0

9. December 2009 - Confluence 3.1

10. March 2010 - Confluence 3.2

11. July 2010 - Confluence 3.3

12. Basic Metadata

13. The Sample macro
• Just tests input/output
• Keeps your eyes on the form,
ignores the rendered output

14. The generated descriptor.
<macro name="confluence-macro-metadata-plugin"
class="demo.ExampleMacro"
key="my-macro">
<!-- TODO: Add macro description -->
<!-- <description></description> -->
</macro>

15. Your macro looks like... meh
You might have
missed that?

16. You need:
NINJA HAMSTER

17. <macro name="my-macro"
class="demo.ExampleMacro"
key="my-macro"
icon="/download/resources/my-plugin
/images/ninja-hamster.png" >
<description>A macro that tests metadata</description>
</macro>
Some basic metadata
<resource type="download" key="images" name="images/"
location="demo/images"/>
<resource type="i18n" name="i18n" location="demo/i18n" />

18. my-plugin.my-macro.label=Awesome Macro
my-plugin.my-macro.desc=
An awesome test macro that displays the parameters
you pass it.
I18N by convention

19. Now yo pimpin’

20. Search on description

21. Autocomplete on the cheap

22. <macro name="my-macro"
class="demo.ExampleMacro"
key="my-macro"
icon="/download/resources/my-plugin
/images/ninja-hamster.png"
documentation-url="http://atlassian.com">
<description>A macro that tests metadata</description>
</macro>
documentation-url

23. The basic Macro form

24. The basic Macro form

25. <parameters>

26. But first...

27. Categories
<macro name="my-macro"
class="demo.ExampleMacro"
key="my-macro"
icon="/download/resources/my-plugin
/images/ninja-hamster.png"
documentation-url="http://atlassian.com">
<description>A macro that tests metadata</description>
<category>admin</category>
</macro>

28. Eh? Where’s the Awesome?

29. Parameters Matter
<macro name="my-macro"
class="demo.ExampleMacro"
key="my-macro"
icon="/download/resources/my-plugin
/images/ninja-hamster.png"
documentation-url="http://atlassian.com">
<description>A macro that tests metadata</description>
<category>admin</category>
<parameters/>
</macro>

30. Browsing is GO
<parameters/>
ALWAYS
ADD

31. And your little form, too!

32. <parameter>

33. Basic types - string
<parameters>
<parameter name="string-param" type="string"/>
</parameters>

34. my-plugin.my-macro.param.string-param.label=
A String Parameter
my-plugin.my-macro.param.string-param.desc=
This field just takes a string. Anything will do.
I18N by convention 2

35. That’s Some String...

36. But my parameters aren’t named!
{my-macro:foo}
<parameters>
<parameter name="" type="string"/>
<parameters>
my-plugin.my-macro.param..label=
A String Parameter

37. But my parameters aren’t named!
{my-macro:foo}
{my-macro:foo|bar}
<parameters>
<parameter name="" type="string"/>
<parameters>
<parameters>
<parameter name="" type="string"/>
<parameter name="" type="string"/>
<parameters>

38. <parameters>
<parameter name="" type="string">
<alias name="str-prm"/>
<alias name="string-param"/>
</parameter>
<parameters>
Multiple names? Aliases!
{my-macro:foo}
{my-macro:str-prm=foo}
{my-macro:string-param=foo}
my-plugin.my-macro.param..label=
A String Parameter

39. <parameters>
<parameter name="string-param" type="string">
<alias name=""/>
<alias name="str-prm"/>
</parameter>
<parameters>
Multiple names? Aliases!
{my-macro:foo}
{my-macro:str-prm=foo}
{my-macro:string-param=foo}
my-plugin.my-macro.param.string-param.label=
A String Parameter

40. Making fields required
<parameters>
<parameter name="string-param" type="string"
required="true"/>
<parameters>

41. NoValue, No Insert

43. Body just works
public boolean hasBody()
{
return false;
}
public boolean hasBody()
{
return true;
}

44. my-plugin.my-macro.body.label=
Macro Body Here
my-plugin.my-macro.body.desc=
Text in here gets rendered in the macro output
Body just works

45. Body just works
Eviction Notice

46. Beyond The String

47. Basic types - boolean
<parameters>
...
<parameter name="boolean-param" type="boolean"/>
...
</parameters>

48. Basic types - enum
<parameter name="enum-param" type="enum" required="true">
<value name=""/>
<value name="foo"/>
<value name="bar"/>
<value name="baz"/>
</parameter>

49. Basic types - other
<parameter name="int-param" type="int"/>
<parameter name="relativedate-param" type="relativedate"/>
<parameter name="url-param" type="url"/>
<parameter name="color-param" type="color"/>
<parameter name="label-param" type="label"/>
<parameter name="date-param" type="date"/>
<parameter name="group-param" type="group"/>
PARKED

50. Defaults - just for looks
<parameter name="int-param" type="int" default="42"/>

51. Order matters
<parameter name="username-param"
type="username"
required="true"/>
<parameter name="boolean-param"
type="boolean"/>
<parameter name="string-param"
type="string"/>
<parameter name="int-param"
type="int"/>

52. Funky Shit
(oh my god, that’s some)

53. Autocomplete fields - Hard?

54. Not really
<parameter name="content-param" type="confluence-content"/>

55. Filtering? <option>
<parameter name="content-param" type="confluence-content">
<option key="type" value="page"/>
</parameter>

56. Spaces, Users, Easy
<parameter name="spacekey-param" type="spacekey"/>
<parameter name="username-param" type="username"/>

57. Here there be Dragons

58. Multiples? Er. Um.
<parameter name="username-param" type="username"
multiple="true"/>

59. JavaScript hooks
<web-resource key="macro-browser-smart-fields"
name="Macro Browser Smart Fields">
<resource type="download"
name="oc-macro-fields.js"
location="javascript/oc-macro-fields.js" />
<dependency>confluence.editor.actions:
editor-macro-browser</dependency>
<context>macro-browser</context>
</web-resource>

60. No API, No docs, No worries
AJS.MacroBrowser.setMacroJsOverride(macroName, override)
The override object has optional properties:
- fields,
- beforeParamsSet,
- beforeParamsRetrieved
- and some _really_ obscure ones

61. No API, No docs, No worries
override.fields
- overrides the parameter field UI based on
parameter type or parameter name
override.fields.string[“my-param”] = function(param) {
return AJS.MacroBrowser.ParameterFields["_hidden"]
(param, {});
}
- uses a hidden HTML text field for the “my-param” string
parameter.

62. No API, No docs, No worries
override.beforeParamsSet
- a function to run before an existing macro is loaded into
the parameter form fields
override.beforeParamsRetrieved
- a function to run before the form fields are converted
into a macro parameter string

63. Office Connector
JS madness, then
a 5 minute demo...

64. ...using the Atlassian SDK...
• atlas-run
• atlas-cli

65. ... and FastDev
• Bleeding edge!
• Re-installs the plugin on page refresh, based
on a URL filter

66. Your move!
• This slideshow in the usual place
• List your macros
• Update for the Browser
• Update for the Form
• Go nuts with the JavaScript

67. Questions?
• david.taylor@atlassian.com
• CAC - http://confluence.atlassian.com/display/
CONFDEV/Including+Information+in+your
+Macro+for+the+Macro+Browser
54321