User Mentions

Version 52.4 by Manuel Leduc on 2020/05/11 18:06

 

https://forum.xwiki.org/t/user-mention-in-ck-editor/843

Description

Introduction

Mentions are a structured way to reference users in the text (e.g., comments, annotations, documents).

They are usually visually distinguishable by an @ prefix followed by the identifier of a user, often in hypertext form (e.g., @mleduc).

This document first presents the specifications. Then the discussion list some topic for which no final decision has been made. Finally, the tasks section presents a more technical and fine-grained description of the tasks required for the integration of the mentions in XWiki.

The implementation section describes the implementation details of the identified use cases.

Additionally, existing discussions list some discussions that are related to the topic of user mentions, and the comparison matrix present a partial view on the integration of user mentions in other wikis and social services.

Table of content

  1. Introduction
  2. Table of content
  3. Specifications
    1. Mentions Integration
    2. Notifications
      1. Notifications content
      2. Notifications answer
      3. Notifications settings
    3. Extensibility
  4. Discussions
    1. Requesting view rights
      1. Messaging
      2. Ad-hoc mechanism
  5. Tasks
    1. UC1. Rich editor integration
    2. UC2. Adding an auto-completion on the rich editor
    3. UC3. Mention macro
    4. UC4. Mention macro settings
    5. UC5. Mention in the syntax
      1. UC5.1. XWiki/2.2
      2. UC5.x. Other syntaxes
    6. UC6. New mentions identification
    7. UC7. Notifications
      1. UC7.1 Notifications integration
      2. UC7.2 Notifications settings
    8. UC8. Answering to a notification from the notification
    9. UC9. Answer to a notification by email
    10. UC10. Integration of browser notifications
    11. UC11. Integration of answers from external source
    12. UC12. Auto page watch
    13. Tasks on Jira
  6. Implementation
    1. General guidelines
    2. Rich editor integration
    3. Mentions auto-completion
    4. Mentions macro
    5. Mentions style
      1. Html
      2. CSS
    6. Mention creation
    7. MentionCreatedEvent handling
    8. Notifications integration
      1. User
        1. Document body
        2. Document comment
        3. Document annotation
        4. Document AWM textarea field
      2. Group
        1. Document body
        2. Document comment
        3. Document annotation
        4. Document AWM textarea field
      3. Answering
    9. Integration of browser notifications
  7. Existing discussions
    1. Links extensibility
  8. Comparison matrix

Specifications

Mentions Integration

It should be possible to add mentions to users or groups wherever XWiki syntaxes are supported.

The list of impacted fields 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)

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 could have a specific background color. Similarly, mentions to the current user and/or a group in which the current user 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 the content to 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 displayed clearly, it should possibly be identifiable visually that the user has been removed with a strikethrough on the name (which is not easy to identify in the context of AP for instance).

Screenshot from 2020-05-11 14-52-05.png

Notifications

Notifications content

The content of a notification message 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 (document body, comment, annotation...)
  • 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 the comment
    • an anchor to the annotation
    • an anchor to the AWM field in the document in read mode.

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 include:

  • having a form to interact with the content directly in the content of the notification created by the mention
  • being able to answer directly to mail eventually received as a notification of a mention

Notifications settings

Notifications of mentions should be integrated into 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.

image-20200507101357956.png

Extensibility

While the nominal scenario is the integration of mentions inside an 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
  • user identifiers resolution
  • an extension point on the notifications emission.

Besides, the core of the mentions must support unknown types of external users.

Discussions

Requesting view rights

If a 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 requiring 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 advanced 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

UC#Depends onTitleComplexityPriority
UC1 Rich editor integrationMediumHigh
UC2UC3Adding an auto-completion on the rich editorMediumHigh
UC3  Mention macroMediumHigh
UC4 UC3Mention macro settingsEasyLow
UC5.1  Mentions in XWiki/2.2HardLow
UC6 UC3New mentions identificationHardMedium
UC7.1UC6Notifications integrationMediumHigh
UC7.2UC7.1Notifications settingsMediumMedium
UC8UC7.1Answering to a notification from the notificationMediumLow
UC9UC7.1Answer to a notification by emailHardLow
UC10 Integration of browser notificationsTBDMedium
UC11UC7.1Integration of answers from external sourceMediumLow
UC12 Auto page watchEasyLow

UC1. Rich editor integration

The mention feature must be eased by the generalization of the integration of the rich editor.

This is currently not the case and multiple places where it would be interesting to have user mentions (i.e., comments and annotations) support XWiki syntax without being supported by a rich editor.

The rich editor must be integrated on every textarea supporting the XWiki syntax and be activated by default for users that choose wysiwyg as by default.

UC2. Adding an auto-completion on the rich editor

Typing @ in the rich editor must present an auto-completion of available users and groups and automatically insert the corresponding macro in the text.

Untitled.png

UC3. Mention macro

The mention macro must allow declaring a mention. This macro has one field pointing to a single user or group.

The macro must be displayed 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)

UC4. Mention macro settings

Variations points of the mention macro must be configurable in the skins administration

image-20200507110127020.png

UC5. Mention in the syntax

Mentions could be integrated as first-class entities in some syntaxes supported in the wiki if those syntaxes have build-in support for it.

UC5.1. XWiki/2.2

In the specific context of xwiki/2.2, user mentions could be built around the notions of links to users. See the discussions on Link extensibility.

UC5.x. Other syntaxes

TBD

UC6. New mentions identification

A user must only be notified on the first save after the introduction of a mention. That does not prevent the user to be notified several times (eventually for a single document save) if her name is newly introduced in several places of a text at once.

See the Implementation for more details of the realization of this feature.

UC7. Notifications

UC7.1 Notifications integration

The notifications must be integrated and triggered from the relevant places and must rely on the mentions history to avoid duplicates.

Multiple templates must be defined, for each place where mentions can be defined.

UC7.2 Notifications settings

Integrate settings in the configuration to activate mentions at the level of the administration and at the level of individual users.

image-20200507101630235.png

UC8. Answering to a notification from the notification

When a mention links to an entity to which a user can answer (e.g., mentions and notifications), the mention must include a textarea allowing to quickly answer to the mention.

The way the answer is integration depends on the place where the mention originates from.

OriginAnswer
Document bodyThe answer is integrated as an annotation around the user's mention in the document.
CommentThe answer is integrated as a comment answering the originating comment.
AnnotationThe answer is integrated as a comment answering the originating annotation (which are actually handled as a comment, so the UX is similar to the comment case).
AWM textareaAs of today no mechanism allows a text to be attached to a specific text. Consequently, answering an AWM textarea is not supported and no answer should be proposed to the mentioned user in this case.

UC9. Answer to a notification by email

When a notification from a mention which a user can answer (e.g., mentions and notifications) is received by email, it should be possible to answer the email directly.

The answer is then integrated as an answer in the web interface.

Answering by email follows the same logic as UC8. Answering to a notification from the specifications.

UC10. Integration of browser notifications

Notifications can currently be displayed to the user through the notification menu and by email.

It should be possible to receive notifications using the Browser notification API integrated into most major browsers.

The browser notification can be activated in the same way as other notification methods, either globally in the administration, or for a user in her notification settings.

Screenshot from 2020-05-11 11-00-39.png

This feature is orthogonal to the integration of the user mentions, but allow better integration of the user's notifications in her browser (and eventually in the underlying OS).

UC11. Integration of answers from external source

If the mentions are notified to an external user using an extension mechanism (for instance in the context of an integration of the user mentions with ActivityPub), answers to the notification (for instance by a comment on Mastodon), should be gracefully integrated into the UI.

In summary, answering to mentions should be open to extensions.

UC12. Auto page watch

Whenever a user is mentioned in a document, he is automatically added to the watchers of the document.

This feature must be deactivated by default and could be activated by a setting in the user profile (section Watched Pages of the notification preference section, along with the Automatic page watching setting).

Tasks on Jira

Implementation

This section details further the implementation details of the user mention integration.

General guidelines

The business logic triggered by the introduction of a mention must be asynchronous and must not impact the reactiveness of  the UX.

Rich editor integration

Activating the rich editor is simply added using CKEDITOR.replace('identifier').

Is placing this operation enough?

Mentions auto-completion

The mechanism is the same as for links autocompletion the main differences being:

  • The itemTemplate, which inject a mention macro instead
  • The feed, which should point to a page which returns a list of matched users and group according to the substring currently typed by the user. This page is technically similar to CKEditor.LinkSuggestions.
  • The marker: '@'
  • Cached: yes

Mentions macro

The mention macro is a macro which has the following properties:

  • Macro Id: mention
  • Macro Name: Mention
  • Macro description: Insert a user mention
  • Support inline mode: yes
  • macro visibility: current wiki
  • macro content availability: no content

The macro has two parameters which have the following properties:

Identifier:

  • id: identifier
  • description: The identifier of the mentioned user or group.
  • Mandatory: yes

Display choice:

  • id: displayChoice
  • description: The display choice of the mention (this is only supported for user mention).
  • Mandatory: yes
  • Choices:
    • First name + last Name
    • First name
    • User login

The parameter takes a single fully qualified user or group identifier (e.g., xwiki:XWiki.U1, xwiki:XWiki.MyGroup, [email protected]).
The identifier is later resolved as a local or external user following a chain of resolvers by calling the components that implement the MentionUserResolver roles, ordered by their priority.

That way, extensions can be added to resolve new kinds of users (for instance, using webfinger for activitypub).

Mentions style

Html

<a class="mention user self">@Admin</a> <a class="mention user">@OtherUser</a> <a class="mention group self">@XWikiAdminGroup</a> <a class="mention group">@OtherGroup</a>

CSS

Of course the actual colors used in the style must be retrieved from the value configured in the skin settings.

a.mention {
 background-color: #c2c2c25e;
 border-radius: 8px;
 padding: 2px 5px 2px 5px;
}

a.mention.user.self {
 background-color: #ff00005e;
}

a.mention.group.self {
 background-color: #00ff005e;
}

a.mention.removed {
text-decoration: line-through;
}

Mention creation

Mentions are identified by listening to XWiki existing events. The events listed below are listened to using a class implementing org.xwiki.observation.AbstractEventListener.

TypeEventsContent
Document/AWM textarea

org.xwiki.bridge.event.DocumentCreatedEvent, org.xwiki.bridge.event.AnnotationAddedEvent|XDOM/Fields of type LargeStringProperty of the objects of the document.| 

Comment

org.xwiki.bridge.event.CommentAddedEvent, org.xwiki.bridge.event.AnnotationAddedEvent|XDOM| 

Annotation

org.xwiki.bridge.event.AnnotationAddedEvent, org.xwiki.bridge.event.AnnotationAddedEvent|XDOM| 

To make the event handling asynchronous, the only task of this event listener is to create a job executor request (MentionRequest) later handled by a dedicated org.xwiki.contrib.activitypub.internal.async.jobs.AbstractPageNotificationJob<MentionRequest, MentionStatus> implementation, in charge of the identification of actual mentions in the content.

In the case of content initial creation (DocumentCreatedEvent, CommentAddedEvent, AnnotationAddedEvent), all occurrences of the mention macro found in the content trigger a mention.

In case of content update (AnnotationAddedEvent, AnnotationAddedEvent, AnnotationAddedEvent), a comparison is realized against the previous version of the document, only newly introduced mention macro triggers a mention.
Newly identified mention are realized by counting the number of occurrences of the mentions to a given user in the updated XDOM, and to do the same task on the initial XDOM. A notification is sent to a given user if her number of mentions has increased.

This mechanism might be refined later to improve the accuracy of the user mentions notifications.

Note that this count must be realized after the resolution of the mentions macro's identifiers because there might be more than one way to identify the same user.

In practice, triggering a mention is realized by emitting a new event called org.xwiki.bridge.event.MentionCreatedEvent.

One event is created for each mentioned user. If a mention refers to a group, an event is created for each member of the group.

MentionCreatedEvent handling

This event can be freely listened to using a class implementing org.xwiki.observation.AbstractEventListener.

We provide a default implementation that is in charge to identify if the mentioned user is a local user of the XWiki, and if so, send a notification using the org.xwiki.observation.ObservationManager component.

Dedicated events must be created, for each type of notification:

  • DocumentMentionEvent: for mentions from a document body
  • AnnotationMentionEvent: for mentions from an annotation
  • CommentMentionEvent: for mentions from a comment
  • AWMFieldMentionEvent: for mentions from an AWM textarea field

Notifications integration

This component is dedicated to the handling and display of the mentions event.

A specific template is to be defined for each type of mention.

The sections below present drafts of the content of the mentions according to the origin (document body, commment...) and the type of the entity mentioned (user/group).

User

Document body

You are mentioned by __USER_NAME__ (+ link to user) on __DOCUMENT_NAME__. (link to the document view + anchor to the mention).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document comment

You are mentioned by __USER_NAME__ (+ link to user) on __DOCUMENT_NAME__ comments. (link to the document view + anchor to the comment).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document annotation

You are mentioned by __USER_NAME__ (+ link to user) on an annotation on __DOCUMENT_NAME__. (link to the document view + anchor to the annotation on the comments section).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document AWM textarea field

You are mentioned by __USER_NAME__ (+ link to user) on the field ___FIELD_NAME__ of  __DOCUMENT_NAME__ (link to the document view + anchor to the field).

(citation) __100 char before and 100 chars after the mentions__

Group

Document body

The group __GROUP_NAME__ (+ link to group) is mentioned by __USER_NAME__ (+ link to user) on __DOCUMENT_NAME__. (link to the document view + anchor to the mention).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document comment

The group __GROUP_NAME__ (+ link to group) is mentioned by __USER_NAME__ (+ link to user) on __DOCUMENT_NAME__ comments. (link to the document view + anchor to the comment).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document annotation

The group __GROUP_NAME__ (+ link to group) is mentioned by __USER_NAME__ (+ link to user) on an annotation on __DOCUMENT_NAME__. (link to the document view + anchor to the annotation on the comments section).

(citation) __100 char before and 100 chars after the mentions__

Answer button

Document AWM textarea field

The group __GROUP_NAME__ (+ link to group) is mentioned by __USER_NAME__ (+ link to user) on the field ___FIELD_NAME__ of  __DOCUMENT_NAME__ (link to the document view + anchor to the field).

(citation) __100 char before and 100 chars after the mentions__

Answering

Clicking the "Answer button" opens a modal window that provides a larger preview around the mentions and presents a textarea supporting XWiki syntax and rich editing.

Filling and submitting this textarea send an answer for the mention.

Integration of browser notifications

See https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API .

Note that the notification cannot be rendered as html, so their body and title must eventually be converted to plain text before being sent through this API.

Another important point is the management and activation of the notification user rights. 

Indeed, using Firefox, the pop-up below is only displayed to the user following and user action (e.g., a click event), otherwise, the query is proposed but not displayed to the user, who has to go activate the feature by himself.

Define how to trigger this popup on firefox 

05-15-54-58-Screenshot-2019-04-01-at-11.00.42-600x247.png_Ima.jpg

Existing discussions

This section collects discussions that are related to user mentions.

Mentions in CKEditor https://forum.xwiki.org/t/user-mention-in-ck-editor/843

Links extensibility

Comparison matrix

ProductDocumentationActivityPub?Details
Mastodon yesWebfinger ids or user login for the local instance, prefixed with @.
Twitter noUser login prefixed with @
Wordpresshttps://wordpress.com/support/user-mentions/yes (by extension)User login prefixed with @
Discourse noUser login prefixed with @
Jira noUser login prefixed with @
MediaWiki  Special link format ([[User:Username]])
Drupalhttps://www.drupal.org/project/mentions Special link format ([@userlogin]). Displayed with the user login prefixed with @
Confluencehttps://confluence.atlassian.com/doc/mentions-251725350.html User login prefixed with @

 

Tags:
    

Get Connected