User Mentions
Description
Introduction
Mentions are a structured way to reference users in text (e.g., comments, annotations, documents).
They are usually visually distinguishable by an @ prefix followed by the identifier of an user, often in hypertext form (e.g., @mleduc).
Mentions Integration
It should be possible to add mentions to users or groups wherever xwiki syntaxes are supported.
A non comprehensive list includes:
- documents body
- comments (integrate rich editor)
- annotations (integrate rich editor)
- textarea fields in AWM (the rich editor is a user choice in the AWM settings)
- WARNING: other places ?
In the rich editor it should be easy to include a mention using only the keyboard, and without having to use the macro section of the rich editor menu.
Mentions must be visually identifiable in the text, for instance the user name or group group could have a specific background color. Similarly, mentions to the current user and/or a group in which the current is must be highlighted in specific colors.
The default content of the display mention should be the first name + last name of the user. It should be possible to change it to it first name only, or to the login of the user. I don't know if it's a good idea to be able to allow to change the text of the mention for a free text (confusing, risk of link scamming...).
Mentions of removed users should still be display clearly, eventually identified visually that the user has been removed (which is not easy to identify in the context of AP for instance).
Notifications
Notifications rules
Mentioning a user of a group must trigger a even, eventually leading to the notification of the concerned users.
Nonetheless, user should not be notified several time for the same mention (e.g., when a document is edited and a mention was previously in the document).
Notifications content
The content of a notification must include as much content as possible regarding the context in which the mention occurred. This content must be as specific as possible according to the type of entity in which the mention occurred.
A non comprehensive list includes:
- the user that made the mention
- the type of entity in which the mention occurred
a direct link to the entity, e.g.,
- the body of a document, ideally an anchor to the § where the mention occurs.
- an anchor to a comment
- an anchor to an annotation
Notifications answer
The most basic scenario is to click on the link in the notification and to interact with the wiki as usual
More advanced scenarios includes:
- having a form to interact with the content directly in the content of the notification created by the mention (TODO: create task)
- being able to answer directly to mail eventually received as a notification of a mention (TODO: create trask)
Notifications settings
Notifications of mentions should be integrated in the notifications settings of the wiki, using the notifications framework provided by XWiki.
Notifications must be activated by default to help users discover the new feature by receiving mentions.
Extensibility
While the nominal scenario is the integration of mentions inside a xwiki instance (and its sub-wikis). The mentions features must be extensible to let extensions add new features on tops of the mentions.
The main use case of this is the integration of user mentions on ActivityPub (see https://design.xwiki.org/xwiki/bin/view/Proposal/ActivityPub).
The list of extension points should include:
- users suggestions in the rich editor
- an extension point on the notifications emission.
In addition, the core of the mentions must support unknown type of external users.
Discussions
Requesting view rights
If an user tries to access a document for which she does not have the read right (for instance, after being mentioned inside the given document), an action should allow to require an access to the page.
Messaging
The most basic solution is to simply send a message to the user that triggered the mentions, asking for access to the page.
Ad-hoc mechanism
A more advance solution could be to present a button that would send a query to whoever has the right to set the read right for this page.
Tasks
Rich editor integration
The rich editor must be integrated on every textarea supporting the xwiki syntax.
- Comments
- Annotations
WARNING: other places ?
Adding an autocompletion on the rich editor
Typing @ in the rich editor must present an autompletion of available users and groups and automatically insert the corresponding macro in the text.
Mention macro
The mention macro must allow to declare a mention. This macro has one field pointing to a single user or group.
The macro must be display in a distinctive and identifiable way.
Mentions to the current user and/or a group in which the current is must be highlighted in specific colors.
The text of the mention should be first name + last name, first name only or user login (the user defining the mention should be able to choose)
Mention macro settings
Variations points of the mention macro must be configurable in the skins administration
Mention in the syntax
Mentions could be integrated as first-class entities in some syntaxes supported in the wiki, if those syntaxes has a build-in support for it.
XWiki/2.2
In the specific context of xwiki/2.2, user mentions could be build around the notions of link to users, discussed in TODO, TODO and TODO.
Other syntaxes
TBD
Mentions history
An user must not be notified of a mention several time for the same entity (document, comment, annotation...).
A mapping between mentioned users (members of a group must be resolved to their individual users) and entities must be stored and used to identify the relevant notifications.
Similarly, only members present in a group prior to the group mentions should be notified.
A mapping between mentioned groups and entities must also be stored.
A notification is only send to individual users that have not already be notified, and to groups that have not already been notified. Only group members who have not already been notified are notified.
Notifications settings
integrate settings in the configuration to activate mentions at the level of the administration and at the level of individual users.
Existing discussions
This section collects existing discussions that are relates to concerns of interest in the context of user mentions.
Mentions in CKEditor https://forum.xwiki.org/t/user-mention-in-ck-editor/843
Links extensibility
Comparison matrix
| Product | Documentation | ActivityPub? | Details |
|---|---|---|---|
| Mastodon | yes | Webfinger ids or user login for the local instance, prefixed with @. | |
| no | User login prefixed with @ | ||
| Wordpress | https://wordpress.com/support/user-mentions/ | yes (by extension) | User login prefixed with @ |
| Discourse | no | User login prefixed with @ | |
| Jira | no | User login prefixed with @ | |
| MediaWiki | Special link format ([[User:Username]]) | ||
| Drupal | https://www.drupal.org/project/mentions | Special link format ([@userlogin]). Displayed with the user login prefixed with @ | |
| Confluence | https://confluence.atlassian.com/doc/mentions-251725350.html | User login prefixed with @ |
