atlascamp 2010: making confluence macros easy (for the user) - dave taylor
TRANSCRIPT
![Page 1: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/1.jpg)
Making Confluence Macros Easy
(for the user)
(in 5 minutes)
![Page 2: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/2.jpg)
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?
![Page 3: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/3.jpg)
Fear & Loathing
• Confluence 4.0 == no wiki markup editor
• Macro metadata or bust
![Page 4: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/4.jpg)
Always look on the bright side
• Macro Browser is your advertisement
• Browse / Search
• No more notation guide
• Five minutes
![Page 5: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/5.jpg)
What’s covered?
• Basic metadata - the browser
• Parameter metadata - the macro form
• JavaScript hook intro
• Demo (FIVE MINUTES)
![Page 6: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/6.jpg)
Who’s talking?
• David Taylor
• Confluence Developer
• 3 years on front-end features
• Co-wrote the Macro Browser
![Page 7: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/7.jpg)
Macro Browser History 101
![Page 8: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/8.jpg)
June 2009 - Confluence 3.0
![Page 9: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/9.jpg)
December 2009 - Confluence 3.1
![Page 10: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/10.jpg)
March 2010 - Confluence 3.2
![Page 11: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/11.jpg)
July 2010 - Confluence 3.3
![Page 12: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/12.jpg)
Basic Metadata
![Page 13: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/13.jpg)
The Sample macro
• Just tests input/output
• Keeps your eyes on the form, ignores the rendered output
![Page 14: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/14.jpg)
The generated descriptor.
<macro name="confluence-macro-metadata-plugin" class="demo.ExampleMacro" key="my-macro"> <!-- TODO: Add macro description --> <!-- <description></description> --></macro>
![Page 15: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/15.jpg)
Your macro looks like... meh
You might have missed that?
![Page 16: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/16.jpg)
You need:
NINJA HAMSTER
![Page 17: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/17.jpg)
<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" />
![Page 18: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/18.jpg)
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
![Page 19: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/19.jpg)
Now yo pimpin’
![Page 20: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/20.jpg)
Search on description
![Page 21: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/21.jpg)
Autocomplete on the cheap
![Page 22: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/22.jpg)
<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
![Page 23: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/23.jpg)
The basic Macro form
![Page 24: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/24.jpg)
The basic Macro form
![Page 25: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/25.jpg)
<parameters>
![Page 26: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/26.jpg)
But first...
![Page 27: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/27.jpg)
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>
![Page 28: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/28.jpg)
Eh? Where’s the Awesome?
![Page 29: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/29.jpg)
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>
![Page 30: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/30.jpg)
Browsing is GO
<parameters/>
ALWAYSADD
![Page 31: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/31.jpg)
And your little form, too!
![Page 32: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/32.jpg)
<parameter>
![Page 33: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/33.jpg)
Basic types - string
<parameters> <parameter name="string-param" type="string"/></parameters>
![Page 34: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/34.jpg)
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
![Page 35: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/35.jpg)
That’s Some String...
![Page 36: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/36.jpg)
But my parameters aren’t named!
{my-macro:foo}
<parameters> <parameter name="" type="string"/><parameters>
my-plugin.my-macro.param..label=A String Parameter
![Page 37: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/37.jpg)
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>
![Page 38: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/38.jpg)
<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
![Page 39: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/39.jpg)
<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
![Page 40: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/40.jpg)
Making fields required
<parameters> <parameter name="string-param" type="string" required="true"/><parameters>
![Page 41: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/41.jpg)
No Value, No Insert
![Page 42: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/42.jpg)
![Page 43: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/43.jpg)
Body just works
public boolean hasBody(){ return false;}
public boolean hasBody(){ return true;}
![Page 44: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/44.jpg)
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
![Page 45: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/45.jpg)
Body just works
Eviction Notice
![Page 46: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/46.jpg)
Beyond The String
![Page 47: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/47.jpg)
Basic types - boolean
<parameters> ... <parameter name="boolean-param" type="boolean"/> ...</parameters>
![Page 48: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/48.jpg)
Basic types - enum
<parameter name="enum-param" type="enum" required="true"> <value name=""/> <value name="foo"/> <value name="bar"/> <value name="baz"/></parameter>
![Page 49: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/49.jpg)
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
![Page 50: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/50.jpg)
Defaults - just for looks
<parameter name="int-param" type="int" default="42"/>
![Page 51: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/51.jpg)
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"/>
![Page 52: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/52.jpg)
Funky Shit(oh my god, that’s some)
![Page 53: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/53.jpg)
Autocomplete fields - Hard?
![Page 54: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/54.jpg)
Not really
<parameter name="content-param" type="confluence-content"/>
![Page 55: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/55.jpg)
Filtering? <option>
<parameter name="content-param" type="confluence-content"> <option key="type" value="page"/></parameter>
![Page 56: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/56.jpg)
Spaces, Users, Easy
<parameter name="spacekey-param" type="spacekey"/><parameter name="username-param" type="username"/>
![Page 57: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/57.jpg)
Here there be Dragons
![Page 58: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/58.jpg)
Multiples? Er. Um.
<parameter name="username-param" type="username" multiple="true"/>
![Page 59: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/59.jpg)
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>
![Page 60: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/60.jpg)
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
![Page 61: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/61.jpg)
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.
![Page 62: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/62.jpg)
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
![Page 63: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/63.jpg)
Office Connector JS madness, then
a 5 minute demo...
![Page 64: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/64.jpg)
...using the Atlassian SDK...
• atlas-run
• atlas-cli
![Page 65: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/65.jpg)
... and FastDev
• Bleeding edge!
• Re-installs the plugin on page refresh, based on a URL filter
![Page 66: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/66.jpg)
Your move!
• This slideshow in the usual place
• List your macros
• Update for the Browser
• Update for the Form
• Go nuts with the JavaScript
![Page 67: AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor](https://reader034.vdocuments.site/reader034/viewer/2022052122/5557f514d8b42a200d8b4b55/html5/thumbnails/67.jpg)
Questions?
• CAC - http://confluence.atlassian.com/display/CONFDEV/Including+Information+in+your+Macro+for+the+Macro+Browser
54321