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:
| 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.
| 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
| 1.4 |
exclude |
|
| Forum topics with matching properties will be excluded
| 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):
| 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.
| 1.0 |
showPics |
| true | Whether to show the user's profile pictures or not:
| 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 ( | 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.
Overview
Community Forums
Content Tools
13 Comments
Unknown User (rupert.shanks@ne.nykline.com)
When I use the parameter excerpt=topic, the Last Post column in my forum display table just shows the 1st post details.
When I use the parameter excerpt=comment, the Last Post column does show the Last Post details.
Is there a way to show the 1st comment details in the Topic column in my display table AND the Last post details in the "Last Post" column?
Thanks!
Unknown User (skrebs)
not currently, but I think this is how it should work by default. I have created an issue for this here: http://jira.adaptavist.com/browse/BUBBLES-285
Unknown User (rupert.shanks@ne.nykline.com)
Thanks for the support Shannon
Unknown User (skrebs)
Yes this is the way it works currently. We recognise this isn't how most users would expect it to work, and have actually changed it so the pages original author will be displayed not the latest editor, this will be available in the 1.2.1 release. (Hopefully late this week, depending on how long some other bugs take to get fixed.)
Unknown User (hajoworldwide)
OK, cool
. Looking forward to the new release!!
Unknown User (mplant)
The CSS for the Forum includes a style for the body which overides Theme Builder custom CSS (line 315).
The comment for the body style says to remove the style as it is just there to make the testbed look nicer.
/* remove the body style - it's just here to make the testbed look nicer */ body { font-family: Arial, Helvetica, sans-serif; font-size: 12px; }I now have to go through change requests to ask the network administrators to remove the body style.
Why can you not just remove this style from the plugin CSS?
Unknown User (skrebs)
The 1.6 release fixes this bug.
Unknown User (lumina)
Hello,
We are using the forum macro with the showpic parameter = True. However in the tabular display, under the Author and Last Posts columns the images are not shown. However if you go to the details of a topic the images are displayed in the child page. Would this be because we have disabled the people directory entirely for all users. We had to do this as the people directory was showing up for users that had restricted access to certain spaces only.
Unknown User (skrebs): Edited to remove images that were making the page width too wide.
Unknown User (skrebs)
The first thing I would check is the base url settings of your confluence install. Compare the url being output for the user images in the forum macro with the url being used in the comments.
In the latest releases of the plugin if a user doesn't have permission to see the profile pics that should get the default image, not an empty box.
Unknown User (lumina)
Thanks, it works! And in future we will post these questions to Forums!
Unknown User (hooligan495)
I am trying to use the forum.
I have a simple page in a space that has:
add-topic
forum
I can add topics but the forum table isn't updating (it keeps saying that there are no topics in this forum). How can I figure out what's going on? I have other forums in other spaces that have worked in the past and they don't show new topics (but they still show the old ones).
Unknown User (scayla)
Either force indexation in the admin console or wait for the created pages to be indexed and they will show up in the forum
Unknown User (heatherfara)
You can use the macro recently-updated macro for a feed of the entire site (across spaces)