diff --git a/modules/ROOT/examples/live-demos/comments-callback/example.js b/modules/ROOT/examples/live-demos/comments-callback/example.js index 68e5977e10..824c745418 100644 --- a/modules/ROOT/examples/live-demos/comments-callback/example.js +++ b/modules/ROOT/examples/live-demos/comments-callback/example.js @@ -169,15 +169,47 @@ const tinycomments_lookup = ({ conversationUid }, done, fail) => { }); }; +const tinycomments_fetch = (conversationUids, done, fail) => { + const requests = conversationUids.map((uid) => fetch(`https://api.example/conversations/${uid}`, { + method: 'GET', + headers: { + 'Content-Type': 'application/json', + }}) + .then((response) => response.json()) + .then((data) => ({ + [uid]: { + uid: uid, + comments: data + } + })) + ); + + Promise.all(requests) + .then((data) => { + console.log('data', data); + const conversations = data.reduce((conv, d) => ({ + ...conv, + ...d + }) + , {}); + console.log(`Fetch success ${conversationUids}`, conversations); + done({ conversations }); + }) + .catch((err) => { + console.error(`Fetch failure ${conversationUids}`, err); + fail('Fetching conversations failed'); + }); +}; + tinymce.init({ selector: 'textarea#comments-callback', height: 800, plugins: 'code tinycomments help lists', toolbar: - 'undo redo | blocks | ' + + 'addcomment showcomments | undo redo | blocks | ' + 'bold italic backcolor | alignleft aligncenter ' + 'alignright alignjustify | bullist numlist outdent indent | ' + - 'removeformat | addcomment showcomments | help', + 'removeformat | help', menubar: 'file edit view insert format tc', menu: { tc: { @@ -192,10 +224,6 @@ tinymce.init({ tinycomments_delete_all, tinycomments_delete_comment, tinycomments_lookup, - /* The following setup callback opens the comments sidebar when the editor loads */ - setup: (editor) => { - editor.on('SkinLoaded', () => { - editor.execCommand('ToggleSidebar', false, 'showcomments'); - }); - }, + tinycomments_fetch, + sidebar_show: 'showcomments', }); diff --git a/modules/ROOT/examples/live-demos/comments-callback/index.html b/modules/ROOT/examples/live-demos/comments-callback/index.html index 06a2740b8a..92c933f6e6 100644 --- a/modules/ROOT/examples/live-demos/comments-callback/index.html +++ b/modules/ROOT/examples/live-demos/comments-callback/index.html @@ -7,7 +7,7 @@

Welcome to Tiny Comments!

  • Type your comment into the text field at the bottom of the Comment sidebar.
  • Click Comment.
    • -

    Your comment is then attached to the text, exactly like this!

    +

    Your comment is then attached to the text, exactly like this!

    If you want to take Tiny Comments for a test drive in your own environment, Tiny Comments is one of the premium plugins you can try for free for 14 days by signing up for a Tiny account. Make sure to check out our documentation as well.

    A simple table to play with

    diff --git a/modules/ROOT/examples/live-demos/comments-callback/index.js b/modules/ROOT/examples/live-demos/comments-callback/index.js index 5a5d2e8abd..8f8e3daf05 100644 --- a/modules/ROOT/examples/live-demos/comments-callback/index.js +++ b/modules/ROOT/examples/live-demos/comments-callback/index.js @@ -46,8 +46,47 @@ tinymce.ScriptLoader.loadScripts( }; /* Our server "database" */ - const getDB = () => - JSON.parse(localStorage.getItem('fakedb') ?? '{}'); + const initialDB = { + "mce-conversation_19679600221621399703915": [ + { + uid: "mce-conversation_19679600221621399703915", + author: "Another Tiny User", + authorName: "Another Tiny User", + content: "Please revise this sentence, exclamation points are unprofessional!", + createdAt: "2021-05-19T04:48:23.914Z", + modifiedAt: "2021-05-19T04:48:23.914Z", + }, + { + uid: "mce-conversation_19679600221621399703917", + author: "Another Tiny User", + authorName: "Another Tiny User", + content: "Replied", + createdAt: "2021-05-19T04:48:23.914Z", + modifiedAt: "2021-05-19T04:48:23.914Z", + }, + { + uid: "mce-conversation_19679600221621399703918", + author: "Another Tiny User", + authorName: "Another Tiny User", + content: "Replied again", + createdAt: "2021-05-19T04:48:23.914Z", + modifiedAt: "2021-05-19T04:48:23.914Z", + }, + ], + "mce-conversation_420304606321716900864126": [ + { + uid: "mce-conversation_420304606321716900864126", + author: "john_smith", + authorName: "John Smith", + authorAvatar: "https://i.pravatar.cc/150?img=11", + content: "I think this is a great idea!", + createdAt: "2024-05-28T12:54:24.126Z", + modifiedAt: "2024-05-28T12:54:24.126Z", + }, + ], + }; + + const getDB = () => JSON.parse(localStorage.getItem('fakedb') ?? JSON.stringify(initialDB)); const setDB = (data) => { localStorage.setItem('fakedb', JSON.stringify(data)); }; @@ -621,16 +660,48 @@ tinymce.ScriptLoader.loadScripts( fail(err); }); }; + + const tinycomments_fetch = (conversationUids, done, fail) => { + const requests = conversationUids.map((uid) => fetch(`https://api.example/conversations/${uid}`, { + method: 'GET', + headers: { + 'Content-Type': 'application/json', + }}) + .then((response) => response.json()) + .then((data) => ({ + [uid]: { + uid: uid, + comments: data + } + })) + ); + + Promise.all(requests) + .then((data) => { + console.log('data', data); + const conversations = data.reduce((conv, d) => ({ + ...conv, + ...d + }) + , {}); + console.log(`Fetch success ${conversationUids}`, conversations); + done({ conversations }); + }) + .catch((err) => { + console.error(`Fetch failure ${conversationUids}`, err); + fail('Fetching conversations failed'); + }); + }; tinymce.init({ selector: 'textarea#comments-callback', height: 800, plugins: 'code tinycomments help lists', toolbar: - 'undo redo | blocks | ' + + 'addcomment showcomments | undo redo | blocks | ' + 'bold italic backcolor | alignleft aligncenter ' + 'alignright alignjustify | bullist numlist outdent indent | ' + - 'removeformat | addcomment showcomments | help', + 'removeformat | help', menubar: 'file edit view insert format tc', menu: { tc: { @@ -645,13 +716,7 @@ tinymce.ScriptLoader.loadScripts( tinycomments_delete_all, tinycomments_delete_comment, tinycomments_lookup, - /* The following setup callback opens the comments sidebar when the editor loads */ - setup: (editor) => { - editor.on('SkinLoaded', () => { - editor.execCommand('ToggleSidebar', false, 'showcomments', { - skip_focus: true, - }); - }); - }, + tinycomments_fetch, + sidebar_show: 'showcomments', }); }); diff --git a/modules/ROOT/examples/live-demos/comments-embedded/index.js b/modules/ROOT/examples/live-demos/comments-embedded/index.js index 13517fd03f..e09fbb2121 100644 --- a/modules/ROOT/examples/live-demos/comments-embedded/index.js +++ b/modules/ROOT/examples/live-demos/comments-embedded/index.js @@ -4,7 +4,7 @@ const userAllowedToResolve = 'Admin1'; tinymce.init({ selector: 'textarea#comments-embedded', plugins: 'code tinycomments', - toolbar: 'bold italic underline | addcomment showcomments', + toolbar: 'addcomment showcomments | bold italic underline', menubar: 'file edit view insert format tools tc', menu: { tc: { @@ -22,10 +22,4 @@ tinymce.init({ }); }, content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }', - /* The following setup callback opens the comments sidebar when the editor loads */ - setup: (editor) => { - editor.on('SkinLoaded', () => { - editor.execCommand('ToggleSidebar', false, 'showcomments', { skip_focus: true }); - }); - } }); diff --git a/modules/ROOT/examples/live-demos/comments-readonly-mode/index.html b/modules/ROOT/examples/live-demos/comments-readonly-mode/index.html new file mode 100644 index 0000000000..fe676301b3 --- /dev/null +++ b/modules/ROOT/examples/live-demos/comments-readonly-mode/index.html @@ -0,0 +1,36 @@ +
    + +
    \ No newline at end of file diff --git a/modules/ROOT/examples/live-demos/comments-readonly-mode/index.js b/modules/ROOT/examples/live-demos/comments-readonly-mode/index.js new file mode 100644 index 0000000000..22cbbbaa73 --- /dev/null +++ b/modules/ROOT/examples/live-demos/comments-readonly-mode/index.js @@ -0,0 +1,26 @@ +tinymce.init({ + selector: "textarea#comment-readonly-ui-mode", + plugins: [ + "tinycomments", "advlist", "anchor", "autolink", "charmap", "code", "fullscreen", + "help", "image", "insertdatetime", "link", "lists", "media", + "preview", "searchreplace", "table", "visualblocks", + ], + toolbar: "addcomment showcomments togglereadonly | undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image", + tinycomments_mode: 'embedded', + readonly: true, + setup: (editor) => { + const isReadonlyMode = () => editor.mode.get() === 'readonly'; + editor.ui.registry.addToggleButton('togglereadonly', { + text: 'Readonly mode', + context: 'any', // Available from 7.4 + onSetup: (buttonApi) => { + const activate = (api) => () => api.setActive(isReadonlyMode()); + editor.on('SwitchMode', activate(buttonApi)); + return (teardownApi) => editor.off('SwitchMode', activate(teardownApi)); + }, + onAction: (api) => { + editor.mode.set(isReadonlyMode() ? 'design' : 'readonly'); + } + }); + } +}); \ No newline at end of file diff --git a/modules/ROOT/examples/live-demos/comments-ui-mode/index.html b/modules/ROOT/examples/live-demos/comments-ui-mode/index.html new file mode 100644 index 0000000000..4c34ab043b --- /dev/null +++ b/modules/ROOT/examples/live-demos/comments-ui-mode/index.html @@ -0,0 +1,38 @@ +
    + +
    \ No newline at end of file diff --git a/modules/ROOT/examples/live-demos/comments-ui-mode/index.js b/modules/ROOT/examples/live-demos/comments-ui-mode/index.js new file mode 100644 index 0000000000..5224935f09 --- /dev/null +++ b/modules/ROOT/examples/live-demos/comments-ui-mode/index.js @@ -0,0 +1,11 @@ +tinymce.init({ + selector: "textarea#comments-ui-mode", + plugins: [ + "tinycomments", "advlist", "anchor", "autolink", "charmap", "code", "fullscreen", + "help", "image", "insertdatetime", "link", "lists", "media", + "preview", "searchreplace", "table", "visualblocks", + ], + toolbar: "addcomment showcomments | undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image", + tinycomments_mode: 'embedded', + tinycomments_access: 'comment' +}); \ No newline at end of file diff --git a/modules/ROOT/images/comment-add-comment.png b/modules/ROOT/images/comment-add-comment.png new file mode 100644 index 0000000000..23bbd04bd2 Binary files /dev/null and b/modules/ROOT/images/comment-add-comment.png differ diff --git a/modules/ROOT/images/comment-comment-created.png b/modules/ROOT/images/comment-comment-created.png new file mode 100644 index 0000000000..fb5bc11442 Binary files /dev/null and b/modules/ROOT/images/comment-comment-created.png differ diff --git a/modules/ROOT/images/comment-delete-all-conversations-file-menu.png b/modules/ROOT/images/comment-delete-all-conversations-file-menu.png new file mode 100644 index 0000000000..8f50ca819c Binary files /dev/null and b/modules/ROOT/images/comment-delete-all-conversations-file-menu.png differ diff --git a/modules/ROOT/images/comment-delete-all-conversations.png b/modules/ROOT/images/comment-delete-all-conversations.png new file mode 100644 index 0000000000..c8a7fa461d Binary files /dev/null and b/modules/ROOT/images/comment-delete-all-conversations.png differ diff --git a/modules/ROOT/images/comment-delete-comment-dialog.png b/modules/ROOT/images/comment-delete-comment-dialog.png new file mode 100644 index 0000000000..ad00c9f5de Binary files /dev/null and b/modules/ROOT/images/comment-delete-comment-dialog.png differ diff --git a/modules/ROOT/images/comment-delete-comment.png b/modules/ROOT/images/comment-delete-comment.png new file mode 100644 index 0000000000..fc1bebfca9 Binary files /dev/null and b/modules/ROOT/images/comment-delete-comment.png differ diff --git a/modules/ROOT/images/comment-delete-conversation-dialog.png b/modules/ROOT/images/comment-delete-conversation-dialog.png new file mode 100644 index 0000000000..e1ccddab1d Binary files /dev/null and b/modules/ROOT/images/comment-delete-conversation-dialog.png differ diff --git a/modules/ROOT/images/comment-delete-conversation.png b/modules/ROOT/images/comment-delete-conversation.png new file mode 100644 index 0000000000..63742fe952 Binary files /dev/null and b/modules/ROOT/images/comment-delete-conversation.png differ diff --git a/modules/ROOT/images/comment-edit-comment.png b/modules/ROOT/images/comment-edit-comment.png new file mode 100644 index 0000000000..41fb3542b4 Binary files /dev/null and b/modules/ROOT/images/comment-edit-comment.png differ diff --git a/modules/ROOT/images/comment-edit-existing-comment-ellipsis.png b/modules/ROOT/images/comment-edit-existing-comment-ellipsis.png new file mode 100644 index 0000000000..c9a31f34c8 Binary files /dev/null and b/modules/ROOT/images/comment-edit-existing-comment-ellipsis.png differ diff --git a/modules/ROOT/images/comment-edited-comment.png b/modules/ROOT/images/comment-edited-comment.png new file mode 100644 index 0000000000..a64709d2ad Binary files /dev/null and b/modules/ROOT/images/comment-edited-comment.png differ diff --git a/modules/ROOT/images/comment-reply-add-comment-focus.png b/modules/ROOT/images/comment-reply-add-comment-focus.png new file mode 100644 index 0000000000..ce04a5da0f Binary files /dev/null and b/modules/ROOT/images/comment-reply-add-comment-focus.png differ diff --git a/modules/ROOT/images/comment-reply-add-comment-pre-submit.png b/modules/ROOT/images/comment-reply-add-comment-pre-submit.png new file mode 100644 index 0000000000..97c238c719 Binary files /dev/null and b/modules/ROOT/images/comment-reply-add-comment-pre-submit.png differ diff --git a/modules/ROOT/images/comment-reply-add-comment-textarea.png b/modules/ROOT/images/comment-reply-add-comment-textarea.png new file mode 100644 index 0000000000..c31b30af2a Binary files /dev/null and b/modules/ROOT/images/comment-reply-add-comment-textarea.png differ diff --git a/modules/ROOT/images/comment-reply-add-comment.png b/modules/ROOT/images/comment-reply-add-comment.png new file mode 100644 index 0000000000..1294681363 Binary files /dev/null and b/modules/ROOT/images/comment-reply-add-comment.png differ diff --git a/modules/ROOT/images/comment-reply-to-comment-done.png b/modules/ROOT/images/comment-reply-to-comment-done.png new file mode 100644 index 0000000000..28d620ab95 Binary files /dev/null and b/modules/ROOT/images/comment-reply-to-comment-done.png differ diff --git a/modules/ROOT/images/comment-reply-to-comment-submitted.png b/modules/ROOT/images/comment-reply-to-comment-submitted.png new file mode 100644 index 0000000000..c38f55bed3 Binary files /dev/null and b/modules/ROOT/images/comment-reply-to-comment-submitted.png differ diff --git a/modules/ROOT/images/comment-resolve-conversation.png b/modules/ROOT/images/comment-resolve-conversation.png new file mode 100644 index 0000000000..3699408b8d Binary files /dev/null and b/modules/ROOT/images/comment-resolve-conversation.png differ diff --git a/modules/ROOT/images/comments-delete-comment.png b/modules/ROOT/images/comments-delete-comment.png deleted file mode 100644 index 243325fed1..0000000000 Binary files a/modules/ROOT/images/comments-delete-comment.png and /dev/null differ diff --git a/modules/ROOT/images/comments-delete-conversation.png b/modules/ROOT/images/comments-delete-conversation.png deleted file mode 100644 index 2cd3852de8..0000000000 Binary files a/modules/ROOT/images/comments-delete-conversation.png and /dev/null differ diff --git a/modules/ROOT/images/comments-delete-conversations.png b/modules/ROOT/images/comments-delete-conversations.png deleted file mode 100644 index e94d805b00..0000000000 Binary files a/modules/ROOT/images/comments-delete-conversations.png and /dev/null differ diff --git a/modules/ROOT/images/comments-edit.png b/modules/ROOT/images/comments-edit.png deleted file mode 100644 index 88bd128299..0000000000 Binary files a/modules/ROOT/images/comments-edit.png and /dev/null differ diff --git a/modules/ROOT/images/comments-resolve-conversation.png b/modules/ROOT/images/comments-resolve-conversation.png deleted file mode 100644 index 04ba2be992..0000000000 Binary files a/modules/ROOT/images/comments-resolve-conversation.png and /dev/null differ diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 305b3b4607..6b5747561b 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -303,6 +303,7 @@ **** xref:comments-callback-mode.adoc[Callback mode] **** xref:comments-embedded-mode.adoc[Embedded mode] **** xref:comments-toolbars-menus.adoc[Toolbar buttons and menu items] +**** xref:comments-access-options.adoc[Access Options] **** xref:comments-commands-events-apis.adoc[Commands, Events and APIs] *** xref:advcode.adoc[Enhanced Code Editor] *** Enhanced Media Embed diff --git a/modules/ROOT/pages/comments-access-options.adoc b/modules/ROOT/pages/comments-access-options.adoc new file mode 100644 index 0000000000..b9af24548e --- /dev/null +++ b/modules/ROOT/pages/comments-access-options.adoc @@ -0,0 +1,13 @@ +:navtitle: Comments Access Options +:description: TinyMCE Comments plugin access options. +:keywords: comments, commenting, tinycomments, access options +:pluginname: Comments +:plugincode: comments +:pluginminimumplan: enterprise + +[[access-options]] +== Access Options + +The following configuration option affects the behavior of the {pluginname} plugin. + +include::partial$configuration/comments-tinycomments_access.adoc[leveloffset=+1] diff --git a/modules/ROOT/pages/comments-callback-mode.adoc b/modules/ROOT/pages/comments-callback-mode.adoc index 0b6e342277..7478c5398f 100644 --- a/modules/ROOT/pages/comments-callback-mode.adoc +++ b/modules/ROOT/pages/comments-callback-mode.adoc @@ -1,4 +1,4 @@ -= Configuring the Comments plugin in callback mode += Configuring the {pluginname} plugin in callback mode :navtitle: Callback mode :description: Information on configuring the Comments plugin in callback mode :keywords: comments, commenting, tinycomments, callback @@ -6,32 +6,35 @@ :plugincode: comments :commentsMode: callback -*Callback mode* is the default mode for the Comments plugin. In the callback mode, callback functions are required to save user comments on a server. The Comments functions (create, reply, edit, delete comment, delete all conversations, resolve, and lookup) are configured differently depending upon the server-side storage configuration. +*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. -== Interactive example - -The following example uses a simulated server (provided by https://netflix.github.io/pollyjs/[Polly.js]) which has been hidden from the example javascript to keep the example code concise. The interactions between TinyMCE and Polly.js are visible in the browser console. - -liveDemo::comments-callback[] - -=== How the comments plugin works in callback mode +== 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+`. * The `+fail+` callback takes either a string or a JavaScript Error type. * The `+done+` callback takes an argument specific to each function. -Most (create, reply, and edit) functions require an `+id+` identifying the *current author*. +Most functions (create, reply, and edit) require an `+id+` identifying the *current author*. -Current author:: The Comments plugin does not know the name of the current user. Determining the current user and storing the comment related to that user, has to be configured by the developer. +[NOTE] +**Current author**: The {pluginname} plugin does not know the name of the current user. Determining the current user and storing the comment related to that user is required to be configured by the integrator. -After a user comments (triggering `+tinycomments_create+` for the first comment, or `+tinycomments_reply+` for subsequent comments), the Comments plugin requests the updated conversation using `+tinycomments_lookup+`, which should now contain the additional comment with the proper author. +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+`. + +When a user adds a comment or a reply, the {pluginname} plugin uses the `+tinycomments_lookup+` callback to retrieve the selected conversation. + +== Interactive example + +The following example uses a simulated server (provided by link:https://netflix.github.io/pollyjs/[Polly.js]), which has been hidden from the example JavaScript to keep the example code concise. The interactions between {productname} and Polly.js are visible in the browser console. + +liveDemo::comments-callback[] == Options === Required options -When using callback mode, the Comments plugin requires callback functions for the following options: +When using callback mode, the {pluginname} plugin requires callback functions for the following options: * xref:tinycomments_create[`+tinycomments_create+`] * xref:tinycomments_reply[`+tinycomments_reply+`] @@ -41,16 +44,12 @@ When using callback mode, the Comments plugin requires callback functions for th * xref:tinycomments_delete_all[`+tinycomments_delete_all+`] * xref:tinycomments_lookup[`+tinycomments_lookup+`] -The xref:tinycomments_resolve[`+tinycomments_resolve+`] option is _optional_. - include::partial$configuration/tinycomments_create.adoc[leveloffset=+1] include::partial$configuration/tinycomments_reply.adoc[leveloffset=+1] include::partial$configuration/tinycomments_edit_comment.adoc[leveloffset=+1] -include::partial$configuration/tinycomments_resolve.adoc[leveloffset=+1] - include::partial$configuration/tinycomments_delete_comment.adoc[leveloffset=+1] include::partial$configuration/tinycomments_delete.adoc[leveloffset=+1] @@ -59,6 +58,15 @@ include::partial$configuration/tinycomments_delete_all.adoc[leveloffset=+1] include::partial$configuration/tinycomments_lookup.adoc[leveloffset=+1] +== Optional options + +* xref:tinycomments_resolve[`+tinycomments_resolve+`] +* xref:tinycomments_fetch[`+tinycomments_fetch+`] + +include::partial$configuration/tinycomments_resolve.adoc[leveloffset=+1] + +include::partial$configuration/tinycomments_fetch.adoc[leveloffset=+1] + include::partial$plugins/comments-open-sidebar.adoc[] include::partial$plugins/comments-highlighting-css.adoc[] diff --git a/modules/ROOT/pages/comments-commands-events-apis.adoc b/modules/ROOT/pages/comments-commands-events-apis.adoc index 89b8e3b3f7..6ff3f9f24f 100644 --- a/modules/ROOT/pages/comments-commands-events-apis.adoc +++ b/modules/ROOT/pages/comments-commands-events-apis.adoc @@ -1,4 +1,4 @@ -= Commands, Events and APIs for the comments plugin += Commands, Events and APIs for the {pluginname} plugin :navtitle: Commands, Events and APIs :description: Information on the commands, events and APIs provided with the comments plugin. :keywords: comments, commenting, tinycomments @@ -7,7 +7,7 @@ == Commands -The Comments plugin provides the following {productname} commands. +The {pluginname} plugin provides the following {productname} commands. include::partial$commands/comments-cmds.adoc[] @@ -46,13 +46,104 @@ The {pluginname} plugin provides the xref:comments-commands-events-apis#getEvent include::partial$misc/admon-requires-6.1v.adoc[] -Returns a log with information and timestamps of all changes to comments, including when: +The `getEventLog` returns a log that contains information and timestamps of all changes to comments, including when: -* A new comment is added (and who added it). -* A comment is edited (and who edited it). -* A reply to a comment is added (and who added the reply). -* A comment is resolved (and who resolved the comment). -* A comment is deleted (and who deleted the comment). +* A new comment is added. + +[source,js] +---- +{ + "type": "create", + "timestamp": "2024-10-01T03:07:53.771Z", + "conversationUid": "annotation-r1nn5xdo5ye", + "conversationContext": "Welcome", + "conversationContent": "new comment" +}, +---- + +* A comment is edited. + +[source,js] +---- +{ + "type": "edit-comment", + "timestamp": "2024-10-01T03:08:06.551Z", + "conversationUid": "annotation-r1nn5xdo5ye", + "commentUid": "annotation-r1nn5xdo5ye", + "conversationContext": "Welcome", + "conversationContent": "new comment", + "conversationCreatedAt": "2024-10-01T03:07:53.771Z", + "commentContent": "new comment (Edit comment)", + "commentAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + }, + "conversationAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + } +}, +---- + +* A reply to a comment is added. + +[source,js] +---- +{ + "type": "reply", + "timestamp": "2024-10-01T03:07:53.771Z", + "conversationUid": "annotation-r1nn5xdo5ye", + "commentUid": "annotation-uh00rb41kma", + "conversationContext": "Welcome", + "conversationContent": "new comment (Edit comment)", + "conversationCreatedAt": "2024-10-01T03:07:53.771Z", + "commentContent": "reply to existing comment", + "conversationAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + } +}, +---- + +* A comment is resolved. + +[source,js] +---- +{ + "type": "resolve", + "timestamp": "2024-10-01T03:08:25.783Z", + "conversationUid": "annotation-r1nn5xdo5ye", + "conversationContext": "Welcome", + "conversationContent": "new comment (Edit comment)", + "conversationAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + } +}, +---- + +* A comment is deleted. + +[source,js] +---- +{ + "type": "delete-comment", + "timestamp": "2024-10-01T03:08:23.292Z", + "conversationUid": "annotation-r1nn5xdo5ye", + "commentUid": "annotation-uh00rb41kma", + "conversationContext": "Welcome", + "conversationContent": "new comment (Edit comment)", + "commentContent": "reply to existing comment", + "commentAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + }, + "conversationAuthor": { + "author": "DEMO USER", + "authorName": "DEMO USER" + } +}, +---- The event log can be retrieved either in full or with the `after` option, which restricts the returned list to Comment events after a time-stamp date in the link:https://en.wikipedia.org/wiki/ISO_8601[ISO-8601] format, both shown in the following: @@ -81,7 +172,7 @@ The `+'tinycomments'+` annotator, like all editor APIs, can only be accessed aft This example makes use of the `+annotationChanged+` method in the `+editor.annotator+` API to create a xref:creating-custom-notifications.adoc[custom notification]. -This notification displays for five seconds every time any content with a `+'tinycomments'+` annotation is selected. +The below notification example displays for five seconds every time any content with a `+'tinycomments'+` annotation is selected. [source,js] ---- diff --git a/modules/ROOT/pages/comments-embedded-mode.adoc b/modules/ROOT/pages/comments-embedded-mode.adoc index af3fb39179..f5fb056bca 100644 --- a/modules/ROOT/pages/comments-embedded-mode.adoc +++ b/modules/ROOT/pages/comments-embedded-mode.adoc @@ -1,26 +1,27 @@ -= Configuring the Comments plugin in embedded mode += Configuring the {pluginname} plugin in embedded mode :navtitle: Embedded mode :description: Information on configuring the Comments plugin in embedded mode :keywords: comments, commenting, tinycomments, embedded, embedded mode :pluginname: Comments :plugincode: comments -== Add the Comments plugin in embedded mode +== Add the {pluginname} plugin in embedded mode -To add the Comments plugin in embedded mode to the {productname}, configure the following options: +To add the {pluginname} plugin in embedded mode to the {productname}, configure the following options: [source,js] ---- tinymce.init({ selector: 'textarea', // change this value according to your html plugins: 'tinycomments', + toolbar: 'addcomment showcomments', tinycomments_author: 'author', tinycomments_author_name: 'Name of the commenter', tinycomments_mode: 'embedded' }); ---- -This is the minimum recommended setup for the Comments plugin in embedded mode. If the `+tinycomments_author+` and `+tinycomments_author_name+` options are not configured, all users will be assigned the name "_ANON_". +This is the minimum recommended setup for the {pluginname} plugin in embedded mode. If the `+tinycomments_author+` and `+tinycomments_author_name+` options are not configured, all users will be assigned the name "_ANON_". == Interactive example @@ -44,4 +45,4 @@ include::partial$configuration/tinycomments_can_edit_comment.adoc[leveloffset=+1 include::partial$plugins/comments-open-sidebar.adoc[] -include::partial$plugins/comments-highlighting-css.adoc[] +include::partial$plugins/comments-highlighting-css.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/comments-toolbars-menus.adoc b/modules/ROOT/pages/comments-toolbars-menus.adoc index ce82e328a8..4d3e9d803b 100644 --- a/modules/ROOT/pages/comments-toolbars-menus.adoc +++ b/modules/ROOT/pages/comments-toolbars-menus.adoc @@ -1,4 +1,4 @@ -= Toolbar buttons and menu items for the Comments plugin += Toolbar buttons and menu items for the {pluginname} plugin :navtitle: Toolbar buttons and menu items :description: Details of the toolbar buttons and menu items provided for the Comments plugin. :keywords: comments, commenting, tinycomments diff --git a/modules/ROOT/pages/comments-using-comments.adoc b/modules/ROOT/pages/comments-using-comments.adoc index 41e322084e..4fe65b2582 100644 --- a/modules/ROOT/pages/comments-using-comments.adoc +++ b/modules/ROOT/pages/comments-using-comments.adoc @@ -1,34 +1,68 @@ -= Using TinyMCE Comments += Using {productname} {pluginname} :navtitle: Using Comments -:description: How to add, edit, resolve, and remove comments in TinyMCE +:description: How to add, edit, resolve, and remove comments in {productname} :keywords: comments, commenting, tinycomments :pluginname: Comments :plugincode: comments -I'm trying to: +== Overview -* xref:add-a-comment[Add a comment]. -* xref:edit-a-comment[Edit a comment]. -* xref:delete-a-comment[Delete a comment]. -* xref:delete-a-comment-thread-conversation[Delete a comment thread (conversation)]. -* xref:resolve-a-comment-thread-conversation[Resolve a comment thread (conversation)]. -* xref:show-or-view-a-comment[Show or view a comment]. -* xref:delete-all-comment-threads[Delete all comment threads]. +This guide provides visual instructions for using the comments plugin, including how to: + +* xref:add-a-comment[add new comments] to selected content +* xref:replying-to-comments[replying to comments] +* xref:edit-a-comment[edit existing comments] +* xref:delete-a-comment[delete individual comments] +* xref:delete-a-comment-thread-conversation[delete entire conversations] +* xref:resolve-a-comment-thread-conversation[resolving conversations] +* xref:show-or-view-a-comment[viewing comments] using the sidebar +* xref:delete-all-comment-threads[deleting all conversations] in a document + +[TIP] +The editor must contain content before a comment can be added. [[add-a-comment]] == Add a comment . Select the content from the desired location in the editor body. -. From the navigation menu, choose *Insert*-> *Add Comment* or click on the *Add comment* image:icons/comment-add.svg[Add comment] toolbar button to add the comment. -. The Comment box appears in the sidebar of the editor instance. -. Type a comment in the comment box, the "_Add comment…_" placeholder text will disappear. -. Press *Clear* to discard or *Comment* to store the input comment. +.. From the menubar, toggle *Insert* -> *Add comment*, or +.. click on the *Add comment* image:icons/comment-add.svg[Add comment] toolbar button, or +.. press `Ctrl+Alt+M` (Windows/Linux) or `Cmd+Option+M` `+⌥ + ⌘ + M+` (Mac) to add a comment. +. The {pluginname} sidebar will appear on the right side of the editor instance. +. The `+