User Mentions Application
 | Mention users in wiki content. |
| Type | XAR |
| Category | Application |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | XWiki Standard 12.6+ |
Table of contents
Description
This Mentions application allows for the integration of user mentions on XWiki.
This application integrates the user mentions feature in XWiki. Users can mention other users using a dedicated macro. Users are then notified of the pages in which they are mentioned through XWiki activity stream.
This applications is based on the XWiki Platform - Mentions - API. The API documentation provides more details on how to customize or create your own mentions actors and listeners.
Mentions Auto-Completion
To assist quickly mentioning users, an auto-completion is displayed when '@' is typed in the WYSIWYG editor.
The list of 6 users matching the characters typed after the '@' is presented as you type, sorted alphabetically by first name and then by last name, independently of the case. The matching users are users accessible to the current user.
Mention Macro
The mention macro allows for the insertion of the mention to a user in a body of text.
It has four parameters:
- The reference of the mentioned actor
- The style of display of the mentioned actor:
- First and last name
- First name only
- User login
- The anchor, a unique identifier of a mention in a document.
- XWiki 12.10+ The type of the mentioned actor (a local user of the wiki by default)
The mention macro can be user in all long text fields of the Wiki, for instance:
- The body of the documents
- Long text fields of the applications
- Comments
- Annotations
A notification will be sent to the mentioned user, who will eventually receive it according to its notifications settings.
Using the WYSIWYG Editor
To insert a mention:
- In the WYSIWYG editor menu click on add a mention and select other macros
- Search for the User Mention entry and click on select
- Look for a user name in the first field
- Select a display method for the mention:
- First and last name of the user (e.g., John Doe)
- First name only (e.g., John)
- User login (e.g., JDoe)
- Type a unique anchor, make sure to make it unique across the document, for instance using random.org.
These steps are detailed in the gallery below.
Using the Source Editor
When inserting a mention manually, be careful to make the mention anchor unique across the document, for instance using random.org.
{{mention identifier="XWiki.Admin" displayChoice="FIRST_NAME" anchor="xwiki-XWiki.Admin-123456"/}}
{{mention identifier="XWiki.Admin" displayChoice="LOGIN" anchor="xwiki-XWiki.Admin-123456"/}}
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| reference | no | An actor identifier (for instance xwiki:XWiki.User) | - | The user identifier of the mentioned actor. It will be read according to the type of the mention. By default a wiki user identifier. |
| style | no | A value of the DisplayChoice enumeration (i.e., FULL_NAME, FIRST_NAME, or LOGIN). | - | Defines of the mentioned user is presented in the macro.
|
| anchor | no | Any string | The empty string | A random string, usually prefixed by the mentioned user identifier (e.g., xwiki-XWiki-User). |
| type | yes (default: 'user') | Any string | The empty string | XWiki 12.10+ The type of the mentioned actor |
Notifications
The mentions rely on the standard notification mechanism of XWiki, based on XWiki Activity Stream.
XWiki 16.8.0+ If the mention is sent from a different subwiki than the one the user is currently in, the subwiki name is shown.
User Mentions Activation
A user can choose if and how they want to receive their mentions through the notifications, using the notifications settings.
To do so, choose the notification entry in the user's profile and turn the toggle buttons on in the Notification menu or Email columns of the Mentions row.
Settings
Pool Size
The number of threads dedicated to the analysis of new mentions in created or updated document is available in xwiki.properties.
#-# The detection and notification for the user mentions in created or edited content is done asynchronously
#-# by a pool of consumers.
#-# This properties controls the size of this pool.
#-#
#-# The default is :
# mentions.poolSize = 1
Administration
Global Mentions Activation
Notifications can be globally configured on the wiki administration, in the Notifications entry (under the Social category).
To do so, turn the toggle buttons on in the Notification menu or Email columns of the Mentions row.
The users of the wiki still have the possibility to change these settings individually (see the User Mentions Activation section).
Mentions Colors Administration
Mentions colors can be configured in the wiki administration, in the sub-section Mentions of the Social section.
Two colors can be configured, the default color of the mentions, and the colors of the mentions to the current users.
Mentions Summary
A summary of the text surrounding a mentions can now be integrated in a mention notification.
The generation and display of the mention summary can be deactivated in the mentions section of the administration.
Monitoring
JMX
An object named org.xwiki:name=mentions is provided and provides two attributes and one operations:
- QueueSize: Displays the numbers of elements (created or updated pages) to be analysed.
- ThreadNumber: The number the threads in the thread pool.
- clearQueue(): Removes all the elements in the queue. Warning: By doing so some pages will not be analysed and some mentions will be missed. To be used carefully.
Known related issues
Upgrading
A local database is stored in the permanent directories and stores the updated document that needs to be analyzed for new mentions. This database is based on H2 MVStore. On major version upgrades, the file format of H2 MVStore can change and the old one becomes unsupported. In this case, the old database file is moved to a backup file, and a new one is created.
Warning: In this case, any updated document queued for upgrade when the server is stopped will be discarded, and some users will not be notified of their mentions.
Please make sure that the queue size is at zero before upgrading (see JMX).
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:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
v12.5-rc-1
Starting with XWiki 12.5RC1 the Mentions Application has been moved to XWiki Platform and the release notes are now part of the XWiki Release Notes.
v1.0
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-mentions-ui 16.10.1):
- org.xwiki.platform:xwiki-platform-notifications-ui 16.10.1
- org.xwiki.platform:xwiki-platform-mentions-default 16.10.1
- org.xwiki.platform:xwiki-platform-mentions-notifications 16.10.1
