Cheese can be a wonderful thing, but not all cheeses are created equal. For example Easy Cheese is filth, whereas Stinking Bishop is pure gold.

The Cheese Macro in Confluence is great, but it’s a bit generic. It obviously wasn’t written with quality or localisation in mind. I find that it’s a bit too limited in scope for my needs.

To resolve this problem, I’ve created British Cheese, a user macro that celebrates the quality milk-based food products of the British Isles.

## Macro title: British Cheese
## Macro has a body: N
## Body processing: n/a
## Output: Selected output option
##
## Developed by: David Simpson <david@davidsimpson.me>
## Date created: 2012-05-08
## Installed by: My Name

## @param Type:title=Variety|type=enum|enumValues=Caerphilly,Cheddar,Cheshire,Cornish Yarg,Derby,Double Gloucester,Lancashire,Red Leicester,Shropshire Blue,Stilton,Wensleydale,White Stilton|default=Shropshire Blue|desc=Choose your favourite British cheese

#set ($url = $paramType.replaceAll(" ","").toLowerCase())

I love <a href="http://www.britishcheese.com/${url}">$paramType</a>!

If you like this user macro but don’t agree that Britain produces the finest cheese on the planet, why not create your own localised version of it. Maybe call it something like {käse} or {fromage}.

Photo credit: Stilton

Thomas Emil Hansen recently wrote How do I write a user macro with “sections” and “panels” using the 4.0 HTML template?

With Confluence 4, the storage format has changed from traditional wiki markup to an XML based storage format. This means that all those old wiki-markup based user macros are now overdue some TLC. Luckily, there’s always the “Insert Wiki Markup” dropdown in the Confluence editor to fall back on.

To convert your macro…

1. Create a new page and use the “Insert Wiki Markup” function to add your wiki markup:

   {section}
     {column}
       $body
     {column}
     {column:width=300px}
       {panel}
         *Contents:*
         {toc:maxLevel=3}
       {panel}
     {column}
   {section}
   

2. Save the page
3. From the Tools menu, select View Storage Format. This will give you:

   <ac:macro ac:name="section">
       <ac:rich-text-body>
           <ac:macro ac:name="column">
               <ac:rich-text-body>
                   <p>$body</p>
               </ac:rich-text-body>
           </ac:macro>
           <ac:macro ac:name="column">
               <ac:parameter ac:name="width">300px</ac:parameter>
               <ac:rich-text-body>
                   <ac:macro ac:name="panel">
                       <ac:rich-text-body>
                           <p><strong>Contents:</strong></p>
                           <ac:macro ac:name="toc">
                               <ac:parameter ac:name="maxLevel">3</ac:parameter>
                           </ac:macro>
                       </ac:rich-text-body>
                   </ac:macro>
               </ac:rich-text-body>
           </ac:macro>
       </ac:rich-text-body>
   </ac:macro>
   

4. Paste this into your user macro rather than the old-fangled wiki markup.
5. Repeat this procedure for all user macros you wish to convert.

From a recent comment on Atlassian Answers, Norman Hills asked “Is it possible to reverse the order in which comments appear?”

This is straightforward if done client-side, so I’ve written it up here.

If you just want to reverse the order for good, browse to Confluence Admin | Look & Feel | Custom HTML

Add this to At the end of the HEAD:

<script>
  AJS.toInit(function(){
    $comments = AJS.$('#page-comments');
    $comments.children().each(function(i,li){$comments.prepend(li)});
  });
</script>

Job done.

For extra points

If you want to be able to reverse the order, then it’s slightly more effort.

Browse to Confluence Admin | Look & Feel | Custom HTML

Add this to At the end of the HEAD:

<script>
  function reverseCommentOrder(){
    $comments = AJS.$('#page-comments');
    $comments.children().each(function(i,li){$comments.prepend(li)});
  }

  AJS.toInit(function(){
    // reverse the comment order
    reverseCommentOrder();

    // add a link to reverse the order
    AJS.$('#comments-section-title').append('<a id="page-comments-reverse" href="#">(Reverse Order)</a>');
    AJS.$('#page-comments-reverse').css({ 'color':'#999','font-size':'0.65em'})
                                   .click(function(e){
      reverseCommentOrder();
      e.preventDefault();
    });
  });
</script>

That’s all. Have fun.

Want to use some “hot” new web fonts to pimp your Confluence wiki?

It’s really straightforward. This post describes a method by which you can change all the headings to use web fonts hosted by Google.

Site-wide web fonts

Using Rokkitt font

Browse to Confluence Administration | Look and Feel | Custom HTML

In At end of the HEAD paste:

<!-- Fonts for headings -->
<link href='http://fonts.googleapis.com/css?family=Rokkitt:400,700'
      rel='stylesheet' type='text/css'>
<style>
#com-atlassian-confluence h1,
#com-atlassian-confluence h2,
#com-atlassian-confluence h3,
#com-atlassian-confluence h4,
#com-atlassian-confluence h5,
#com-atlassian-confluence h6 {
	font-family: 'Rokkitt', serif;
	font-weight : bold;
}
</style>

Please note that adding inline styles is not big or clever, but it is quick and easy for the purpose of this blogpost.

This results in a layout similar to the screenshot below:

Using Leckerli One font

Was that too corporate? Then lets have some handwriting…

Browse to Confluence Administration | Look and Feel | Custom HTML

In At end of the HEAD paste:

<!-- Fonts for headings -->
<link href='http://fonts.googleapis.com/css?family=Leckerli+One:400'
      rel='stylesheet' type='text/css'>
<style>
#com-atlassian-confluence h1,
#com-atlassian-confluence h2,
#com-atlassian-confluence h3,
#com-atlassian-confluence h4,
#com-atlassian-confluence h5,
#com-atlassian-confluence h6 {
	font-family: 'Leckerli One', cursive;
}
</style>

Now, you’ll get something like this:

I’m not sure that this is a good look, but never mind.

Web fonts for a single space

Want to just mess up the fonts in a single space?

Then, duplicate the content of the Google hosted stylesheet — for example http://fonts.googleapis.com/css?family=Leckerli+One:400 and add to the space stylesheet…

Browse to Browse | Space Admin | Look and Feel | Stylesheet.

Click on Edit and paste in:

/* Duplicated from http://fonts.googleapis.com/css?family=Leckerli+One:400 */
@font-face {
  font-family: 'Leckerli One';
  font-style: normal;
  font-weight: normal;
  src: local('LeckerliOne'), url('http://themes.googleusercontent.com/static/fonts/leckerlione/v2/S2Y_iLrItTu8kIJTkS7DrKRDOzjiPcYnFooOUGCOsRk.woff') format('woff');
}

/* Targetting Confluence heading  */
#com-atlassian-confluence h1,
#com-atlassian-confluence h2,
#com-atlassian-confluence h3,
#com-atlassian-confluence h4,
#com-atlassian-confluence h5,
#com-atlassian-confluence h6 {
	font-family: 'Leckerli One', cursive;
}

This will only affect the space in which you add the CSS and will override the global styles.

I’m not sure whether the URL for the font will remain constant in the long term though, so you may have to repeat this process.

Be careful

There are plenty of web font services and many, many fonts to choose from. With great power comes great responsibility, so be careful.

People have been shouting from the rooftops that Confluence 4 has finally arrived. Despite all the hype, it’s a cracking release. I’m not going to list all the features here, as you can find them elsewhere. However I will mention one…

The new editor

Simply put, it’s fast, slick and gorgeous looking. It works better than any online editor I’ve used elsewhere. It is a design that would make Antoine de Saint-Exupéry proud.

Wiki markup is dead

Past experience shows that people’s fondness of wiki markup is somewhat akin to that of Marmite. So it seems quite a bold step to ditch this aspect of the editor for something completely new.

Long live wiki markup

The good news is that behind the scenes, wiki markup is alive and well — all the new editor’s great keyboard shortcuts are based off of the syntax that many people know so well.

The final irony being that wiki markup haters may just start using wiki markup in their “faster, richer, simpler” editing experience.

Now, see what I mean:

Find out more.

A quick demo of a Confluence plugin for a staff & student directory at the University of Nottingham.

Developed by David Simpson and Shaun Hare back in 2010.

The University of Nottingham started using Concur‘s online travel & expense management system towards the end of 2010. They needed a simple method of accessing the Concur system from their travel and expenses documentation (hosted in Confluence) without addtitional authentication prompts.

A SAML-based single sign-on plugin for Confluence was rapidly designed and built over the course of a single week. Here’s a demonstration of the basic functionality:

Last week I released Analytics Plugin for Confluence 1.2 on the Atlassian Plugin Exchange.

It’s been 6 months since the initial release which was only tested on Confluence 3.0. This time I’ve added a new dashboard section, full support for Confluence 3.1 & 3.2 and a pile of macro parameters as requested by Guy Fraser. The release notes are here. Confluence 3.3 is just around the corner, so I’ll add an update for that when it comes out.

Thank you

The Confluence community has shown a great deal of support and encouragement since the plugin was originally released. For example, Atlassian blogged about it before I got a chance to. So thanks to all for your support.

The plugin was name checked by Sherif Mansour – Atlassian’s Product Manager for Confluence in the Confluence State of the Union presentation at Atlassian Summit 2010 at the start of the month. Watch it all, but concentrate especially around 5:10!

This week Google approved the plugin for their Google Analytics Application Gallery — take a look here. The Apps Gallery has only been going for about a month so I’m really excited about being a part of it. The slight name change and new logo were done to fit in with the Application Gallery Policy.

In the future

The next release should support Confluence 3.3 and also complete tracking of all pages in a space — not just those with a URL starting /display/spaceKey/ — based on this hack :

// Add a page-level custom variable to record the space-key
if (typeof jQuery('meta[name=confluence-space-key]').attr("content") == 'string')
{
  pageTracker._setCustomVar(
    1, // This custom var is set to slot #1 of 5

    // The name acts as a kind of category for the user activity
    'confluence-space-key',    

    // This value of the custom variable
    jQuery('meta[name=confluence-space-key]').attr("content"), 

    3 // Sets the scope to page-level
  );
}

— If you want to use this hack now, try out this custom Google Analytics report which will allow you to take advantage of it now.

I’d also like to add full space specific tracking for attachments too.

A quick demo

And finally, this is what the new version looks like:

Related Posts

• Tracking Atlassian Confluence usage with Google Analytics
• 4 Useful Tips on Google Analytics Reporting for Confluence
• Announcing: Google Analytics plugin for Confluence – original release

Update: 2011-09-20 With the release of Confluence 4.0, this post obsolete.

A simple Confluence user macro to hide access to the View Wiki Markup menu link…

{hide-wiki-markup}

One thing I love about Confluence is the way that you can browse other people’s pages and steal their superior layout ideas for your own wiki pages.

It’s dead easy to do. Go to the Tools drop down menu and click on the View Wiki Markup link. A new window will open containing the wiki markup for the page. You can now copy the bits you like and discard the rest. Your friends and colleagues will be impressed by your wiki skills and you can continue on your path to becoming a wiki ninja.

But what if you don’t want to share those wiki markup skills?
That’s not very collaborative, I know. But there are entirely valid reasons that you’d wish to disable this feature.

An example of this is use of the {sql} plugin. This is a really powerful plugin that allows you to query databases and tabulate the results in Confluence. Wrap this in a {chart} macro and you have an instant graph. Nice work! There’s a great blog post at Atlassian that use this to great effect.

Security

However, using this kind of markup on a public website is a bad idea. Exposing the structure of your databases to people you don’t know and can’t trust is somewhat short sighted. On a company intranet, the risk is still there, but hopefully it is not so dangerous. Even so, it’s really best not to show this information in the first place.

What can we do about it?

The best solution would be additional security in the product that allows editors to prevent others from viewing wiki markup. It would probably go in the Restrictions screen. This does seem somewhat like a paranoid feature request, but call me paranoid.

Another way is to use Javascript to remove the link from the DOM. This is not a replacement for good security, but will stop the casual user from accessing the wiki markup.

It is easily done in a user macro:

As a Confluence administrator, go to Confluence Admin | User Macros and click on Create a User Macro.

Fill out the form…
Macro name: hide-wiki-markup
Output: Macro generates HTML markup
Template:

<script type="text/javascript">
jQuery('#action-view-source-link').parent().hide(); /*Updated from .remove(); Aug 2010*/
</script>

I’ve previously written a number of posts about Confluence and Google Analytics (GA), including how to set up GA on Confluence and pointers for GA reports you should consider. Lastly, I wrote the Confluence Google Analytics Plugin (CGAP) which provides space specific GA reports from within Confluence.

However, I’ve not been entirely happy because there wasn’t a method to allow complete tracking of all space specific Confluence pages using CGAP or the reports that I’ve previously described.

This has been documented elsewhere, but briefly, the problem is with…

• pages with punctuation in the title e.g. This page is bad for Analytics, isn’t it? (hover on the link to see the URI)
• short URLs e.g. /x/2Bq9Ag
• space administration e.g. /spaces/spaceadmin.action?key=spaceKey
• page edits e.g./pages/editpage.action?pageId=XXXX
• page creation e.g. /pages/createpage.action?spaceKey=spaceKey&fromPageId=XXXX
• add/view attachments e.g. /pages/viewpageattachments.action?pageId=XXXX
• page history e.g. /pages/viewpreviousversions.action?pageId=XXXX
• view wiki markup e.g. /pages/viewpagesrc.action?pageId=XXXX

…and so on. I think you get the picture.

For any page where there is a real interaction with the wiki — such as page creation or page edits, attachment viewing or uploading — it is very difficult associate that interaction to the space where the interaction took place. Damn. That’s the main point really. Wikis are for collaboration — editing and creating content — not just passively reading.

It really bugs me that the URIs in Confluence aren’t built up so that they always provide a context of where you are. But what can we do?

This post suggests 2 possible solutions to this problem:

1. A Javascript only method
2. A Javascript and velocity templating method

Both have their drawbacks, but they do let you get a little closer to understanding what your users are doing within your Confluence spaces. Try them out and please report back on your preference or your own alternative solution.

The Javascript only method

In this method, we track a custom variable in GA where possible, so that we can attach a page view to the corresponding Confluence space.

Atlassian handily provide the following (example) meta tag on every page that has an associated space:

<meta id="confluence-space-key" name="confluence-space-key" content="~cczdas">

We can check for that meta tag and pass it into a custom variable in Google Analytics.

In Confluence, go to Dashboard | Administration | Look and Feel | Custom HTML

Click on the “Edit” button and add this javascript snippet (with your tracker code) to the “At end of the BODY” section:

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">

	window.onload = function(){
		try
		{
			var pageTracker = _gat._getTracker("UA-XXXXX-XX");

			// Add a page-level custom variable to record the space-key
			if (typeof jQuery('meta[name=confluence-space-key]').attr("content") == 'string')
			{
				pageTracker._setCustomVar(
				     1,                         // This custom var is set to slot #1 of 5
				     'confluence-space-key',    // The name acts as a kind of category for the user activity
				     jQuery('meta[name=confluence-space-key]').attr("content"), // This value of the custom variable
				     3                          // Sets the scope to page-level
				);
			}
		}
		catch (err) {}
	}

</script>

This means for each page, we’ve added a custom variable which can later be check against. We can now therefore easily check which page belongs to which space.

In Google Analytics, the custom variables report looks like this:

This doesn’t really tell us much, other than the number of page views for a space and a little more. To get at the real power of custom variables, we need to create a custom segment for each space. This will allow us to see all the interactions for the space.

Here’s a short video guide to creating custom segments for Confluence spaces:

Pros

• It’s really simple. Anyone with Confluence administration rights can cut and paste this code.
• It’s pure. This should not be affected by upgrades to the platform.
• It’s easily to support. Lots of people know Javascript.

Cons

• You’re moving into slightly advanced Google Analytics territory here.
• You’ll need to set up a separate custom advanced segment for each space. This may be somewhat dull.

I really like this approach, but haven’t managed to successfully add it into CGAP yet whilst maintaining access to historical data.

Javascript and velocity templating method

In this method, we trick Google Analytics into reporting the URL in a the format that works with content drill-down e.g.

• /pages/viewpage.action?pageId=XXXX becomes /display/spaceKey/Page+Title
• /x/2Bq9Ag (short URL) becomes /display/spaceKey/Page+Title
• /pages/editpage.action?pageId=XXX becomes /display/spaceKey/Page+Title/edit
• /pages/viewpageattachments.action?pageId=XXX becomes /display/spaceKey/Page+Title/view-attachments

We do this by adding a custom meta tag named “analytics.url.fix” from which we read the “fixed” URL using a little Javascript.

Edits

page.vmd in your theme:

## Add Google Analytics support for page edits, attachment views etc.
## Called by $!sitemeshPage.getProperty("page.googleAnalyticsUrlFix") in main.vmd
<content tag="googleAnalyticsUrlFix">
	#if ($mode == "view")
		<meta name="analytics.url.fix" desc="$req.contextPath/display/$page.spaceKey/$page.title" />
	#else
		<meta name="analytics.url.fix" desc="$req.contextPath/display/$page.spaceKey/$page.title/$mode" />
	#end
</content>

main.vmd in your theme:
Add after the title node in /html/head/title

## Call the googleAnalyticsUrlFix content tag in page.vmd, fail silently:
$!sitemeshPage.getProperty("page.googleAnalyticsUrlFix")

In Confluence, go to Dashboard | Administration | Look and Feel | Custom HTML

Click on the “Edit” button and add this javascript snippet (with your tracker code) to the “At end of the BODY” section:

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
	window.onload = function(){
		try
		{
			var pageTracker = _gat._getTracker("UA-XXXXXX-X"); 

			// Test for the meta[name=analytics.url.fix] tag & fix the url
			if (typeof jQuery('meta[name=analytics.url.fix]').attr("content") == 'string')
			{
	 			// console.debug('corrected pageview');
	   			var pageUri = jQuery('meta[name=analytics.url.fix]').attr("content").replace(/s+/gi, '+');
				pageTracker._trackPageview(pageUri);
			}
			else
			{
				// console.debug('default pageview');
				pageTracker._trackPageview();
			}
		}
		catch (err) {}
	}
</script>

Pros

• You don’t have to do anything on the Google Analytics side at all
• This is just great for the content drilldown screen in Google Analytics.
  • It means that pages with punctuation in the title can now be seen within their correct space.
  • The space owners can now be sure of the stats for viewing and editing pages within their space.
• This is great for the Google Analytics plugin for Confluence (CGAP)
  • All the page edits should be shown in the analytics report
  • It’s easily supportable. Lots of people know Javascript

Cons

• It’s a bit messy.
• You’ll have to apply this to every theme you support.
• Editing velocity templates isn’t everyone’s cup of tea.
• I’ve no idea what will happen when you upgrade Confluence.
• It niggles me that we’re sending incorrect (though easily readable) pageview data to Google Analytics.
• It still doesn’t tie everything to the space, just the page interactions

To my mind, this is less elegant, but provides pretty much instant results.

Which one to choose?

I really like the simplicity of the first solution. Just a little bit of Javascript to read a meta tag that’s already there. It’s likely to easily survive an upgrade. But I’m disappointed that as yet, I can’t get it to work nicely with CGAP.

For ongoing support reasons, I’d always say don’t mess with the platform. Don’t do anything which makes it more difficult to upgrade to the latest and greatest version. If you agree, then steer well clear of the latter option. If however, you absolutely have to start complete space specific tracking right now, no matter what, then the latter is then choice for you.