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 mac...
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 min...
What’s covered?
• Basic metadata - the browser
• Parameter metadata - the macro form
• JavaScript hook intro
• Demo (FIVE ...
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">
<!-- TO...
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....
my-plugin.my-macro.label=Awesome Macro
my-plugin.my-macro.desc=
An awesome test macro that displays the parameters
you pas...
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....
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/nin...
Eh? Where’s the Awesome?
Parameters Matter
<macro name="my-macro"
class="demo.ExampleMacro"
key="my-macro"
icon="/download/resources/my-plugin
/ima...
Browsing is GO
<parameters/>
ALWAYS
ADD
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 jus...
That’s Some String...
But my parameters aren’t named!
{my-macro:foo}
<parameters>
<parameter name="" type="string"/>
<parameters>
my-plugin.my-m...
But my parameters aren’t named!
{my-macro:foo}
{my-macro:foo|bar}
<parameters>
<parameter name="" type="string"/>
<paramet...
<parameters>
<parameter name="" type="string">
<alias name="str-prm"/>
<alias name="string-param"/>
</parameter>
<paramete...
<parameters>
<parameter name="string-param" type="string">
<alias name=""/>
<alias name="str-prm"/>
</parameter>
<paramete...
Making fields required
<parameters>
<parameter name="string-param" type="string"
required="true"/>
<parameters>
NoValue, 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 outpu...
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 n...
Basic types - other
<parameter name="int-param" type="int"/>
<parameter name="relativedate-param" type="relativedate"/>
<p...
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="boo...
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"/>
</paramet...
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="downloa...
No API, No docs, No worries
AJS.MacroBrowser.setMacroJsOverride(macroName, override)
The override object has optional prop...
No API, No docs, No worries
override.fields
- overrides the parameter field UI based on
parameter type or parameter name
ov...
No API, No docs, No worries
override.beforeParamsSet
- a function to run before an existing macro is loaded into
the param...
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...
Questions?
• david.taylor@atlassian.com
• CAC - http://confluence.atlassian.com/display/
CONFDEV/Including+Information+in+y...
AtlasCamp 2010: Making Confluence Macros Easy (for the user) - Dave Taylor
Prochain SlideShare
Chargement dans…5
×

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

7 996 vues

Publié le

Publié dans : Technologie
0 commentaire
5 j’aime
Statistiques
Remarques
  • Soyez le premier à commenter

Aucun téléchargement
Vues
Nombre de vues
7 996
Sur SlideShare
0
Issues des intégrations
0
Intégrations
1 082
Actions
Partages
0
Téléchargements
54
Commentaires
0
J’aime
5
Intégrations 0
Aucune incorporation

Aucune remarque pour cette diapositive

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

×