cogAPI to support the mention of users
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager


The User Mentions API allows to configure how the mentions are sent, and to registers new kinds of mentionable actors.


The MentionsConfiguration provides the shared constants and configurable values used for the mentions:

  • USER_MENTION_TYPE: the default type of mentions
  • getMentionsColor(): the default background color of the mentions
  • getSelfMentionsColor() the default background color of the mentions to the current user 
  • isQuoteActivated() returns true of a quote of the text surrounding a mentions must be generated when sending a notification

Integrating a new mention type

Declaring a new mention type is made in three steps

Declaring a formatter

This step is optional. When no formatter is provided for a given type, the default formatter is used. In this case the identifier of the mentioned actors is displayed without further formatting.

The formatter is used to display the mentioned actor in a textual form according to its type.

Three display styles can be asked for:

  • full name (first and last names)
  • first name only
  • login

Declaring a provider is done by declaring a component with the role org.xwiki.mentions.MentionsFormatter.
For instance:

import javax.inject.Named;
import javax.inject.Singleton;

import org.xwiki.component.annotation.Component;
import org.xwiki.mentions.DisplayStyle;
import org.xwiki.mentions.MentionsFormatter;

@Named("example") // the hint must match the type of actor
public class ExampleMentionsFormatter implements MentionsFormatter
   public String formatMention(String actorReference, DisplayStyle style)
       switch (style) {
           case FULL_NAME:
               return "...full name...";
           case FIRST_NAME:
               return "...first name...";
           case LOGIN:
               return "...login...";
               return null;

Declaring a listener


Declaring an actor provider

This features is not yet available as of XWiki 12.10.

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

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.platform:xwiki-platform-mentions-api 12.9):


Get Connected