Discussions Macro

Last modified by Thomas Mortagne on 2024/02/12 00:00

cogUser Interface macros for the discussions.
Developed by

Simon Urli, Manuel Leduc

Active Installs3
0 Votes
LicenseGNU Lesser General Public License 2.1


Installable with the Extension Manager


The discussions application allows to integrate discussions into various parts of a wiki. 

It provides APIs and reusable user interface elements and is dedicated to developers.

This extension is under heavy development and can be highly unstable. Please use it only to perform tests on a dedicated XWiki instance.

This application is not dedicated to end users. 

Applications of the discussions application dedicated to end users can be found in:

Discussions Macro is built on top of several modules that can be useful when integrating the discussions in a new context:


Discussion Context

A discussion context represents a context that can be linked to a discussion.
A discussion can have several discussion contexts and a discussion context can be linked to several discussions.

A discussion context is defined by its name, description, and entity reference.
The name and description are here to describe the discussion context in natural language.
The entity reference represents the kind of entity referenced by the discussion context and is composed of an entity type and an entity reference.
entity The type represents the type of the referenced entity, and the entity reference stores a string that identified uniquely the referenced entity.

Each application that uses the Discussions application to integrates discussions in its context can use its own type of entities.
For instance, in the context of the integration of the discussions in the ActivityPub Application, the discussion contexts are of type activitypub-activity and their values are the URIs of the references ActivityPub activities.


A discussion contains a collection of messages and can be linked to several discussion contexts.
Discussions are then queried by looking at the discussion context to which they are linked.
For instance, in the context of the integration of the discussions in the ActivityPub Application, the list of the discussions related to a given activity is found by querying the discussions that are linked to a discussion context with an entity reference type equals to  activitypub-activity and an entity reference equals to the URI of the activity.

A discussion also contains a title and a description.


A message is contained in a discussion and has the following attributes:

  • an actor, qualified by its type and reference
  • a creation date
  • an update date
  • the content of the message, qualified by its syntax and content

Storage of discussions

By default all discussions, discussions contexts and messages are stored in the same space named Discussions.
However, since Discussions 2.0 it's possible for the applications which relies on Discussions to configure where to store the different elements, and to dynamically chose the storage location.
To do so, two concepts have been put in place: an #applicationHint# must be used in the various API which defines the #DiscussionStoreConfiguration# component that should be used. Then, this component uses in its API a #DiscussionStoreConfigurationParameters# which is basically a map of parameters: those parameters needs to be given when using the different APIs for creating or retrieving the different objects, but they can be completely custom depending on the implementation of the #DiscussionStoreConfiguration#.


Discussion Macro

The discussion macro displays a discussion and a form to add new messages to the discussion.


NameDescriptionDefault ValueSince
referenceThe reference of the discussion to display 1.0
namespaceThe namespace. An arbitrary value used to distinguish between two discussion macros in the same page 1.0
pageSizeThe number of message to display on a single page101.0


{{discussion reference="DISCUSSION_REFERENCE" namespace="DISCUSSION_NAMESPACE"/}}

List Discussions Macro

The list discussions macro lists all the discussions linked to a given discussion context.
The discussions link to the requested discussion context type and the joker value  (*) are also included by default.


NameDescriptionDefault ValueSince
listIdA unique id of the list. 1.0
typeThe type of the discussion context linked to the discussions. 1.0
referenceThe value of the reference of the discussion context linked to the discussions. 1.0
linkTemplateA template to generate the links to the discussions. __REFERENCE__ is replaced by the reference of the discussions when generating the links. 1.0
jokerAllowedIf true, the discussion context with a reference equals to * will also be included in the results.true1.0


{{listDiscussions listId="list_id" type="discussion-context-type" reference="discussion-context-reference" linkTemplate="http://server/reference=__REFERENCE__"/}}


Three kind of events are sent by the application:

  • org.xwiki.contrib.discussions.events.DiscussionEvent
  • org.xwiki.contrib.discussions.events.DiscussionEvent
  • org.xwiki.contrib.discussions.events.MessageEvent

The are sent whenever the respective entity state is changed and contains the type of change:



An index page provides two tables:

  • the list of all the discussions
  • the list of all the discussion contexts

This pages is accessible from the right drawer.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes


The following translations have been updated with this release:







The following translations have been updated with this release:


The following translations have been updated with this release:


Discussion now requires XWiki 14.10 as minimum version.



Translations update.




Dependencies for this extension (org.xwiki.contrib:discussions-macro 2.5.1):

  • org.xwiki.contrib:discussions-api 2.5.1
  • org.xwiki.contrib:discussions-server 2.5.1
  • org.xwiki.contrib:discussions-rest-default 2.5.1

Get Connected