DOC-2174: added documentation for Mentions plugin's getUsers API deprecation to 6.0-release-notes-premium-changes.adoc and migration-from-5x.adoc (#3060)

* added getusers-api-alternative demo to 6.0 release notes and the 5 to 6 migration guide

* fix demo toolbar

* added changelog entry

* Apply suggestions from code review

Co-authored-by: Mitchell Crompton <[email protected]>

* added more names to getusers-api-alternative demo

* Update changelog.md

---------

Co-authored-by: Mitchell Crompton <[email protected]>

Author: Farzad Hayat

changelog.md

@@ -8,6 +8,7 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 ### 2024-02-13
 
+- DOC-2174: added documentation for Mentions plugin's `getUsers` API deprecation to `6.0-release-notes-premium-changes.adoc` and `migration-from-5x.adoc`.
 - DOC-2162: Improve documentation for `noneditable` options and multi-root editing.
 
 ### 2024-02-09

modules/ROOT/examples/live-demos/getusers-api-alternative/index.html

@@ -0,0 +1,16 @@
+<textarea id="getusers-api-alternative">
+<p>The deprecated <code>getUsers</code> API would return an array of currently mentioned names which were mentioned since loading the editor.</p>
+<p>Add some mentions to the content by typing "@a...", then click the <strong>getUsers</strong> button in the toolbar to insert a list of names which have been mentioned.</p>
+
+<br><br><br>
+
+<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">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>

modules/ROOT/examples/live-demos/getusers-api-alternative/index.js

@@ -0,0 +1,58 @@
+const users = [
+  { id: 'user-1', name: 'Angelina Winn' },
+  { id: 'user-2', name: 'Rodrigo Hawkins' },
+  { id: 'user-3', name: 'Dianna Smiley' },
+  { id: 'user-4', name: 'Eliana Stout' },
+  { id: 'user-5', name: 'Oscar Khan' },
+  { id: 'user-6', name: 'Mariana Dickey' },
+  { id: 'user-7', name: 'Jakoby Roman' },
+  { id: 'user-8', name: 'Grace Gross' },
+  { id: 'user-9', name: 'Muhammed Sizemore' },
+  { id: 'user-10', name: 'Kathryn Mcgee' },
+];
+
+const fetchMentions = (query, success) => {
+  const matches = users.filter((user) => user.name.toLowerCase().includes(query.term.toLowerCase()));
+  success(matches);
+};
+
+const insertedUsers = new Set();
+
+const mentionsInsert = (editor, user) => {
+  const span = editor.getDoc().createElement('span');
+  span.className = 'mention';
+  span.appendChild(editor.getDoc().createTextNode('@' + user.name));
+  insertedUsers.add(user);
+  return span;
+};
+
+const getUsers = (editor) => {
+  const spans = Array.from(editor.getBody().querySelectorAll('[data-mce-mentions-id]'));
+  const currentIds = spans.map((elm) => elm.getAttribute('data-mce-mentions-id'));
+  const currentUsers = Array.from(insertedUsers).filter((user) => currentIds.includes(user.id));
+
+  return currentUsers;
+};
+
+tinymce.init({
+  selector: "textarea#getusers-api-alternative",
+  plugins: "mentions code",
+  mentions_fetch: fetchMentions,
+  mentions_menu_complete: mentionsInsert,
+
+  toolbar: 'getUsersButton',
+  setup: function (editor) {
+	editor.ui.registry.addButton('getUsersButton', {
+	  text: 'getUsers',
+	  onAction: function () {
+		// Get mentioned users
+		var mentionedUsers = getUsers(editor);
+    // Insert mentioned users as a bullet list
+		if (mentionedUsers.length > 0) {
+		  var userList = mentionedUsers.map((user) => '<li>' + user.name + '</li>').join('');
+		  editor.execCommand('mceInsertContent', false, '<ul>' + userList + '</ul>');
+		}
+	  }
+	});
+  }
+});

modules/ROOT/pages/6.0-release-notes-premium-changes.adoc

@@ -172,6 +172,9 @@ The following change was made to the xref:mentions.adoc[Mentions] plugin:
 
 The `getUsers` API was removed.
 
+View the following demo for an alternative to the `getUsers` API:
+
+liveDemo::getusers-api-alternative[height="400"]
 
 === PowerPaste
 

modules/ROOT/pages/migration-from-5x.adoc

@@ -309,6 +309,14 @@ The schema must, therefore, be configured to allow usage of the media elements,
 
 NOTE: As of this release, there are no known cases of this change causing media objects to not work as expected. But, also as of this release, not every potential or possible use-case has been tested.
 
+=== Mentions
+
+The `getUsers` API was a part of the `mentions` plugin and was used to retrieve a list of mentioned users in the current editor session.
+
+This API has been _deprecated_ in {productname} 6.0.
+
+Refer to the xref:6.0-release-notes-premium-changes.adoc#mentions[_{productname} 6.0 Release Notes_] for an alternative to the `getUsers` API.
+
 [[plugins-paste]]
 === Paste