AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor

7,962 views

Published on

Published in: Technology
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
7,962
On SlideShare
0
From Embeds
0
Number of Embeds
1,082
Actions
Shares
0
Downloads
54
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide

AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor

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

×