AtlasCamp 2013: Confluence patterns

866 views

Published on

Published in: Technology, Business
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
866
On SlideShare
0
From Embeds
0
Number of Embeds
107
Actions
Shares
0
Downloads
7
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

AtlasCamp 2013: Confluence patterns

  1. 1. Confluence Patterns Getting the most out of your add-on Ryan Thomas Atlassian May 2013
  2. 2. About Me
  3. 3. About Me • OnDemand Team Lead • Ex-Confluence Developer • From Sydney, Australia • rthomas@atlassian.com • @RyanAtlassian
  4. 4. In Context
  5. 5. In Context Notification
  6. 6. In Context You’re Too Big Notification
  7. 7. In Context You’re Too Big Notification The 90%
  8. 8. In Context You’re Too Big Notification The 90%
  9. 9. What is a design pattern?
  10. 10. What is a design pattern? “a design pattern is a general reusable solution to a commonly occurring problem”
  11. 11. In Context Editor Pattern
  12. 12. In Context Pattern Making sure the object your macro creates is contextual inside of the editor!
  13. 13. In Context Pattern Making sure the object your macro creates is contextual inside of the editor!
  14. 14. In Context Pattern 1 A vanilla macro placeholder does not give enough context about the macro.
  15. 15. In Context Pattern 1 A vanilla macro placeholder does not give enough context about the macro. Use an Image Based Placeholder for your macro.
  16. 16. In Context Pattern 1
  17. 17. In Context Pattern 1
  18. 18. In Context Pattern 1 • Image Based Placeholders allow you to dynamically generate an image to use for rendering in the editor. • Easy to retrofit to your existing macros. https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as+a+Macro+Placeholder+in+the+Editor
  19. 19. In Context Pattern 1 • Image Based Placeholders allow you to dynamically generate an image to use for rendering in the editor. • Easy to retrofit to your existing macros. https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as+a+Macro+Placeholder+in+the+Editor
  20. 20. In Context Pattern 2 Your macro augments or modifies the properties of images.
  21. 21. In Context Pattern 2 Your macro augments or modifies the properties of images. Instead of using a macro, add this functionality to the Image Property Dialog.
  22. 22. In Context Pattern 2
  23. 23. In Context Pattern 2
  24. 24. In Context Pattern 2 • Allows you to extend the Image Property Dialog • Use it when your macro modifies the properties of images and you wish for more seamless integration with the editor. https://developer.atlassian.com/display/CONFDEV/Extending+the+Image+Properties+Dialog
  25. 25. In Context Pattern 3 Your macro generates a link when rendered.
  26. 26. In Context Pattern 3 Your macro generates a link when rendered. Extend the Link Browser Dialog to add the functionality here, instead of using a macro.
  27. 27. In Context Pattern 3
  28. 28. In Context Pattern 3 Select a repository...
  29. 29. In Context Pattern 3 • Useful for complex links, or links that require a lot of parameters. • Useful for links that have some administration setup • Simplifies the user experience. https://developer.atlassian.com/display/CONFDEV/Extending+the+Confluence+Insert+Link+Dialog
  30. 30. In Context Pattern 4 You would like to capture data a user pastes into the Confluence editor, to better represent it.
  31. 31. In Context Pattern 4 You would like to capture data a user pastes into the Confluence editor, to better represent it. Extend the editor autoconvert to convert userpasted data into any editor content you like.
  32. 32. In Context Pattern 4 • Register a paste handler • Can convert to images or arbitrary wiki content, not just macros!
  33. 33. In Context Pattern 4 • Register a paste handler • Can convert to images or arbitrary wiki content, not just macros! https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert
  34. 34. In Context Pattern Use Case Plugin Point Macro generates an image Image Based Placeholder Macro modifies images Extend the Image Dialog Macro create a link Extend the Link Dialog Capture user-pasted content Extend Autoconvert More Info https://developer.atlassian.com/display/CONFDEV/Providing+an+Image+as +a+Macro+Placeholder+in+the+Editor https://developer.atlassian.com/display/CONFDEV/Extending+the+Image +Properties+Dialog https://developer.atlassian.com/display/CONFDEV/Extending+the +Confluence+Insert+Link+Dialog https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert
  35. 35. You’re Too Big Editor Pattern
  36. 36. You’re Too Big Pattern Your macro has too many parameters, or you wish to provide a custom user experience.
  37. 37. You’re Too Big Pattern Your macro has too many parameters, or you wish to provide a custom user experience. Write a custom editor dialog for your macro.
  38. 38. You’re Too Big Pattern
  39. 39. You’re Too Big Pattern
  40. 40. You’re Too Big Pattern
  41. 41. You’re Too Big Pattern Easy to do! AJS.bind(“init.rte”, function() { AJS.MacroBrowser.setMacroJsOverride(“myMacro”, { opener: function(macro) { // Dialog drawing code goes here... } } }
  42. 42. You’re Too Big Pattern • Use AJS.MacroBrowser.setMacroJsOverride to override the editor functionality for a macro & display your own dialog. • Do this when you have too many parameters, or you want a custom editor experience. https://developer.atlassian.com/display/AUI/Dialog
  43. 43. You’re Too Big Pattern • Use AJS.MacroBrowser.setMacroJsOverride to override the editor functionality for a macro & display your own dialog. • Do this when you have too many parameters, or you want a custom editor experience. https://developer.atlassian.com/display/AUI/Dialog
  44. 44. Think of the 90% Editor Pattern
  45. 45. The 90% Pattern Think of the 90% use case!
  46. 46. The 90% Pattern Think of the 90% use case!
  47. 47. The 90% Pattern 1 You are building a macro with a number of common parameters.
  48. 48. The 90% Pattern 1 You are building a macro with a number of common parameters. Add them to the macro property panel.
  49. 49. The 90% Pattern 1 Extend the property panel with common parameters
  50. 50. The 90% Pattern 1 Extend the property panel with common parameters Colour preset buttons
  51. 51. The 90% Pattern 1 Extend the property panel with common parameters Text input field Colour preset buttons
  52. 52. var updateMacro = function(macroNode, param) {     var $macroDiv = AJS.$(macroNode);     AJS.Rte.getEditor().selection.select($macroDiv[0]);     AJS.Rte.BookmarkManager.storeBookmark();       var macroRenderRequest = {         contentId: Confluence.Editor.getContentId(), AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId",         macro: { function(e, macroNode) {             name: "status-light",      updateMacro(macroNode, "paramValue");             params: {"percentage": param}, }             defaultParameterValue: "", );             body : ""         }     };       tinymce.confluence.MacroUtils.insertMacro(macroRenderRequest); };
  53. 53. AJS.Confluence.PropertyPanel.Macro.registerButtonHandler("buttonId", function(e, macroNode) {      updateMacro(macroNode, "paramValue"); } ); https://developer.atlassian.com/display/CONFDEV/Extending+the+Macro+Property+Panel
  54. 54. The 90% Pattern 2 Your macro has many required parameters, trying to cater to every eventuality.
  55. 55. The 90% Pattern 2 Your macro has many required parameters, trying to cater to every eventuality. Think about the parameters you’re making required!
  56. 56. The 90% Pattern 2 The status macro does it wrong!
  57. 57. The 90% Pattern 2 Think about required parameters! • These will cause the macro edit dialog to always be displayed • Is the field actually required, or could you set a sensible default for it? • Using sensible defaults can lead to a smoother user experience
  58. 58. Notification Admin Pattern
  59. 59. Notification Pattern
  60. 60. Notification Pattern
  61. 61. Notification Pattern 1 You have configuration needed to be done by an administrator.
  62. 62. Notification Pattern 1 You have configuration needed to be done by an administrator. Create an Administration Task Item so that admins can track and complete the config.
  63. 63. Notification Pattern 1
  64. 64. Notification Pattern 1 Add a web-item to the system.admin.tasks/general section <web-item key="plugin-admin-task" section="system.admin.tasks/general" weight="150"> <label key="plugin.admin.task.title"/> <description key="plugin.admin.task.description"/> <link id="configure-mail">/admin/mail/viewmailservers.action</link> <condition class="com.atlassian.examples.DefaultMailServerExistsCondition" invert="true"/> </web-item> atlassian-plugin.xml
  65. 65. Notification Pattern 1 • Ensure your addon is correctly configured by creating an administrator task for it • Admin tasks display in the Confluence Administration page. • The can be checked off as completed by administrators https://developer.atlassian.com/display/CONFDEV/Creating+an+Admin+Task
  66. 66. Notification Pattern 2 You want to keep your users informed of what’s new when they install your plugin.
  67. 67. Notification Pattern 2 You want to keep your users informed of what’s new when they install your plugin. Configure a post-install-url for your plugin.
  68. 68. Notification Pattern 2
  69. 69. Notification Pattern 2 <plugin-info> <description>${project.description}</description> <version>${project.version}</version> <vendor name="${project.organization.name}" url="${project.organization.url}"/> <param name="configure.url">/plugins/servlet/configureServlet</param> <param name="post.install.url">/plugins/servlet/installServlet</param> <param name="post.update.url">/plugins/servlet/installServlet</param> </plugin-info> atlassian-plugin.xml
  70. 70. Notification Pattern 2 • Specifies a page that appears after installation, or update • Keep administrators up to date with the latest features of your addon • Only appears when installed via Atlassian Marketplace https://developer.atlassian.com/display/UPM/Plugin+Metadata+Files+used+by+UPM+and+Marketplace
  71. 71. In Context You’re Too Big Notification The 90%
  72. 72. In Context You’re Too Big Notification The 90%
  73. 73. In Context You’re Too Big Notification The 90%
  74. 74. In Context You’re Too Big Notification The 90%
  75. 75. In Context You’re Too Big Notification The 90%
  76. 76. In Context You’re Too Big Notification The 90%
  77. 77. In Context Notification https://developer.atlassian.com/ You’re Too Big The 90%
  78. 78. Thank you!

×