From version < 19.1 >
edited by Manuel Leduc
on 2020/05/07 15:22
To version < 20.1 >
edited by Manuel Leduc
on 2020/05/07 15:39
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,4 +1,4 @@
1 -== Introduction ==
1 += Introduction =
2 2  
3 3  Mentions are a structured way to reference users in the text (e.g., comments, annotations, documents).
4 4  
... ... @@ -8,13 +8,13 @@
8 8  This document first presents the [[specifications>>||anchor="HSpecifications"]]. Then the [[discussion>>||anchor="HDiscussions"]] list some topic for which no final decision has been made. Finally, the [[tasks>>||anchor="HTasks"]] section presents a more technical and fine-grained description of the tasks required for the integration of the mentions in XWiki.
9 9  Additionally, [[existing discussions>>||anchor="HExistingdiscussions"]] list some discussions that are related to the topic of user mentions, and the [[comparison matrix>>||anchor="HComparisonmatrix"]] present a partial view on the integration of user mentions in other wikis and social services.
10 10  
11 -== Table of content ==
11 += Table of content =
12 12  
13 13  {{toc numbered="true"/}}
14 14  
15 -== Specifications ==
15 += Specifications =
16 16  
17 -=== Mentions Integration ===
17 +== Mentions Integration ==
18 18  
19 19  It should be possible to add mentions to users or groups wherever XWiki syntaxes are supported.
20 20  
... ... @@ -38,15 +38,15 @@
38 38  
39 39  Mentions of removed users should still be displayed clearly, eventually identified visually that the user has been removed (which is not easy to identify in the context of AP for instance).
40 40  
41 -=== Notifications ===
41 +== Notifications ==
42 42  
43 -==== Notifications rules ====
43 +=== Notifications rules ===
44 44  
45 45  Mentioning a user of a group must trigger an event, eventually leading to the notification of the concerned users.
46 46  
47 47  Nonetheless, users should not be notified several times for the same mention (e.g., when a document is edited and a mention to a given user was already in the document).
48 48  
49 -==== Notifications content ====
49 +=== Notifications content ===
50 50  
51 51  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.
52 52  
... ... @@ -62,7 +62,7 @@
62 62  * an anchor to an annotation
63 63  )))
64 64  
65 -==== Notifications answer ====
65 +=== Notifications answer ===
66 66  
67 67  The most basic scenario is to click on the link in the notification and to interact with the wiki as usual
68 68  
... ... @@ -71,7 +71,7 @@
71 71  * having a form to interact with the content directly in the content of the notification created by the mention
72 72  * being able to answer directly to mail eventually received as a notification of a mention
73 73  
74 -==== Notifications settings ====
74 +=== Notifications settings ===
75 75  
76 76  Notifications of mentions should be integrated into the notifications settings of the wiki, using the notifications framework provided by XWiki.
77 77  
... ... @@ -79,7 +79,7 @@
79 79  
80 80  [[image:image-20200507101357956.png]]
81 81  
82 -=== Extensibility ===
82 +== Extensibility ==
83 83  
84 84  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.
85 85  
... ... @@ -92,22 +92,22 @@
92 92  
93 93  In addition, the core of the mentions must support unknown types of external users.
94 94  
95 -== Discussions ==
95 += Discussions =
96 96  
97 -=== Requesting view rights ===
97 +== Requesting view rights ==
98 98  
99 99  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.
100 100  
101 -==== Messaging ====
101 +=== Messaging ===
102 102  
103 103  The most basic solution is to simply send a message to the user that triggered the mentions, asking for access to the page.
104 104  
105 -==== Ad-hoc mechanism ====
105 +=== Ad-hoc mechanism ===
106 106  
107 107  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.
108 108  
109 109  
110 -== Tasks ==
110 += Tasks =
111 111  
112 112  |=UC#|=Depends on|=Title|=Complexity|=Priority
113 113  |UC1| |[[Rich editor integration>>||anchor="HUC1.Richeditorintegration"]]|Medium|High
... ... @@ -121,7 +121,7 @@
121 121  |UC8|UC7.1|[[Answering to a notification from the notification>>||anchor="HUC8.Answeringtoanotificationfromthenotification"]]|Medium|Low
122 122  |UC9|UC7.1|[[Answer to a notification by email>>||anchor="HUC9.Answertoanotificationbyemail"]]|Hard|Low
123 123  
124 -=== UC1. Rich editor integration ===
124 +== UC1. Rich editor integration ==
125 125  
126 126  The rich editor must be integrated on every textarea supporting the XWiki syntax.
127 127  
... ... @@ -130,11 +130,11 @@
130 130  
131 131  WARNING: other places?
132 132  
133 -=== UC2. Adding an auto-completion on the rich editor ===
133 +== UC2. Adding an auto-completion on the rich editor ==
134 134  
135 135  Typing @ in the rich editor must present an auto-completion of available users and groups and automatically insert the corresponding macro in the text.
136 136  
137 -=== UC3. Mention macro ===
137 +== UC3. Mention macro ==
138 138  
139 139  The mention macro must allow declaring a mention. This macro has one field pointing to a single user or group.
140 140  
... ... @@ -144,26 +144,26 @@
144 144  
145 145  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)
146 146  
147 -=== UC4. Mention macro settings ===
147 +== UC4. Mention macro settings ==
148 148  
149 149  Variations points of the mention macro must be configurable in the skins administration
150 150  
151 151  [[image:image-20200507110127020.png]]
152 152  
153 -=== UC5. Mention in the syntax ===
153 +== UC5. Mention in the syntax ==
154 154  
155 155  Mentions could be integrated as first-class entities in some syntaxes supported in the wiki if those syntaxes have build-in support for it.
156 156  
157 -==== UC5.1. XWiki/2.2 ====
157 +=== UC5.1. XWiki/2.2 ===
158 158  
159 159  (% class="wikigeneratedid" %)
160 160  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>>||anchor="HLinksextensibility"]].
161 161  
162 -==== UC5.x. Other syntaxes ====
162 +=== UC5.x. Other syntaxes ===
163 163  
164 164  TBD
165 165  
166 -=== UC6. Mentions history ===
166 +== UC6. Mentions history ==
167 167  
168 168  A user must not be notified of a mention several times for the same entity (document, comment, annotation...).
169 169  
... ... @@ -175,45 +175,45 @@
175 175  
176 176  A notification is only sent 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.
177 177  
178 -=== UC7. Notifications ===
178 +== UC7. Notifications ==
179 179  
180 -==== UC7.1 Notifications integration ====
180 +=== UC7.1 Notifications integration ===
181 181  
182 182  The notifications must be integrated and triggered from the relevant places and must rely on the mentions history to avoid duplicates.
183 183  
184 184  Multiple templates must be defined, for each place where mentions can be defined.
185 185  
186 -==== UC7.2 Notifications settings ====
186 +=== UC7.2 Notifications settings ===
187 187  
188 188  integrate settings in the configuration to activate mentions at the level of the administration and at the level of individual users.
189 189  
190 190  [[image:image-20200507101630235.png]]
191 191  
192 -=== UC8. Answering to a notification from the notification ===
192 +== UC8. Answering to a notification from the notification ==
193 193  
194 194  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.
195 195  
196 -=== UC9. Answer to a notification by email ===
196 +== UC9. Answer to a notification by email ==
197 197  
198 198  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.
199 199  
200 200  The answer is then integrated as an answer in the web interface.
201 201  
202 -=== Tasks on Jira ===
202 +== Tasks on Jira ==
203 203  
204 204  {{jira url="https://jira.xwiki.org" source="jql"}}
205 205  labels = mentions ORDER BY priority DESC
206 206  {{/jira}}
207 207  
208 -=== ===
208 +== ==
209 209  
210 -== Existing discussions ==
210 += Existing discussions =
211 211  
212 212  This section collects discussions that are related to user mentions.
213 213  
214 214  Mentions in CKEditor https://forum.xwiki.org/t/user-mention-in-ck-editor/843
215 215  
216 -=== Links extensibility ===
216 +== Links extensibility ==
217 217  
218 218  * Proposal [[https:~~/~~/jira.xwiki.org/browse/XRENDERING-290>>https://jira.xwiki.org/browse/XRENDERING-290]]
219 219  ** Discussion [[https:~~/~~/xwiki.markmail.org/thread/vw3derowozijqalr>>https://xwiki.markmail.org/thread/vw3derowozijqalr]] / Vote + Discussion: [[http:~~/~~/markmail.org/message/t2wb2xq7534qsshg>>http://markmail.org/message/t2wb2xq7534qsshg]]
... ... @@ -220,7 +220,7 @@
220 220  ** Second vote [[http:~~/~~/markmail.org/message/colazwowt2lcpm5y>>url:http://markmail.org/message/colazwowt2lcpm5y]]
221 221  ** PoC [[https:~~/~~/github.com/xwiki/xwiki-rendering/compare/82958ceb6d78%5E...fcdc93e75ed0>>https://github.com/xwiki/xwiki-rendering/compare/82958ceb6d78%5E...fcdc93e75ed0]]
222 222  
223 -== Comparison matrix ==
223 += Comparison matrix =
224 224  
225 225  |=Product|=Documentation|=ActivityPub?|=Details
226 226  |Mastodon| |yes|Webfinger ids or user login for the local instance, prefixed with @.

 

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

Description

Introduction

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

Table of content

  1. Introduction
  2. Table of content
  3. Specifications
    1. Mentions Integration
    2. Notifications
      1. Notifications rules
      2. Notifications content
      3. Notifications answer
      4. Notifications settings
    3. Extensibility
  4. Discussions
    1. Requesting view rights
      1. Messaging
      2. Ad-hoc mechanism
    1. Introduction
    2. Table of content
    3. Specifications
      1. Mentions Integration
      2. Notifications
        1. Notifications rules
        2. Notifications content
        3. Notifications answer
        4. 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. Mentions history
      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. Tasks on Jira
      11. UserMentions
    6. Existing discussions
      1. Links extensibility
    7. Comparison matrix
  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. Mentions history
    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. Tasks on Jira
    11. UserMentions
  6. Existing discussions
    1. Links extensibility
  7. Comparison matrix

Specifications

Mentions Integration

Specifications

Mentions Integration

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

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

This list must be comprehensive.

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, eventually identified visually that the user has been removed (which is not easy to identify in the context of AP for instance).

Notifications

Notifications

Notifications rules

Notifications rules

Mentioning a user of a group must trigger an event, eventually leading to the notification of the concerned users.

Nonetheless, users should not be notified several times for the same mention (e.g., when a document is edited and a mention to a given user was already in the document).

Notifications content

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 a comment
    • an anchor to an annotation

Notifications answer

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

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
  • an extension point on the notifications emission.

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

Discussions

Requesting view rights

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

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

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

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 UC3Mentions historyHardMedium
UC7.1UC6Notifications integrationMediumHigh
UC7.2UC7.1Notifications settingsMediumMedium
UC8UC7.1Answering to a notification from the notificationMediumLow
UC9UC7.1Answer to a notification by emailHardLow

UC1. Rich editor integration

UC1. Rich editor integration

The rich editor must be integrated on every textarea supporting the XWiki syntax.

  • Comments
  • Annotations

WARNING: other places?

UC2. Adding an auto-completion on the rich editor

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.

UC3. Mention macro

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

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

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

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

UC5.x. Other syntaxes

TBD

UC6. Mentions history

UC6. Mentions history

A user must not be notified of a mention several times 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 sent 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.

UC7. Notifications

UC7. Notifications

UC7.1 Notifications integration

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

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

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.

UC9. Answer to a notification by email

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.

Tasks on Jira

Tasks on Jira

Existing discussions

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

Links extensibility

Comparison matrix

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 @


 

Get Connected