Discussions Application
An application to integrate discussions into wikis. |
Type | XAR |
Category | Application |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Compatibility | 12.10+ |
Table of contents
Description
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.
Applications of the discussions application to end users can be found in:
- the discussions message stream application
- the ActivityPub Application
Concepts
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.
Discussion
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.
Message
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
Macros
Discussion Macro
The discussion macro displays a discussion and a form to add new messages to the discussion.
Parameters
Name | Description | Default Value | Since |
---|---|---|---|
reference | The reference of the discussion to display | 1.0 | |
namespace | The namespace. An arbitrary value used to distinguish between two discussion macros in the same page | 1.0 | |
pageSize | The number of message to display on a single page | 10 | 1.0 |
Example
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.
Parameters
Name | Description | Default Value | Since |
---|---|---|---|
listId | A unique id of the list. | 1.0 | |
type | The type of the discussion context linked to the discussions. | 1.0 | |
reference | The value of the reference of the discussion context linked to the discussions. | 1.0 | |
linkTemplate | A template to generate the links to the discussions. __REFERENCE__ is replaced by the reference of the discussions when generating the links. | 1.0 | |
jokerAllowed | If true, the discussion context with a reference equals to * will also be included in the results. | true | 1.0 |
Example
Events
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:
- CREATE
- UPDATE
- DELETE
Indexes
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.