Mentions plugin
This plugin is only available for paid TinyMCE subscriptions. |
The mentions plugin will present a list of users when a user types the "@" symbol followed by the beginnings of a username after it. It will then query your server using the mentions_fetch
callback.
Interactive example
-
TinyMCE
-
HTML
-
CSS
-
JS
-
Edit on CodePen
<textarea id="mentions">
<p><img style="display: block; margin-left: auto; margin-right: auto;" title="Tiny Logo" src="https://www.tiny.cloud/docs/images/logos/android-chrome-256x256.png" alt="TinyMCE Logo" width="128" height="128"></p>
<h2 style="text-align: center;">Welcome to the TinyMCE Mentions interactive demo!</h2>
<p>Type "<kbd>@</kbd>" followed immediately by one or more characters.</p>
<p>For example: @a</p>
<p style="text-align: center;">And visit the <a href="https://www.tiny.cloud/pricing">pricing page</a> to learn more about our Premium plugins.</p>
<h2>A simple table to play with</h2>
<table style="border-collapse: collapse; width: 100%;" border="1">
<thead>
<tr style="text-align: left;">
<th>Product</th>
<th>Cost</th>
<th>Really?</th>
</tr>
</thead>
<tbody>
<tr>
<td>TinyMCE Cloud</td>
<td>Get started for free</td>
<td><strong>Yes!</strong></td>
</tr>
<tr>
<td>Plupload</td>
<td>Free</td>
<td><strong>Yes!</strong></td>
</tr>
</tbody>
</table>
<h2>Found a bug?</h2>
<p>If you believe you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>
<h2>Finally…</h2>
<p>Don't forget to check out <a href="http://www.plupload.com" target="_blank" rel="noopener">Plupload</a>, the upload solution featuring HTML5 upload support.</p>
<p>Thanks for supporting TinyMCE. We hope it helps you and your users create great content.</p>
<p>All the best from the TinyMCE team.</p>
</textarea>
textarea#mentions {
height: 350px;
}
.mymention {
color: gray !important;
}
div.card,
.tox div.card {
width: 240px;
background: white;
border: 1px solid #ccc;
border-radius: 3px;
box-shadow: 0 4px 8px 0 rgba(34, 47, 62, .1);
padding: 8px;
font-size: 14px;
font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif;
}
div.card::after,
.tox div.card::after {
content: "";
clear: both;
display: table;
}
div.card h1,
.tox div.card h1 {
font-size: 14px;
font-weight: bold;
margin: 0 0 8px;
padding: 0;
line-height: normal;
font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif;
}
div.card p,
.tox div.card p {
font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif;
}
div.card img.avatar,
.tox div.card img.avatar {
width: 48px;
height: 48px;
margin-right: 8px;
float: left;
}
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const mentions_fetch = async (query, success) => {
const searchPhrase = query.term.toLowerCase();
await fetch(`${API_URL}?q=${encodeURIComponent(searchPhrase)}`)
.then((response) => response.json())
.then((users) => success(users.data.map((userInfo) => ({
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
}))))
.catch((error) => console.log(error));
};
const mentions_menu_complete = (editor, userInfo) => {
const span = editor.getDoc().createElement('span');
span.className = 'mymention';
span.setAttribute('data-mention-id', userInfo.id);
span.appendChild(editor.getDoc().createTextNode('@' + userInfo.name));
return span;
};
const createCard = (userInfo) => {
const div = document.createElement('div');
div.innerHTML = (
'<div class="card">' +
'<img class="avatar" src="' + userInfo.image + '">' +
'<h1>' + userInfo.name + '</h1>' +
'<p>' + userInfo.description + '</p>' +
'</div>'
);
return div;
};
const mentions_select = async (mention, success) => {
const id = mention.getAttribute('data-mention-id');
await fetch(`${API_URL}/${id}`)
.then((response) => response.json())
.then((userInfo) => {
const card = createCard({
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
});
success(card);
})
.catch((error) => console.error(error));
};
const mentions_menu_hover = async (userInfo, success) => {
const card = createCard(userInfo);
success(card);
};
tinymce.init({
selector: "textarea",
plugins: [
"advlist", "anchor", "autolink", "charmap", "code", "fullscreen",
"help", "image", "insertdatetime", "link", "lists", "media",
"preview", "searchreplace", "table", "visualblocks", "mentions"
],
toolbar: "undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image",
content_style: '.mymention{ color: gray; }',
mentions_fetch,
mentions_item_type: 'profile',
mentions_menu_complete,
mentions_selector: '.mymention',
mentions_select,
mentions_menu_hover,
tinycomments_mode: 'embedded'
});
Options
These configuration options affect the execution of the mentions
plugin. The main option that needs to be implemented is the mentions_fetch
callback.
mentions_fetch
This option lets you request a list of users from your server that match a search query. The callback gets passed two parameters: one is the search query object, the other is the success callback to execute with the results. The query object has a term property that contains what the user has typed after the "@" sign.
The success call should contain an array of users.
Only the first ten (10) users listed in the array are displayed in the Mentions UI presented to end-users. |
For information on the user properties to pass to the success callback for the available mentions item types (mentions_item_type
), see: User properties.
Type: Function
Example: using mentions_fetch
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const mentions_fetch = async (query, success) => {
const searchPhrase = query.term.toLowerCase();
await fetch(`${API_URL}?q=${encodeURIComponent(searchPhrase)}`)
.then((response) => response.json())
.then((users) => success(users.data.map((userInfo) => ({
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
}))))
.catch((error) => console.log(error));
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_fetch
});
The success
callback can be passed an optional array of extra items. When clicked, the menu reloads and passes additional query parameters to the fetch function. The extra items can be used to search with different queries or show additional results, such as a full text search (which is slower to fetch). Each extra item should contain:
-
A "text" property for the content to be displayed in the menu.
-
A "meta" property for that will be passed using the fetch query parameter.
Example with extras
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const mentions_fetch = async (query, success) => {
const searchPhrase = query.term.toLowerCase();
await fetch(`${API_URL}?q=${encodeURIComponent(searchPhrase)}`)
.then((response) => response.json())
.then((users) => {
const mentions = users.data.map((userInfo) => ({
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
...(query.meta && query.meta.email)
? { email: userInfo.custom.email }
: {}
}));
const extras = [{
text: 'Include email...',
meta: { email: true }
}];
success(mentions, extras);
})
.catch((error) => console.log(error));
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_fetch
});
mentions_item_type
This option sets which user interface item type to use when displaying the list of users.
-
The
name
item will only display the user’s name. -
The
profile
item will display the user’s name and can display an optional image and description.
For information on the properties required for the user object provided to mentions_fetch
, see: User properties.
Type: String
Default value: 'name'
Possible values: 'name'
, 'profile'
Example: using mentions_item_type
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_item_type: 'name'
});
User properties
The following table describes the properties available for user objects provided to the mentions_fetch
callback. Properties may be required, optional, or not available; depending on the mentions_item_type
and mentions_select
options.
Name | Value | name |
profile |
Description |
---|---|---|---|---|
id |
string |
required |
required |
Used to identify the user mention in different callbacks |
name |
string |
required |
required |
Name to display and highlight matches |
image |
string |
not available |
optional |
Image source for user avatar |
description |
string |
not available |
optional |
Description to display |
mentions_min_chars
This option specifies the number of characters a user needs to type after the "@" symbol before the list of users will be displayed.
Type: Number
Default value: 1
mentions_menu_complete
This option overrides the default logic for inserting the mention into the editor. The callback should return an element created using the editor’s document.
Type: Function
Example: using mentions_menu_complete
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const mentions_menu_complete = (editor, userInfo) => {
const span = editor.getDoc().createElement('span');
span.className = 'mymention';
span.setAttribute('data-mention-id', userInfo.id);
span.appendChild(editor.getDoc().createTextNode('@' + userInfo.name));
return span;
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_selector: 'span.mymention',
mentions_menu_complete
});
mentions_menu_hover
This option enables you to provide an element to present next to the menu item being hovered. This lets you do custom UIs for presenting user information.
Type: Function
Example: using mentions_menu_hover
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const createCard = (userInfo) => {
const div = document.createElement('div');
div.innerHTML = (
'<div class="card">' +
'<img class="avatar" src="' + userInfo.image + '">' +
'<h1>' + userInfo.name + '</h1>' +
'<p>' + userInfo.description + '</p>' +
'</div>'
);
return div;
};
const mentions_menu_hover = async (userInfo, success) => {
const card = createCard(userInfo);
success(card);
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_selector: '.mymention',
mentions_menu_hover
});
mentions_menu_hover
with predefined templates
If mentions_menu_hover
is resolved with an object specifying the type and user details, a predefined hover card template will be used. To use the predefined template, set type
to 'profile'
. For details on the user properties required for the profile
template, see: User properties.
mentions_selector
This option enables you to provide a custom CSS selector that should match the element created using mentions_menu_complete
. This enables the plugin to find existing mentions. The callback takes two parameters: the editor instance and the userInfo object.
Type: Function
Example: using mentions_selector
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_selector: 'span.mymention',
mentions_menu_complete: (editor, userInfo) => {
const span = editor.getDoc().createElement('span');
span.className = 'mymention';
span.setAttribute('data-mention-id', userInfo.id);
span.appendChild(editor.getDoc().createTextNode('@' + userInfo.name));
return span;
}
});
mentions_select
This option enables a hover card to be presented when a user hovers over a mention in TinyMCE. This could include details about the user. A custom hover card HTML element can be provided or a predefined template can be specified.
Type: Function
Example: using mentions_select
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const createCard = (userInfo) => {
const div = document.createElement('div');
div.innerHTML = (
'<div class="card">' +
'<img class="avatar" src="' + userInfo.image + '">' +
'<h1>' + userInfo.name + '</h1>' +
'<p>' + userInfo.description + '</p>' +
'</div>'
);
return div;
};
const mentions_select = async (mention, success) => {
const id = mention.getAttribute('data-mention-id');
await fetch(`${API_URL}/${id}`)
.then((response) => response.json())
.then((userInfo) => {
const card = createCard({
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
});
success(card);
})
.catch((error) => console.error(error));
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_selector: '.mymention',
mentions_select
});
mentions_select
with predefined templates
If mentions_select
is resolved with an object specifying the type and user details, a predefined hover card template will be used. To use the predefined template, set type
to 'profile'
. For details on the user properties required for the profile
template, see: User properties.
Example: using the 'profile'
template with mentions_select
const API_URL = 'https://demouserdirectory.tiny.cloud/v1/users';
const mentions_select = async (mention, success) => {
const id = mention.getAttribute('data-mention-id');
await fetch(`${API_URL}/${id}`)
.then((response) => response.json())
.then((userInfo) => {
const user = {
id: userInfo.id,
name: userInfo.name,
image: userInfo.avatar,
description: userInfo.custom.role
};
success({ type: 'profile', user });
})
.catch((error) => console.error(error));
};
tinymce.init({
selector: 'textarea',
plugins: 'mentions',
mentions_selector: '.mymention',
mentions_select
});