Popular Labels Macro

The Popular Labels macro displays the most popular labels used throughout your Confluence site or within a space. A popular label is a label that has been added to many pages. 

Using the Popular Labels Macro

To add the Popular Labels macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Autocomplete for links, files, macros and mentions.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Parameters

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter

Default

Description

Number of Labels to Display
(count

100

Specifies the total number of labels to display in the heatmap.

Restrict Labels to this Space Key
(spaceKey

none

Restricts the list of popular labels to the specified space.

Style of Labels
(style

list

  • list – displays the popular labels as a bulleted list, ordered by popularity (highest first).
  • heatmap – displays the popular labels using different font sizes for each label depending on the label's popularity, ordered by label names.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: popular-labels

Macro body: None.

Storage format example

Wikimarkup example

Was this helpful?

Thanks for your feedback!

36 Archived comments

  1. User avatar

    jamiep77

    This macro is working fine and displaying popular labels for the space I'm working with, but when you click one of the labels, the results show matches from all spaces the user can access -- how can I get the results to show only matches for the label within the current space?

    29 Jan 2009
    1. User avatar

      Giles Gaskell

      Hello jamiep77,

      Unfortunately, it's currently not possible to restrict the results of this macro to those restricted by its spaceKey parameter.

      However, this issue has already been raised in CONF-9149 and you can vote on it to increase its chances of being fixed in a future version.

      Best regards,

      Giles Gaskell
      Technical Writer
      ggaskell@atlassian.com
      ATLASSIAN - http://www.atlassian.com

      03 Feb 2009
      1. User avatar

        jamiep77

        Thank you so much for the info -- I've voted on CONF-9149.

        03 Feb 2009
  2. User avatar

    Arne Schirmacher

    I have modified the Popular Labels macro a bit since the standard version didn't fit my needs. The patched version supports customizing using CSS and sorting by label name and rank. You can download it here: Popular Labels Macro Tutorial.

    28 Feb 2009
    1. User avatar

      Brett Ryan

      Nice one Arne, I'm looking for a way to change the background colour to transparent or white, your version looks like it might fit the bill nicely (smile)

      I was trying to simply use the style against the site, however all the styling on the heatmap is at the element level which can't be overridden.

      14 Dec 2010
  3. User avatar

    Craig Pendleton

    In Confluence 2.10.2, this macro does not seem to order by name, even if I use "style=heatmap" as indicated above.  It orders by popularity instead.  How can I order by name?

    11 Mar 2009
    1. User avatar

      Henry Tiong [Atlassian]

      Hi Craig,

      This is because of the existing bug, http://jira.atlassian.com/browse/CONF-13594, in which the ordering by name does not work without the spaceKey parameter. The "heatmap" style will order by popularity if spaceKey parameter is used.

      {popular-labels:style=heatmap|count=20|spaceKey=DOC} 
      

      In your scenario, are you trying to get the popular labels for the entire Confluence instance or just a space? If it is just a space, then putting the spaceKey parameter will solve it. Unfortunately, if it is a global popular labels you are aftering, we need to wait CONF-13594 to be resolved.

      sorry for any inconvenience caused,
      Henry CL Tiong

      13 Mar 2009
      1. User avatar

        Craig Pendleton

        Thank you Henry.  So, my next question is can a variable for spaceKey be used so the macro is still usable in a global template?  If not, is there another more usable heat map macro or plugin for labels?   Thanks in advance!

        Edit: I should clarify that I am looking for space-specific labels, but would like to use the macro in a global template.

        17 Mar 2009
        1. User avatar

          Azwandi Aris [Atlassian]

          Hi Craig,

          You might want to create a user macro that can supply the current space key to the {popular-labels} macro:

          1. Create a user macro
            • Macro name: popular-heatmap
            • Untick "Macro has a body"
            • Output: Macro generates wiki markup
            • Template:
          2. Create a global template that calls the {popular-heatmap} macro we have just created.

          Now, the macro displays space-specific labels. Hope that helps!

          Cheers,
          Azwandi

          30 Mar 2009
  4. User avatar

    Anonymous

    Is it possible to restrict the user to view only those labels in space that the user has access to?

    02 Jun 2009
    1. User avatar

      Zed Yap [Atlassian]

      Hi,

      As far as I know, I have tested it in Confluence 2.10.3 and Confluence 3.0. Unfortunately, the feature requested is not available yet. However, you might want to raise an improvement request in JIRA:

      Hope that helps,
      Zed

      10 Jun 2009
  5. User avatar

    Anonymous

    I'd like to list all spaces having with a specific team label. My goal is to display clusters of spaces grouped by team-lables. I've looked for space-specific macros but none provided me with a filter for team-lables. Any idea?

    Thx in adavance

    GuL

    16 Jul 2009
    1. User avatar

      Sashidaran Jayaraman [Atlassian]

      Hi GuL,

      I think this is achievable by using the reporting plugin. Here is a sample code that works for me:

      Hope this helps.

      Cheers
      JSashi

      21 Jul 2009
      1. User avatar

        Anonymous

        JSashi

        great! Exactly what I was looking for!

        GuL

        22 Jul 2009
        1. User avatar

          Sashidaran Jayaraman [Atlassian]

          Glad it worked for you, GuL!

          Cheers
          JSashi

          23 Jul 2009
  6. User avatar

    Anonymous

    Hi,

    We have lots of pages labelled rss_ that I dont want to appear in a cloud,  so is there a way to exclude certain labels in a space?

    18 Aug 2009
    1. User avatar

      Sashidaran Jayaraman [Atlassian]

      Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at http://jira.atlassian.com. and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page

      Cheers
      JSashi

      19 Aug 2009
  7. User avatar

    Anonymous

    Hi,

    do you guys know a way to display a tag cloud in confluence with a time restriction of the tags - let's say a tag cloud that displays the most popular labels of the last month? The most popular tags in our wiki don't change too often, so it's a bit boring to always display the same labels.

    Any help is greatly appreciated!

    06 Oct 2009
    1. User avatar

      Sashidaran Jayaraman [Atlassian]

      Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at http://jira.atlassian.com. and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page.

      You could also get more help in our Atlassian Answers.

      Cheers
      JSashi

      12 Oct 2009
  8. User avatar

    Anonymous

    Hi ,

    Can we make certain pages specific rather than complete space?

    Neha

    03 Nov 2009
  9. User avatar

    Anonymous

    Hi,

    I meant labels specific to certain pages rather than space.

    Neha

    03 Nov 2009
    1. User avatar

      Zed Yap [Atlassian]

      Hi

      I meant labels specific to certain pages rather than space.

      I have a mere suggestion, you might want to try the Page Family Tag Cloud. Hopefully this plugin will satisfy some of your requirement.

      Hope that helps.
      Best rgds,
      Zed

      04 Nov 2009
  10. User avatar

    Anonymous

    Is it possible to add a narrow heatmap in line with (ie as a section of) the left hand menu?

    I have tried a few options in the 'Navigation' page and failed (popular labels did appear as menu line items). In heat-map form, I only seem to get the panel spanning the full page.

    Thanks in advance for any advice

    Jeremy

    15 Feb 2010
  11. User avatar

    James Mullan

    Hi,

    Is it possible to exclude certain labels?

    For example I've created a blog using confluence but in order for the post to appear they all have to use a certain label. I'd like to exclude this lablel from the heatmap.

    Thanks

    James

    22 Mar 2010
    1. User avatar

      Husein Alatas

      Hi James,

      I am afraid currently it is not possible to exclude certain labels using popular labels macro. Feel free to raise an improvement request at http://studio.plugins.atlassian.com. And describe in detail how you require this improvement to work. Please add yourself as a watcher for this improvement and add your own comments to this improvement request.

      Meanwhile, you can do that by using Tag Cloud Macro plugin along with excludePrefix or excludePostfix paramater.
      For example, if you want to display the most popular labels (excluding "book" and "cat") using Tag Cloud Macro plugin, you can write a macro like this:

      Please take note that you may need to read its documentation here for further usage.

      Hope that helps (smile).
      Regards,
      Husein Alatas

      23 Mar 2010
      1. User avatar

        James Mullan

        Hussein,

        Is there a difference between the Tag Cloud Macro and the Page Family Tag Cloud? we have the latter installed and I'm wondering whether we could use this to exclude certain labels?

        Thanks

        James

        23 Mar 2010
        1. User avatar

          Husein Alatas

          Hi,

          Based on the documentation of Page Family Tag Cloud, it looks like it doesn't have such parameter to exclude certain labels. And also please take note that currently it's not supported in Confluence 3.1.x above.

          To know more on the differences, you can read the documentation of Page Family Tag Cloud and Tag Cloud Macro.

          Regards,
          Husein Alatas

          24 Mar 2010
  12. User avatar

    David McIntyre

    How can I use spaceKey=current in this macro? If I use this in a template or a sidebar I'd like it to populate with only data from the current space.

    14 Oct 2010
  13. User avatar

    Andrea Carta

    Hi,

    What determines the popularity of a label--the number of times it appears or the number of times users click on the label?

    Thanks!
    Andrea

    04 Apr 2011
  14. User avatar

    Qian Zhao

    I installed 4.0-rc7 and the popular labels macro showed all labels in a list fashion even though I choose the heatmap style. Those labels are still shown in different font sizes based on their popularities but being rendered in a list rather than a tag cloud wastes screen real estate. Can this be changed back to tag cloud display? Thanks.

    20 Sep 2011
    1. User avatar

      Bartek Zukowski

      It's the same in full retail 4.0 version (as you can see in one of the first comments on this page). Heat map style is not working properly yet (sad)

      04 Oct 2011
  15. User avatar

    Anonymous

    Hi, would also like to have the "heatmap" style working instead of a list. With the conversion to 4.0 all popular labels are listed.

    The heatmap was a nice visible tag on the main pages.

    07 Oct 2011
  16. User avatar

    christian edohor

    Hi,

    I just installed confluence on my PC and the fonts of the 'Popular Label' macro are not uniform (their sizes vary). Is there any configuration i can make so as to ensure all the text fonts of labels captured by the Popular 'Label macro' are uniform?

    Will highly appreciate a response to this.

     

    Thanks.

    14 Aug 2014
    1. User avatar

      Qian Zhao

      it's a way to show the different popularity of the labels and is meant to be this way.

      14 Aug 2014
      1. User avatar

        christian edohor

        Hi Qian,

        Thanks so much for your response. I really appreciate. It explains a whole lot.

        I actually have a new space now with all fonts in the Popular label macro being of the same size now. But they are quite big and desire reducing thier sizes so as to be quite small.

        Is it possible to reduce their sizes?

         

        15 Aug 2014
        1. User avatar

          Rachel Robins [Atlassian Tech Writer]

          Hi Christian, there's no way to change the appearance of this macro. It is designed to be like a tag cloud, with more popular labels larger than less popular ones. 

          One of other label macros (such as labels list, or related labels) might work better for you if you need a particular layout. 

          18 Aug 2014
Powered by Confluence and Scroll Viewport