AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor
7 likes•6,316 views
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.
![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.](https://image.slidesharecdn.com/confluencemacrosmadeeasy-101102182247-phpapp01/85/AtlasCamp-2010-Making-Confluence-Macros-Easy-for-the-user-Dave-Taylor-61-320.jpg)
AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor
- 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
- 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?
- 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’
- 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>
- 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
- 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>
- 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
- 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? • [email protected] • CAC - http://confluence.atlassian.com/display/ CONFDEV/Including+Information+in+your +Macro+for+the+Macro+Browser 54321