Confluece User Macros - An underestimated feature worth looking into...

[#1]

Hi all,

I want to start a discussion on if & how user macros are used in Confluence Server instances around the world. At our company we use them quite a lot to get more out of existing Confluence macros, where the devs just stopped thinking...

A quick example

Everybody knows the Livesearch macro: It can be used to quick search your Confluence site with support for space & label filtering. You can even restrict the search to certain content types: Pages, blog posts, comments, space desc... And there they stopped thinking. Global search supports a filter on attachments. This macro does not. Seems that someone just didn't want us to have a decent attachment filter.

But that doesn't mean that the macro doesn't support attachment filtering. Creating a user macro which inserts the "attachment" content type instead of the ones offered in the selection does the job:

## Macro title: livesearchattachment
## Macro has a body: N
##
## @param Space:title=Space Key|type=string|desc=Empty:Current Space, @all:All spaces
## @param Placeholder:title=Placeholder|type=string|desc=Placeholder Text|default=Search Attachments...
## @param Instruction:title=Help Description|type=string|desc=Some help description displayed just below the search form|default=Minimum 3 chars, placeholder (*) is allowed and supported:

## Some param handling on the space parameter
## Use current space key & keep it if Space parameter is empty
## If @all is used, all spaces are searched by clearing the usespace variable
#set($usespace=$space.key)
#if($paramSpace && $paramSpace != '')
 #set($usespace = $paramSpace)
 #if($usespace == '@all')
 #set($usespace = '')
 #end
#end
## Create a livesearch macro (Use the Confluence Source Editor AddOn available for Server)
<p>
<ac:structured-macro ac:macro-id="c3ad7372-421a-4a73-a8fd-a63b5c3d95be" ac:name="livesearch" ac:schema-version="1">
 #if($usespace != '')
 ## Non empty space, filter on given space & do not display space name in results
 ## If no spaceKey parameter is generated, all spaces are searched
 <ac:parameter ac:name="spaceKey">
 <ri:space ri:space-key="$usespace"/>
 </ac:parameter>
 <ac:parameter ac:name="additional">none</ac:parameter>
 #end
 <ac:parameter ac:name="placeholder">$paramPlaceholder</ac:parameter>
 ## This one does the trick: Just set attachment as type...
 <ac:parameter ac:name="type">attachment</ac:parameter>
</ac:structured-macro>
</p>
#if($paramInstruction && $paramInstruction != '')
 <p<span style="font-size: 10px;">$paramInstruction</span></p>
#end

What do you need to start experimenting?

• A free addon (or app, whatever it's called today...) from the marketplace
  
  Confluence Source Editor
  
• Some knowledge on User Macros, Velocity (The language Confluence pages are rendered from) & (sometimes) reference documentation on the Confluence Java Server API
  
  Good starting point for writing User Macros
  
  
• A test or staging server is a good idea to use before deploying on a production site

What can go wrong?

Well, writing User Macros can only be done by System Admins. Atlassian might know why... These macros generate code inside a Confluence page. If you got a typo, forget to render valid HTML, etc... your page might be broken, ie. it doesn't display anymore, shows errors, etc.

What should work in these cases:

• Get a link to the broken page by using the space content tools & copy the link
• Paste the URL into a new browser tab
• Modify the URL to use editpage.action instead of viewpage.action
• Open the URL

The page should now be opened in Edit mode allowing to fix the possible macro. Another option is certainly fixing the macro itself...

Where does this head to?

Please comment on how you use User Macros. Should we create a sort of repository in the community? Is there a Bitbucket repo already collecting macros?

Feedback MOST welcome!

[Nic Brough -Adaptavist-]

https://confluence.atlassian.com/pages/viewpage.action?spaceKey=DISC&title=Shared+User+Macros could use some updating love (a lot of it was written for Confluence 3...)

[Davin Studer]

I agree that user macros can be super useful. Unfortunately, Atlassian hasn't done much with the editor in a while. A while ago I wrote some code to make the user macro editing experience a bit less painful. This discussion finally prompted me to do a writeup on it. If you are looking for a better user macro editing experience this might help. Maybe I should write up an article here as well.

https://iamdav.in/2018/03/21/fume-a-better-confluence-user-macro-editor/