DOC-3246: Suggested Edits and User Lookup API documentation

antora-playbook.yml

@@ -8,7 +8,7 @@ content:
     branches: HEAD
     start_path: ./
   - url: https://github.com/tinymce/tinymce-docs.git
-    branches: [ tinymce/5, tinymce/6, tinymce/7]
+    branches: [ tinymce/5, tinymce/6, tinymce/7 ]
 urls:
   html_extension_style: indexify
   latest_version_segment: latest

antora.yml

@@ -10,7 +10,7 @@ asciidoc:
     companyurl: https://www.tiny.cloud
     cdnurl: https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js
     tdcdnurl: https://cdn.tiny.cloud/1/_your_api_key_/tinydrive/7/tinydrive.min.js
-    tinymce_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinymce/7/tinymce.min.js
+    tinymce_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinymce/8-dev/tinymce.min.js
     tinydrive_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinydrive/7/tinydrive.min.js
     webcomponent_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent/dist/tinymce-webcomponent.min.js
     jquery_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@2/dist/tinymce-jquery.min.js

modules/ROOT/examples/live-demos/comments-callback-with-mentions/index.js

@@ -1,18 +1,23 @@
 import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then(({ faker }) => {
+  /* This represents a database of users on the server */
   const userDb = {
     'michaelcook': {
       id: 'michaelcook',
       name: 'Michael Cook',
-      fullName: 'Michael Cook',
-      description: 'Product Owner',
-      image: "{{imagesdir}}/avatars/michaelcook.png"
+      avatar: '{{imagesdir}}/avatars/michaelcook.png',
+      custom: {
+        fullName: 'Michael Cook',
+        description: 'Product Owner'
+      }
     },
     'kalebwilson': {
       id: 'kalebwilson',
       name: 'Kaleb Wilson',
-      fullName: 'Kaleb Wilson',
-      description: 'Marketing Director',
-      image: "{{imagesdir}}/avatars/kalebwilson.png"
+      avatar: '{{imagesdir}}/avatars/kalebwilson.png',
+      custom: {
+        fullName: 'Kaleb Wilson',
+        description: 'Marketing Director',
+      }
     }
   };
 
@@ -35,7 +40,7 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
   const getAuthorInfo = (uid) => {
     const user = userDb[uid];
     if (user) {
-      return fillAuthorInfo(user.id, user.fullName, user.image);
+      return fillAuthorInfo(user.id, user.custom.fullName, user.avatar);
     }
     return {
       author: uid,
@@ -85,8 +90,8 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
   const resolvedConversationDb = {};
 
   const setupFakeServer = () => {
-    const images = [ adminUser.image, currentUser.image ];
-    const userNames = [ adminUser.fullName, currentUser.fullName ];
+    const images = [ adminUser.avatar, currentUser.avatar ];
+    const userNames = [ adminUser.custom.fullName, currentUser.custom.fullName ];
 
     for (let i = 0; i < numberOfUsers; i++) {
       images.push(faker.image.avatar());
@@ -99,14 +104,16 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
       [currentUser.id]: currentUser
     };
     userNames.map((fullName) => {
-      if ((fullName !== currentUser.fullName) && (fullName !== adminUser.fullName)) {
+      if ((fullName !== currentUser.custom.fullName) && (fullName !== adminUser.custom.fullName)) {
         const id = fullName.toLowerCase().replace(/ /g, '');
         userDb[id] = {
           id,
           name: fullName,
-          fullName,
-          description: faker.person.jobTitle(),
-          image: images[Math.floor(images.length * Math.random())]
+          avatar: images[Math.floor(images.length * Math.random())],
+          custom: {
+            fullName,
+            description: faker.person.jobTitle(),
+          }
         };
       }
     });
@@ -118,8 +125,8 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
         const users = Object.keys(userDb).map((id) => ({
           id,
           name: userDb[id].name,
-          image: userDb[id].image,
-          description: userDb[id].description
+          image: userDb[id].avatar,
+          description: userDb[id].custom.description
         }));
         resolve(users);
       }, fakeDelay);
@@ -320,9 +327,6 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     });
     setTimeout(() => done({ conversations: fetchedConversations }), fakeDelay);
   };
-
-  // Read the above `getAuthorInfo` function to see how this could be implemented
-  const tinycomments_fetch_author_info = (done) => done(getAuthorInfo(currentUid));
 
   tinymce.init({
     selector: 'textarea#comments-callback-with-mentions',
@@ -350,9 +354,16 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     mentions_select,
 
     tinycomments_mode: 'callback',
-    tinycomments_author: currentUser.id,
-    tinycomments_author_name: currentUser.fullName,
-    tinycomments_avatar: currentUser.image,
+    user_id: currentUser.id,
+    fetch_users: (userIds) => {
+      return Promise.all(
+        userIds.map(
+          (userId) => new Promise(
+            (resolve) => resolve(userDb[userId] || { id: userId })
+          )
+        )
+      )
+    },
     tinycomments_create,
     tinycomments_reply,
     tinycomments_delete,
@@ -362,6 +373,5 @@ import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then
     tinycomments_delete_comment,
     tinycomments_edit_comment,
     tinycomments_fetch,
-    tinycomments_fetch_author_info
   });
 });

modules/ROOT/examples/live-demos/comments-embedded-with-mentions/index.js

@@ -1,19 +1,28 @@
 import ('https://cdn.jsdelivr.net/npm/@faker-js/faker@9/dist/index.min.js').then(({ faker }) => {
-  const adminUser = {
-    id: 'johnsmith',
-    name: 'John Smith',
-    fullName: 'John Smith',
-    description: 'Company Founder',
-    image: "https://i.pravatar.cc/150?img=11"
-  };
+  /* This represents a database of users on the server */
+  const userDb = {
+    'johnsmith': {
+      id: 'johnsmith',
+      name: 'John Smith',
+      avatar: 'https://i.pravatar.cc/150?img=11',
+      custom: {
+        fullName: 'John Smith',
+        description: 'Company Founder',
+      }
+    },
+    'jennynichols': {
+      id: 'jennynichols',
+      name: 'Jenny Nichols',
+      avatar: 'https://i.pravatar.cc/150?img=10',
+      custom: {
+        fullName: 'Jenny Nichols',
+        description: 'Marketing Director',
+      }
+    }
+  }
 
-  const currentUser = {
-    id: 'jennynichols',
-    name: 'Jenny Nichols',
-    fullName: 'Jenny Nichols',
-    description: 'Marketing Director',
-    image: "https://i.pravatar.cc/150?img=10"
-  };
+  const adminUser = userDb['johnsmith'];
+  const currentUser = userDb['jennynichols'];
 
   const fakeDelay = 500;
   const numberOfUsers = 200;
@@ -24,28 +33,25 @@
   const userRequest = {};
 
   const setupFakeServer = () => {
-    const images = [ adminUser.image, currentUser.image ];
-    const userNames = [ adminUser.fullName, currentUser.fullName ];
+    const images = [ adminUser.avatar, currentUser.avatar ];
+    const userNames = [ adminUser.custom.fullName, currentUser.custom.fullName ];
 
     for (let i = 0; i < numberOfUsers; i++) {
       images.push(faker.image.avatar());
       userNames.push(`${faker.person.firstName()} ${faker.person.lastName()}`);
     }
-
-    /* This represents a database of users on the server */
-    const userDb = {
-      [adminUser.id]: adminUser,
-      [currentUser.id]: currentUser
-    };
+
     userNames.map((fullName) => {
-      if ((fullName !== currentUser.fullName) && (fullName !== adminUser.fullName)) {
+      if ((fullName !== currentUser.custom.fullName) && (fullName !== adminUser.custom.fullName)) {
         const id = fullName.toLowerCase().replace(/ /g, '');
         userDb[id] = {
           id,
           name: fullName,
-          fullName,
-          description: faker.person.jobTitle(),
-          image: images[Math.floor(images.length * Math.random())]
+          avatar: images[Math.floor(images.length * Math.random())],
+          custom: {
+            fullName,
+            description: faker.person.jobTitle(),
+          }
         };
       }
     });
@@ -155,9 +161,16 @@
 
     tinycomments_mode: 'embedded',
     sidebar_show: 'showcomments',
-    tinycomments_author: currentUser.id,
-    tinycomments_author_name: currentUser.fullName,
-    tinycomments_avatar: currentUser.image,
+    user_id: currentUser.id,
+    fetch_users: (userIds) => {
+      return Promise.all(
+        userIds.map(
+          (userId) => new Promise(
+            (resolve) => resolve(userDb[userId] || { id: userId })
+          )
+        )
+      )
+    },
     tinycomments_can_resolve,
   });
 });

modules/ROOT/examples/live-demos/comments-embedded/index.js

@@ -16,7 +16,7 @@ tinymce.init({
   quickbars_image_toolbar: 'alignleft aligncenter alignright | rotateleft rotateright | imageoptions',
   tinycomments_mode: 'embedded',
   sidebar_show: 'showcomments',
-  tinycomments_author: currentAuthor,
+  user_id: currentAuthor,
   tinycomments_can_resolve: (req, done, fail) => {
     const allowed = req.comments.length > 0 &&
                   req.comments[0].author === currentAuthor;

modules/ROOT/examples/live-demos/revisionhistory/index.js

@@ -4,6 +4,15 @@ const getRandomDelay = () => {
   return Math.floor(Math.random() * (maxDelay - minDelay + 1)) + minDelay;
 };
 
+/* This represents a database of users on the server */
+const userDb = {
+  'john.doe': { 
+    id: 'john.doe', 
+    name: 'John Doe', 
+    avatar: 'https://i.pravatar.cc/150?img=11' 
+  }
+};
+
 const lightRevisions = [
   {
     revisionId: '3',
@@ -202,9 +211,15 @@ tinymce.init({
   content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
   revisionhistory_fetch,
   revisionhistory_fetch_revision,
-  revisionhistory_author: {
-    id: 'john.doe',
-    name: 'John Doe'
-  },
+  user_id: 'john.doe',
+    fetch_users: (userIds) => {
+      return Promise.all(
+        userIds.map(
+          (userId) => new Promise(
+            (resolve) => resolve(userDb[userId] || { id: userId })
+          )
+        )
+      )
+    },
   revisionhistory_display_author: true
 });

modules/ROOT/examples/live-demos/suggestededits-access-feedback/example.js

@@ -0,0 +1,21 @@
+const tinymceElement = document.querySelector('textarea#suggested-edits');
+const model = tinymceElement.getAttribute('suggestededits-model');
+
+tinymce.init({
+  selector: 'textarea#suggested-edits',
+  height: 500,
+  plugins: 'suggestededits advlist anchor autolink code charmap emoticons fullscreen help image link lists media preview searchreplace table',
+  toolbar: 'undo redo | suggestededits | styles fontsizeinput | bold italic | align bullist numlist | table link image | code',
+  user_id: 'michaelcook',
+  fetch_users: (userIds) => Promise.all(userIds
+    .map((userId) =>
+      fetch(`/users/${userId}`) // Fetch user data from the server
+      .then((response) => response.json())
+      .catch(() => ({ id: userId })) // Still return a valid user object even if the fetch fails
+  )),
+  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
+  readonly: false, // Set to true to prevent edits to the content
+  suggestededits_access: 'feedback', // Set this value to restrict the permissions in the Suggested Edits view
+  suggestededits_content: 'html',
+  suggestededits_model: model
+});

modules/ROOT/examples/live-demos/suggestededits-access-feedback/index.html

@@ -0,0 +1,44 @@
+<textarea id="suggestededits-access-feedback">
+  {{logofordemoshtml}}
+
+  <h2 style="text-align: center;">Welcome to the TinyMCE Suggested Edits demo!</h2>
+
+  <p style="text-align: center;">Try out the Suggested Edits feature by typing in the editor and then clicking the Review Changes button in the toolbar.</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">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>