Community Bubbles Plugin

All Adaptavist Apps

Page tree
Skip to end of metadata
Go to start of metadata

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

(error)

@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

(error)

@self

An alternate way of specifying the page name

1.0

space

(error)

current space

If you want to display forum topics from a different space, specify the space key with this parameter.

1.0

recurse

(error)

false

Show all descendant pages as topics

1.0

sort

(error)

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

(error)

false

Change the display order to show the oldest posts first.

1.0

excludeSubForums

(error)

true

Exclude any descendent pages from being displayed that are also marked as being forum root pages.

1.2

include

(error)

 

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

(error)

 

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

(error)

show all topics

The maximum number of recent posts that should be shown, eg. 10

1.0

paginate

(error)

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

(error)

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

(error)

 

If specified the topics displayed will be restricted to those authored by the given user. See Also Username Meta Params

1.6

participant

(error)

 

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

(error)

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

(error)

"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

(error)

false

Show an excerpt from the latest comment or the full comment.

1.0

excerpt

(error)

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

(error)

true

Whether to show the user's profile pictures or not:

  • true - Show profile pictures
  • false - Don't show pictures

1.0

showIcons

(error)

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

(error)

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

(error)

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

(error)

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

(error)

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

(error)

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

(error)

 

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.

13 Comments

  1. 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!

    1. Unknown User (skrebs)

      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?

      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

      1. Unknown User (rupert.shanks@ne.nykline.com)

        Thanks for the support Shannon

  2. Unknown User (skrebs)

    2. Can the bahaviour of the forum be adpated, so that later changes on forum topics are not reflected in the forum overview? It seems the macro looks at the last editor and not on the original creator of the page.

    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.)

    1. Unknown User (hajoworldwide)

      OK, cool (thumbs up). Looking forward to the new release!!

  3. 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?

    1. Unknown User (skrebs)

      The 1.6 release fixes this bug.

  4. 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.

    1. 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.

      1. Unknown User (lumina)

        Thanks, it works! And in future we will post these questions to Forums!

  5. 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).

    1. 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 (smile)

  6. Unknown User (heatherfara)

    You can use the macro recently-updated macro for a feed of the entire site (across spaces)