Skip to end of metadata
Go to start of metadata

Overview

The {forum-summary} macro can be used to show a list of forums from a space, or that are child pages of a given page. This macro will only show forums that have their root pages designated as a forum using the forum macro.

Usage

{forum-summary}

There are two usage options with this macro, space and page. In space mode the macro will show all forums from the specified space, in page mode the macro will show all forums that are child pages of the given page.

The forums can be displayed in either a table showing the number of topics/replies as well as the last person to make an update in the forum. Or as a simple list showing the title and the excerpt from the forum root page.

Performance Issues for table display

Because the table display needs to search the confluence index to get the stats for each forum it displays the performance of the macro will be directly proportional to the number of forums displayed. Because the list mode doesn't display this data it will be quicker when displaying a large list of forums.

Parameters

Parameter

Required

Default

Notes

Bubbles Version

default

(error)

Current page or space

Specify the page or space that will be used for the search for forum pages.

1.2

page

(error)

Current page

Alternative to default param, to specify page title to search for children forum pages.

1.2

space

(error)

Current space

Alternative to default param, specify the space.

1.2

mode

(error)

page

Either page or space. Page mode shows the forum pages that are children of the specified page, while space mode will show all forums from a space.

1.2

display

(error)

table

Either table or list

1.2

none

(error)

"There are no forums to display"

The text to display when there are no forum macros found for the given parameters.

1.2

showExcerpt

(error)

true

Whether to show the forum page's excerpt.

1.2

showPics

(error)

true

Whether to show the last update user's pic, only applies to table display.

1.2

tableHeading

(error)

"Forums"

The heading to use for the first column of the table display.

1.2

recurse

(error)

false

Controls how the topic and replies data in the table display is calculated. Recursive searching will include all topics that are descendents of a forum page, while false will only display data about the children of the forum page. (Note: it is possible for the displayed forums to have different recursive parameters on the forum macro used on their own page, however this recursive setting applies to all forum pages displayed, regardless of the setting of the forum macro.)

1.2

Hints and Tips

Nesting {forum-summary} macros

The forum summary macro can be used to create a nested list of forum categories with statistics. Since the forum-summary macro only displays child pages that are classified as forums, you will first need to add a forum macro to a sub category to set the forum flag. You can then remove the forum macro and replace with a forum-summary, then add child forums. If you have set the recursive flag on the top level forum summary macro, the correct topic and reply counts should be shown in the table.

3 Comments

  1. Unknown User (hajoworldwide)

    At last! (thumbs up) Gonna play with it in our test wiki.

    Some questions already;

    • Screenshots please.
    • Does it really state performance issues? ((sad)) If one thing bothers our users, it is performance, regardless of how sleek-nice-and-steamy-hot the functionality is.
    • (re)naming of the categories possible?
    • Possibility to add category logos?
  2. Unknown User (juhalindfors)

    Would wrapping it to {cache:5m} help with the performance? Not an issue for me but just a thought..

    1. Unknown User (gfraser)

      Yes, wrapping it in the cache macro would reduce load on the server (but increase RAM consumption).

      The search index is very fast, so it's unlikely that you'll encounter performance issues from using the macro in the average space. However, if you start adding hundreds of forums, it's obviously going to impact performance.