It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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

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!

2 comments

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

 @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?!? ;-)

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

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/

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.

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

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 Community Leader Mar 22, 2018

I went ahead and wrote the article.

Comment

Log in or Sign up to comment
TAGS
Community showcase
Posted in Confluence

What project did you transition or start on Confluence with the shift to remote work?

It’s been great to hear from fellow users over the last few weeks about the best tips and fun moments you’ve had working on Confluence since the transition to working remote. I’d love to keep the c...

397 views 11 11
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you