From 65e9e8fa307c3fae0d0f4e79d9378ca364ccd452 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 10 Sep 2025 15:14:23 +1000 Subject: [PATCH 1/5] DOC-2728: Documentation Enhancement: Comments callback. --- .../ROOT/pages/comments-callback-mode.adoc | 52 +++++++++++-------- .../ROOT/partials/commands/comments-cmds.adoc | 2 + .../plugins/comments-open-sidebar.adoc | 2 +- 3 files changed, 34 insertions(+), 22 deletions(-) diff --git a/modules/ROOT/pages/comments-callback-mode.adoc b/modules/ROOT/pages/comments-callback-mode.adoc index a5725f33bd..61c61ba993 100644 --- a/modules/ROOT/pages/comments-callback-mode.adoc +++ b/modules/ROOT/pages/comments-callback-mode.adoc @@ -6,23 +6,36 @@ :plugincode: comments :commentsMode: callback -*Callback mode* is the default mode for the {pluginname} plugin. In the callback mode, callback functions are required to save user comments on a server. The {pluginname} functions (create, reply, edit, delete comment, delete all conversations, resolve, lookup, and fetch conversations) are configured differently depending upon the server-side storage configuration. +*Callback mode* is the default mode for the {pluginname} plugin. In callback mode, callback functions are required to save user comments on a server. The {pluginname} functions (create, reply, edit, delete comment, delete all conversations, resolve, lookup, and fetch conversations) are configured differently depending upon the server-side storage configuration. + +[NOTE] +==== +Callback mode provides the most flexibility for integrating with custom backend systems. All comment operations are handled through custom callback functions that communicate with your server. +==== == How the {pluginname} plugin works in callback mode -All options accept functions incorporating `+done+` and `+fail+` callbacks as parameters. The function return type is not important, but all functions must call exactly one of these two callbacks: `+fail+` or `+done+`. +All callback functions accept three parameters: a request object (or array for `+tinycomments_fetch+`), a `+done+` callback, and a `+fail+` callback. The function return type is not important, but all functions must call exactly one of these two callbacks: `+fail+` or `+done+`. -* The `+fail+` callback takes either a string or a JavaScript Error type. -* The `+done+` callback takes an argument specific to each function. +* The `+fail+` callback takes either a string or a JavaScript Error type to indicate an unrecoverable error. +* The `+done+` callback takes an argument specific to each function to indicate successful completion. -Most functions (create, reply, and edit) require an +id+ identifying the current author. This can be provided directly within the callbacks or dynamically via the `+tinycomments_fetch_author_info+` option. +Most functions (create, reply, and edit) require an `+id+` identifying the current author. This can be provided directly within the callbacks or dynamically via the `+tinycomments_fetch_author_info+` option. [NOTE] -**Current author**: By default, the **Comments** plugin does not know the name of the current user. To display the correct author information when creating a new conversation, integrators can now use the `+tinycomments_fetch_author_info+` option to supply author details dynamically through a callback. +==== +**Current author**: By default, the **Comments** plugin does not know the name of the current user. To display the correct author information when creating a new conversation, integrators can use the `+tinycomments_fetch_author_info+` option to supply author details dynamically through a callback. + +**Author display names**: The `+authorName+` field is optional in comment objects. If not provided, the plugin will default to using the `+author+` field value. +==== + +=== Initial conversation loading + +During the initial editor load, the {pluginname} uses the `+tinycomments_fetch+` callback to retrieve existing conversations in the document. If not configured, the {pluginname} will fallback to `+tinycomments_lookup+`. -During the initial editor load, the {pluginname} uses `+tinycomments_fetch+` callback to retrieve the existing conversations in the document. If not configured, the {pluginname} will fallback to `+tinycomments_lookup+`. +=== Comment interaction flow -When a user adds a comment or a reply, the {pluginname} plugin uses the `+tinycomments_lookup+` callback to retrieve the selected conversation. +When a user adds a comment or a reply, the {pluginname} plugin uses the `+tinycomments_lookup+` callback to retrieve the selected conversation. This ensures that the latest conversation data is always displayed to users. [[comments-callback-live-demo]] == Interactive example @@ -31,17 +44,17 @@ liveDemo::comments-callback[] == Options -=== Required options +=== Required callback functions -When using callback mode, the {pluginname} plugin requires callback functions for the following options: +When using callback mode, the {pluginname} plugin requires callback functions for the following operations: -* xref:tinycomments_create[`+tinycomments_create+`] -* xref:tinycomments_reply[`+tinycomments_reply+`] -* xref:tinycomments_edit_comment[`+tinycomments_edit_comment+`] -* xref:tinycomments_delete_comment[`+tinycomments_delete_comment+`] -* xref:tinycomments_delete[`+tinycomments_delete+`] -* xref:tinycomments_delete_all[`+tinycomments_delete_all+`] -* xref:tinycomments_lookup[`+tinycomments_lookup+`] +* xref:tinycomments_create[`+tinycomments_create+`] - Creates new comment conversations +* xref:tinycomments_reply[`+tinycomments_reply+`] - Adds replies to existing conversations +* xref:tinycomments_edit_comment[`+tinycomments_edit_comment+`] - Edits existing comments +* xref:tinycomments_delete_comment[`+tinycomments_delete_comment+`] - Deletes individual comments +* xref:tinycomments_delete[`+tinycomments_delete+`] - Deletes entire conversation threads +* xref:tinycomments_delete_all[`+tinycomments_delete_all+`] - Deletes all conversations +* xref:tinycomments_lookup[`+tinycomments_lookup+`] - Retrieves specific conversations include::partial$configuration/tinycomments_create.adoc[leveloffset=+1] @@ -57,11 +70,8 @@ include::partial$configuration/tinycomments_delete_all.adoc[leveloffset=+1] include::partial$configuration/tinycomments_lookup.adoc[leveloffset=+1] -== Optional options +== Optional callback functions -* xref:tinycomments_resolve[`+tinycomments_resolve+`] -* xref:tinycomments_fetch[`+tinycomments_fetch+`] -* xref:tinycomments_fetch_author_info[`+tinycomments_fetch_author_info+`] include::partial$configuration/tinycomments_resolve.adoc[leveloffset=+1] diff --git a/modules/ROOT/partials/commands/comments-cmds.adoc b/modules/ROOT/partials/commands/comments-cmds.adoc index 223a4f229a..a55e511643 100644 --- a/modules/ROOT/partials/commands/comments-cmds.adoc +++ b/modules/ROOT/partials/commands/comments-cmds.adoc @@ -3,6 +3,7 @@ |Command |Description |tc-delete-conversation-at-cursor |Attempts to delete the comment at the current cursor position. A confirmation dialog will be shown prior to deletion. |tc-try-delete-all-conversations |Attempts to delete all comments in the editor. A confirmation dialog will be shown prior to deletion. +|ToggleSidebar |Toggles the comments sidebar open or closed. When used with the 'showcomments' parameter, specifically controls the comments sidebar. |=== .Examples @@ -10,4 +11,5 @@ ---- tinymce.activeEditor.execCommand('tc-delete-conversation-at-cursor'); tinymce.activeEditor.execCommand('tc-try-delete-all-conversations'); +tinymce.activeEditor.execCommand('ToggleSidebar', false, 'showcomments'); ---- diff --git a/modules/ROOT/partials/plugins/comments-open-sidebar.adoc b/modules/ROOT/partials/plugins/comments-open-sidebar.adoc index ce46de407e..04a1dc417c 100644 --- a/modules/ROOT/partials/plugins/comments-open-sidebar.adoc +++ b/modules/ROOT/partials/plugins/comments-open-sidebar.adoc @@ -1,4 +1,4 @@ -== Show the {pluginname} sidebar when {productname} loads +== Show sidebar on editor load The xref:customsidebar.adoc#sidebar_show[`sidebar_show`] option can be used to show the {pluginname} sidebar when the editor is loaded. From 40f1e2af9389ecb60a43ed923269bfff76f527b9 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 15 Sep 2025 14:09:17 +1000 Subject: [PATCH 2/5] Update modules/ROOT/pages/comments-callback-mode.adoc Co-authored-by: Mitchell Crompton --- modules/ROOT/pages/comments-callback-mode.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/comments-callback-mode.adoc b/modules/ROOT/pages/comments-callback-mode.adoc index 61c61ba993..263b8b53cd 100644 --- a/modules/ROOT/pages/comments-callback-mode.adoc +++ b/modules/ROOT/pages/comments-callback-mode.adoc @@ -70,7 +70,7 @@ include::partial$configuration/tinycomments_delete_all.adoc[leveloffset=+1] include::partial$configuration/tinycomments_lookup.adoc[leveloffset=+1] -== Optional callback functions +=== Optional callback functions include::partial$configuration/tinycomments_resolve.adoc[leveloffset=+1] From 98915b6f94dcce6c6c8b5f7f696006c02f8496db Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 15 Sep 2025 14:40:24 +1000 Subject: [PATCH 3/5] Update modules/ROOT/partials/commands/comments-cmds.adoc Co-authored-by: Mitchell Crompton --- modules/ROOT/partials/commands/comments-cmds.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/commands/comments-cmds.adoc b/modules/ROOT/partials/commands/comments-cmds.adoc index a55e511643..179523a719 100644 --- a/modules/ROOT/partials/commands/comments-cmds.adoc +++ b/modules/ROOT/partials/commands/comments-cmds.adoc @@ -3,7 +3,7 @@ |Command |Description |tc-delete-conversation-at-cursor |Attempts to delete the comment at the current cursor position. A confirmation dialog will be shown prior to deletion. |tc-try-delete-all-conversations |Attempts to delete all comments in the editor. A confirmation dialog will be shown prior to deletion. -|ToggleSidebar |Toggles the comments sidebar open or closed. When used with the 'showcomments' parameter, specifically controls the comments sidebar. +|ToggleSidebar |Toggles the specified sidebar open or closed. When used with the 'showcomments' parameter, this opens the comments sidebar. |=== .Examples From ede3164721a628d515f1411fbc5b5e4bd48eba1a Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 15 Sep 2025 19:42:48 +1000 Subject: [PATCH 4/5] DOC-2728: Update tinycomments_reply callback example and demo code. --- modules/ROOT/examples/live-demos/comments-callback/index.js | 6 +++--- modules/ROOT/partials/configuration/tinycomments_reply.adoc | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/examples/live-demos/comments-callback/index.js b/modules/ROOT/examples/live-demos/comments-callback/index.js index 6451b34923..3ae1195041 100644 --- a/modules/ROOT/examples/live-demos/comments-callback/index.js +++ b/modules/ROOT/examples/live-demos/comments-callback/index.js @@ -69,9 +69,9 @@ const tinycomments_create = (req, done, fail) => { }; const tinycomments_reply = (req, done) => { - const replyUid = 'annotation-' + randomString(); + const commentUid = 'annotation-' + randomString(); conversationDb[req.conversationUid].comments.push({ - uid: replyUid, + uid: commentUid, author: user_id, authorName: 'James Wilson', authorAvatar: 'https://sneak-preview.tiny.cloud/demouserdirectory/images/employee_james-wilson_128_52f19412.jpg', @@ -79,7 +79,7 @@ const tinycomments_reply = (req, done) => { createdAt: req.createdAt, modifiedAt: req.createdAt }); - setTimeout(() => done({ commentUid: replyUid }), fakeDelay); + setTimeout(() => done({ commentUid: commentUid }), fakeDelay); }; const tinycomments_delete = (req, done) => { diff --git a/modules/ROOT/partials/configuration/tinycomments_reply.adoc b/modules/ROOT/partials/configuration/tinycomments_reply.adoc index 99d0283433..bd92c1638a 100644 --- a/modules/ROOT/partials/configuration/tinycomments_reply.adoc +++ b/modules/ROOT/partials/configuration/tinycomments_reply.adoc @@ -43,9 +43,9 @@ const reply_comment = (ref, done, fail) => { return response.json(); }) .then((ref2) => { - let commentUid = ref2.commentUid; + const commentUid = ref2.commentUid; done({ - commentUid: replyUid, + commentUid: commentUid, author: currentUser.id, authorName: currentUser.fullName }); From 5d3505777f85f3d0e70d32cfb4083201d9b7a4c6 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 16 Sep 2025 09:06:41 +1000 Subject: [PATCH 5/5] Update modules/ROOT/pages/comments-callback-mode.adoc --- modules/ROOT/pages/comments-callback-mode.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/comments-callback-mode.adoc b/modules/ROOT/pages/comments-callback-mode.adoc index 263b8b53cd..7f76a26891 100644 --- a/modules/ROOT/pages/comments-callback-mode.adoc +++ b/modules/ROOT/pages/comments-callback-mode.adoc @@ -17,7 +17,7 @@ Callback mode provides the most flexibility for integrating with custom backend All callback functions accept three parameters: a request object (or array for `+tinycomments_fetch+`), a `+done+` callback, and a `+fail+` callback. The function return type is not important, but all functions must call exactly one of these two callbacks: `+fail+` or `+done+`. -* The `+fail+` callback takes either a string or a JavaScript Error type to indicate an unrecoverable error. +* The `+fail+` callback takes an argument specific to each function. * The `+done+` callback takes an argument specific to each function to indicate successful completion. Most functions (create, reply, and edit) require an `+id+` identifying the current author. This can be provided directly within the callbacks or dynamically via the `+tinycomments_fetch_author_info+` option.