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

[JanR]

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...)

[JanR]

 @Nic Brough -Adaptavist- I knew that one, but it's slightly outdated... I just wanted to bring up the topic into focus, because there are so many things one do.

Any more examples of Scriptrunner macros collected somewhere?!? ;-)

[Nic Brough -Adaptavist-]

Yes, I know, that's why I said it could use some love.  People don't get just how powerful user macros can be!  Usually the first thing I go for when someone needs something that can't be done with plain Confluence.

I keep nagging the SR team to do something useful with their docs - they're awful and really should have a library of useful scripts.

On the other hand, SR is likely to change soon, obviating the need for a huge library...

[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/

[Nic Brough -Adaptavist-]

You're biased!  Just because the majority of the good user macros I run into are the ones you wrote, and half the rest are ones I wrote based on yours... Oh.

[JanR]

David,

great idea. I’ll try your editor tomorrow, while I’m using an external editor when editing for now. What about some articles, explaining what can be done with User Macros. 

Some ideas:

• Simple attachment list which links the file name to the preview and/or download option. We use this inside page property macros to generate reports where the attachments can be previewed without opening the pages...
• Space restrictions overview
• User specific links / iFrames
• ...

 I’ll bookmark your excellent blog...

Cheers,

Jan-Peter

[Nic Brough -Adaptavist-]

Another random example - I just wrote one that formats text and excerpts differently for displaying in document headings if a user is in a particular group. 

The library I linked to above is a really good long list of things you can do with user macros.

[Davin Studer]

I went ahead and wrote the article.