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

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

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

44.
Body just works
Eviction Notice

45.
Beyond The String

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

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

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

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

50.
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"/>

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

52.
Autocomplete fields - Hard?

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

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

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

56.
Here there be Dragons

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

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

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

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

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

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

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

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

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

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