Access Keys:
Skip to content (Access Key - 0)

Community Bubbles

Adaptavist Documentation Move

This documentation is deprecated. Adaptavist's documentation has moved to a new location where it is maintained and updated. Please visit Adaptavist's new Documentation area.

forum macro

Overview

The forum macro provides a very simple way to add any number of forums to a wiki space. Simply place it on a page and all child pages will be treated as topics in the forum.

The order of items shown is based on the most recent activity in the child pages - new pages and pages with new comments appear at the top of the list.

Because topics in the forum are normal wiki pages with their normal comments, all the usual Confluence features still apply:

  • If you're watching pages or the space, you'll get email notifications when changes are made
  • You can add pages to your favourites to quickly "bookmark" interesting forum topics
  • Page level permissions can be set and all the usual Space Permissions apply
  • You can turn any existing collections of pages in to forums simply by adding the forum macro to the parent page
Confluence Index Used
From the Bubbles 1.2 release the forum macro makes extensive use of the Confluence search index to get the data to display. This makes it more efficient when dealing with a large number of topics then earlier versions. However any updates will be slightly delayed from appearing in the forum results until the changes from the update have been applied to the Confluence index (normally 1-2 mins on most servers).

Usage

{forum}

When you first put a forum macro on a page you will be prompted to designate the page the forum macro is pointing to as a root forum page. Doing this allows functionality that relies on knowing where forums are in the wiki (such as Sticky Topics, Topic Activity Score, Page Comment Locking or the Forum Summary Macro) to work.

Refer to Forum Permission Management for more information on controlling who has access to this functionality.

If you only want to use the forum macro as a recent update list and don't care about the other functionality, thats ok, you can hide the button using the showForumAdmin=false param. In this mode the forum macro will act like a different version of the recently updated macro, showing updates from child pages.

If you have previously set a page as the root of a forum and want to remove this property, you can use the "Disable Forum Features" option from the tools menu (which will only be visible on forum root pages.)

Macro Parameters

Content Parameters
Display Parameters
Username Meta Parameters

Content Parameters

Parameter Required Default Notes Bubbles Version
default @self The page that is the root of the forum:
  • title - the title of a page that exists within the space
  • @self - the current page (default)
 1.0
page @self An alternate way of specifying the page name 1.0
space current space If you want to display forum topics from a different space, specify the space key with this parameter. 1.0
recurse false Show all descendant pages as topics 1.0
sort date The sorting to use for the forum topics.
  • date - sort by last update date
  • activity - sort by the activity score for each topic. Only valid when activity score calculations are turned on.
 1.3
reverse false Change the display order to show the oldest posts first. 1.0
excludeSubForums true Exclude any descendent pages from being displayed that are also marked as being forum root pages. 1.2
include   Forum topics with matching properties will be included
  • locked - locked topics
  • sticky - sticky topics
    Multiple includes can be specified as a comma separated list, topics must match all the include properties to be displayed.
1.4
exclude   Forum topics with matching properties will be excluded
  • locked - locked topics
  • sticky - sticky topics
    Multiple excludes can be specified as a comma separated list.
 1.4
count show all topics The maximum number of recent posts that should be shown, eg. 10 1.0
paginate true If there are more topics then what can be displayed with the count parameter additional forum page links will be displayed. 1.2
start 0 The start index of the first topic to be displayed. (If the start index is specified in the http parameters when using pagination that value will override this param.) 1.4
author   If specified the topics displayed will be restricted to those authored by the given user. See Also Username Meta Params 1.6
participant   If specified the topics displayed will be restricted to those that the given user has participated in. See Also Username Meta Params 1.6

Display Parameters

Parameter Required Default Notes Bubbles Version
display table (1.2) The layout to use for the forum (examples):
  • simple - A clean-looking simple layout (1.0)
  • clean - A simple-looking clean layout (1.0)
  • table - A more conventional table layout (1.0)
  • list - Simple list of page titles (1.4)
 Varies
none "There are no topics in this forum" The text to display if there are no topics in the forum. From the 1.6 release you can also use the @hide option to completely hide any form macro output if there is no topics. 1.0
fullComment false Show an excerpt from the latest comment or the full comment. 1.0
excerpt comment Controls if the excerpt from the latest comment or the original topic page is displayed.
  • comment - Show the excerpt from the latest comment
  • topic - Show the excerpt from the original topic page always (For the clean and simple display types the original user and date the post was created will be shown if this option is selected. Posts will still be ordered by the date of the last update however)
  • none - don't show the excerpt at all. (This option doesn't make sense with the clean display type since it doesn't display the title of the page at all.)
 1.0
showPics true Whether to show the user's profile pictures or not:
  • true - Show profile pictures
  • false - Don't show pictures
 1.0
showIcons depends on display mode Controls the display of the topic icons such as sticky pages, and locked comments etc. Defaults to false for list display mode, true for other display modes. 1.4
showForumAdmin true Show the links to set a page as a forum page when the macro is first included on a page. If you are using the forum macro to show recent updates from a page hierarchy and don't want to be prompted to enable the forum features all the time, set this to false. (The forum admin settings are not shown in list display mode) 1.2
autoForumProperty false Automatically add the forum property to the root page when the macro is viewed. This can be useful if you are including the forum macro in a template or other automatically generated pages where you don't want the user to have to click the enable forum properties button. (The Forum property will only be set when the page is viewed by a user who has the add/remove forum page permission.) 1.6
showForumStats depends on display mode This parameter controls the display of the forum statistics above the forum. By default they will be shown if the table display mode is selected, but won't be shown for other display modes. 1.2
storeLastViewDate depends on display mode Each time a user visits the forum page the current time is stored against their profile. This allows the forum macro to know what topics are new for each user when they visit the forum page. By setting this parameter to false the date will not be stored which means this functionality won't work, however this will improve performance slightly. By default this parameter is set to true for all display modes other then list 1.2
activityIndicatorThreshold 50 The activity score required before adding the 'hot' indicator () to a topic. (This will only work when activity score calculations are enabled.) 1.3
class   The css class to apply to the top level element in the display to help with creating custom themes. For the list mode this will be appended to the <ul> element, for other display types it will be appended to the <table> element. 1.4

Username Meta Parameters

For macro parameters that take a username the following meta params can be used instead of specifying a username:

@self Refers to the currently logged in user viewing the macro
@creator Refers to the user that created the page that the macro is being rendered on
@owner Refers to the user that created the space that the macro is being rendered in

Hints and Tips

Integrate with other Confluence functionality.

One of the benefits of adding forums to Confluence is the wealth of functionality that already exists. Check out Forum Macro Integration with other Confluence Functionality for ideas about what can be used with your forum macro.

Selective Recent Updates Lists

You can use the forum macro to display recently updated content for a specific section of a space - for example, if you have a page called "Meetings" which has numerous child pages (eg. a page for each individual meeting) you could do something like this:

h3. Recent Meetings

{forum:page=Meetings|recurse=true}
{add-topic:page=Meetings|restrict=false}Add new meeting...{add-topic}

The forum macro will then list all the recent changes to the page hierarchy attached to the "Meetings" page. For this usage you'd probably not want to enable the forum features, so set the showForumAdmin param to false so it doesn't keep asking you to click the button to enable them.

Forum Widget

Use the forum macro inside a widget to display a small number of the most recent posts on another page. See Forum Widget Example

Topic Edit Restrictions

You can automatically restrict editing of new topics to the person who creates the topic (other users can still comment on the topic) by using the add-topic macro.

FAQs

How do I delete restricted topics?

If a topic has page-level edit restrictions set on it (often set when using the add-topic macro), delete links will often not appear when viewing the page. In such cases you must first remove the restriction either by editing the page (if you have sufficient administrative privileges) or by removing restrictions using the "Restricted Pages" link in Space Administration.

Why is my wiki markup getting mangled?

If the fullComment param is set to false and you haven't used the {excerpt} macro within the topic page, the forum macro will create an automatic excerpt from the topic page. This uses an in built feature of Confluence that will strip off any wiki markup which could cause the text that appears in the forum macro to be not quite the same as what it is on the actual topic page. If you notice this problem, the best thing to do would be to include an {excerpt} macro in your topic page, so you can have direct control over what will be displayed in the forum macro.

I'm clicking on disable forum features but nothing is happening?

Check the markup for the forum macro, if the autoForumProperty is set to true, the forum property will be automatically renabled on the page whenever it is viewed. You will need to edit the page to remove this parameter from the macro before clicking the disable forum features menu item.


View old comments
Adaptavist Theme Builder Powered by Atlassian Confluence