Making Confluence Macros Easy

(for the user)

(in 5 minutes)

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?

Fear & Loathing

• Confluence 4.0 == no wiki markup editor

• Macro metadata or bust

Always look on the bright side

• Macro Browser is your advertisement

• Browse / Search

• No more notation guide

• Five minutes

What’s covered?

• Basic metadata - the browser

• Parameter metadata - the macro form

• JavaScript hook intro

• Demo (FIVE MINUTES)

Who’s talking?

• David Taylor

• Confluence Developer

• 3 years on front-end features

• Co-wrote the Macro Browser

Macro Browser History 101

June 2009 - Confluence 3.0

December 2009 - Confluence 3.1

March 2010 - Confluence 3.2

July 2010 - Confluence 3.3

Basic Metadata

The Sample macro

• Just tests input/output

• Keeps your eyes on the form, ignores the rendered output

The generated descriptor.

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

Your macro looks like... meh

You might have missed that?

You need:

NINJA HAMSTER

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

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

Now yo pimpin’

Search on description

Autocomplete on the cheap

<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

The basic Macro form

The basic Macro form

<parameters>

But first...

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>

Eh? Where’s the Awesome?

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>

Browsing is GO

<parameters/>

ALWAYSADD

And your little form, too!

<parameter>

Basic types - string

<parameters> <parameter name="string-param" type="string"/></parameters>

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

That’s Some String...

But my parameters aren’t named!

{my-macro:foo}

<parameters> <parameter name="" type="string"/><parameters>

my-plugin.my-macro.param..label=A String Parameter

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>

<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

<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

Making fields required

<parameters> <parameter name="string-param" type="string" required="true"/><parameters>

No Value, No Insert

Body just works

public boolean hasBody(){ return false;}

public boolean hasBody(){ return true;}

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

Body just works

Eviction Notice

Beyond The String

Basic types - boolean

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

Basic types - enum

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

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

Defaults - just for looks

<parameter name="int-param" type="int" default="42"/>

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

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

Autocomplete fields - Hard?

Not really

<parameter name="content-param" type="confluence-content"/>

Filtering? <option>

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

Spaces, Users, Easy

<parameter name="spacekey-param" type="spacekey"/><parameter name="username-param" type="username"/>

Here there be Dragons

Multiples? Er. Um.

<parameter name="username-param" type="username" multiple="true"/>

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>

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

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.

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

Office Connector JS madness, then

a 5 minute demo...

...using the Atlassian SDK...

• atlas-run

• atlas-cli

... and FastDev

• Bleeding edge!

• Re-installs the plugin on page refresh, based on a URL filter

Your move!

• This slideshow in the usual place

• List your macros

• Update for the Browser

• Update for the Form

• Go nuts with the JavaScript

Questions?

• david.taylor@atlassian.com

• CAC - http://confluence.atlassian.com/display/CONFDEV/Including+Information+in+your+Macro+for+the+Macro+Browser

54321