Skip to content

Commit 7791c9a

Browse files
author
Sorita Heng
committed
Update explanation of plugin and add UID options
1 parent 584785f commit 7791c9a

File tree

7 files changed

+161
-103
lines changed

7 files changed

+161
-103
lines changed

‎modules/ROOT/pages/suggestededits.adoc‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,14 @@ include::partial$misc/admon-iframe-only.adoc[]
2121

2222
== How it works
2323

24-
The Suggested Edits plugin monitors edits made to a document by comparing its current state to the original version. Each change is attributed to its respective author and can be approved or rejected before being applied to the document.
24+
The Suggested Edits plugin builds a document model of the editor content to track edits made by multiple authors. This model is used to compare the current content of the editor with the original version, highlighting changes such as insertions, modifications, and deletions.
2525

26-
The plugin includes a dedicated view for reviewing current changes, accessible via the `{plugincode}` toolbar button or the menu option under the `View` menu. The key components are:
26+
This allows users to review the changes made to the document, provide feedback on them, and accept or reject them as needed. See xref:#suggestededits_access[`suggestededits_access`] option for more information on how to configure user permissions for editing and reviewing content.
27+
28+
[NOTE]
29+
The model's content should be considered as metadata of the editor's HTML content, and both should be saved together to ensure correctness. See xref:#suggestededits_content[`suggestededits_content`] for more information on how to configure the source of content loaded into the editor.
30+
31+
A dedicated read-only view is provided for reviewing current changes, accessible via the `{plugincode}` toolbar button or the menu option under the `View` menu. The key components are:
2732

2833
. **Read-only Diff View**:
2934
+
@@ -47,7 +52,21 @@ The sidebar also displays all tracked changes that need to be resolved. Each cha
4752
* Reject: Removes the change from the document.
4853
* Revert: Undoes a previously accepted or rejected change.
4954

50-
The plugin also enables users to view and provide suggestions to edits. All users with access to the {pluginname} View can view suggestions. To allow users to provide suggestions, xref:{plugincode}_access[`{plugincode}_access`] must be set to either `admin` or `suggest`.
55+
== Types of suggestions
56+
57+
There are four basic types of suggestions that are tracked by the Suggested Edits plugin:
58+
59+
==== Insert
60+
Tracks the addition of new content to the document.
61+
62+
==== Modify
63+
Tracks HTML attribute changes or formatting changes to existing content, such as bold or italic text. Note that if multiple users modify the same content, the original author will still be attributed with the change.
64+
65+
==== Delete
66+
Tracks the removal of content from the document.
67+
68+
==== Replace
69+
Tracks the replacement of existing content with new content. This is treated as a combination of a delete and an insert, where the original content is selected and replaced by new content. Note that if multiple users replace the same content, the most recent author will be attributed with the change.
5170

5271
== Initial setup
5372

‎modules/ROOT/partials/configuration/suggestededits-options.adoc‎

Lines changed: 5 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,5 @@
1-
[[suggestededits_model]]
2-
== `suggestededits_model`
3-
4-
The `{plugincode}_model` option sets the initial model of the document to begin tracking changes. It takes as input an object representing the document, containing all edits made to the document up to that point. This model should be saved externally alongside the document, and loaded into the editor each time the document is opened. This will ensure that both the document and the model are in sync, and that the plugin can track edits correctly.
5-
6-
If the model is not provided in the editor configuration, the plugin will create a new model from the current content of the editor. This model can be retrieved from the editor at any time using the xref:#get_model[`getModel` API].
7-
//*Type:* xref:#trackeddocument[TrackedDocument] `+Object+`
8-
9-
=== Example: using `{plugincode}_model`
10-
11-
// Add a working and tested configuration.
12-
[source,js]
13-
----
14-
tinymce.init({
15-
selector: 'textarea', // Change this value according to your HTML
16-
plugins: 'suggestededits',
17-
toolbar: 'suggestededits',
18-
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
19-
suggestededits_model // Model representing the document with up to date edits
20-
});
21-
----
22-
23-
[[suggestededits_access]]
24-
== `suggestededits_access`
25-
26-
To configure a user's permission to edit the document and review changes, the `{plugincode}_access` option can be set alongside the editor mode.
27-
28-
*Type:* `+String+`
29-
30-
*Possible Values*: `'full'`, `'suggest'`, `'read'`, `'none'`
31-
32-
*Default Value*: `'full'`
33-
34-
The possible values set the access level of the review permissions as follows:
35-
36-
[cols="20%,80%"]
37-
|===
38-
|Value | Review Permission
39-
40-
|`+'full'+`
41-
|Access to the {pluginname} view, with permission to accept, reject, or add suggestions to changes.
42-
43-
|`+'suggest'+`
44-
|Access to the {pluginname} view, with permission to add suggestions to changes.
45-
46-
|`+'read'+`
47-
|Readonly access to the {pluginname} view.
48-
49-
|`+'none'+`
50-
|No access to the {pluginname} view.
51-
|===
52-
53-
[NOTE]
54-
The `{plugincode}_access` option can be used in combination with the editor's read-only mode to restrict a user’s editing permission.
55-
56-
.Example
57-
[source,javascript]
58-
----
59-
tinymce.init({
60-
selector: 'textarea', // Change this value according to your HTML
61-
plugins: 'suggestededits',
62-
toolbar: 'suggestededits',
63-
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
64-
suggestededits_access: 'full' //change this value to set permission to the Suggested Edits view
65-
readonly: false //set to true to restrict a user's editing permission
66-
});
67-
----
68-
69-
liveDemo::suggestededits-access[]
70-
71-
[[suggestededits_content]]
72-
== `suggestededits_content`
73-
The `{plugincode}_content` option determines where the initial content of the document is loaded from. With this option, you can set the content to be loaded from either the editor or the model, allowing you to control the source of truth for the document.
74-
75-
When set to `'html'`, the editor loads the initial content from the HTML in the textarea or the `content` property. In this case, if a model is provided, it will need to match the content in the editor for the plugin to work correctly
76-
77-
When set to `'model'`, the editor loads the initial content from the `{plugincode}_model` option. In this case, the content in the editor will be overwritten with the content from the model. This would allow you to only require the model for document tracking, though it is still recommended to save the content in the editor externally.
78-
79-
In either case, if a model is not provided, the plugin will generate a new model from the current content of the editor, whether it is empty or not.
80-
81-
*Type:* `+String+`
82-
83-
*Possible Values*: `'html'`, `'model'`
84-
85-
*Default value:* `'html'`
86-
87-
=== Example: using `{plugincode}_content`
88-
89-
// Add a working and tested configuration.
90-
[source,js]
91-
----
92-
tinymce.init({
93-
selector: 'textarea', // Change this value according to your HTML
94-
plugins: 'suggestededits',
95-
toolbar: 'suggestededits',
96-
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
97-
suggestededits_model,
98-
suggestededits_content: 'model' // change this value to set the content source
99-
});
100-
----
1+
include::partial$configuration/userlookup_userid.adoc[]
2+
include::partial$configuration/userlookup_fetch.adoc[]
3+
include::partial$configuration/suggestededits_model.adoc[]
4+
include::partial$configuration/suggestededits_content.adoc[]
5+
include::partial$configuration/suggestededits_access.adoc[]

‎modules/ROOT/partials/configuration/suggestededits_access.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
[[suggestededits_access]]
2+
== `suggestededits_access`
3+
4+
To configure a user's permission to edit the document and review changes, the `{plugincode}_access` option can be set alongside the editor mode.
5+
6+
*Type:* `+String+`
7+
8+
*Possible Values*: `'full'`, `'suggest'`, `'read'`, `'none'`
9+
10+
*Default Value*: `'full'`
11+
12+
The possible values set the access level of the review permissions as follows:
13+
14+
[cols="20%,80%"]
15+
|===
16+
|Value | Review Permission
17+
18+
|`+'full'+`
19+
|Access to the {pluginname} view, with permission to accept, reject, or add suggestions to changes.
20+
21+
|`+'suggest'+`
22+
|Access to the {pluginname} view, with permission to add suggestions to changes.
23+
24+
|`+'read'+`
25+
|Readonly access to the {pluginname} view.
26+
27+
|`+'none'+`
28+
|No access to the {pluginname} view.
29+
|===
30+
31+
[NOTE]
32+
The `{plugincode}_access` option can be used in combination with the editor's read-only mode to restrict a user’s editing permission.
33+
34+
.Example
35+
[source,javascript]
36+
----
37+
tinymce.init({
38+
selector: 'textarea', // Change this value according to your HTML
39+
plugins: 'suggestededits',
40+
toolbar: 'suggestededits',
41+
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
42+
suggestededits_access: 'full' //change this value to set permission to the Suggested Edits view
43+
readonly: false //set to true to restrict a user's editing permission
44+
});
45+
----
46+
47+
liveDemo::suggestededits-access[]

‎modules/ROOT/partials/configuration/suggestededits_content.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[[suggestededits_content]]
2+
== `suggestededits_content`
3+
The `{plugincode}_content` option determines where the initial content of the document is loaded from. With this option, you can set the content to be loaded from either the editor or the model, allowing you to control the source of truth for the document.
4+
5+
When set to `'html'`, the editor loads the initial content from the HTML in the textarea or the `content` property. In this case, if a model is provided, it will need to match the content in the editor for the plugin to work correctly
6+
7+
When set to `'model'`, the editor loads the initial content from the `{plugincode}_model` option. In this case, the content in the editor will be overwritten with the content from the model. This would allow you to only require the model for document tracking, though it is still recommended to save the content in the editor externally.
8+
9+
In either case, if a model is not provided, the plugin will generate a new model from the current content of the editor, whether it is empty or not.
10+
11+
*Type:* `+String+`
12+
13+
*Possible Values*: `'html'`, `'model'`
14+
15+
*Default value:* `'html'`
16+
17+
=== Example: using `{plugincode}_content`
18+
19+
// Add a working and tested configuration.
20+
[source,js]
21+
----
22+
tinymce.init({
23+
selector: 'textarea', // Change this value according to your HTML
24+
plugins: 'suggestededits',
25+
toolbar: 'suggestededits',
26+
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
27+
suggestededits_model,
28+
suggestededits_content: 'model' // change this value to set the content source
29+
});
30+
----

‎modules/ROOT/partials/configuration/suggestededits_model.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[[suggestededits_model]]
2+
== `suggestededits_model`
3+
4+
The `{plugincode}_model` option sets the initial model of the document to begin tracking changes. It takes as input an object representing the document, containing all edits made to the document up to that point. This model should be saved externally alongside the document, and loaded into the editor each time the document is opened. This will ensure that both the document and the model are in sync, and that the plugin can track edits correctly.
5+
6+
If the model is not provided in the editor configuration, the plugin will create a new model from the current content of the editor. This model can be retrieved from the editor at any time using the xref:#get_model[`getModel` API].
7+
//*Type:* xref:#trackeddocument[TrackedDocument] `+Object+`
8+
9+
=== Example: using `{plugincode}_model`
10+
11+
// Add a working and tested configuration.
12+
[source,js]
13+
----
14+
tinymce.init({
15+
selector: 'textarea', // Change this value according to your HTML
16+
plugins: 'suggestededits',
17+
toolbar: 'suggestededits',
18+
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
19+
suggestededits_model // Model representing the document with up to date edits
20+
});
21+
----

‎modules/ROOT/partials/configuration/userlookup_fetch.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[[userlookup_fetch]]
2+
== `userlookup_fetch`
3+
4+
Required option to fetch a list of user IDs to display in the Suggested Edits view. This option uses the xref:#userlookupapi[`UserLookup API`].
5+
6+
*Type:* `+Array+`
7+
8+
.Example
9+
[source,javascript]
10+
----
11+
tinymce.init({
12+
selector: 'textarea', // Change this value according to your HTML
13+
plugins: 'suggestededits',
14+
toolbar: 'suggestededits',
15+
userlookup_userid: 'unique-identifier', // replace this with a unique string to identify the user
16+
userlookup_fetch: (ids) => fetch(`/api/users?ids=${ids.join(',')}`)
17+
.then((r) => r.json())
18+
});
19+
----

‎modules/ROOT/partials/configuration/userlookup_userid.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[[userlookup_userid]]
2+
== `userlookup_userid`
3+
4+
Required option to set the current user's unique ID in the editor, allowing the plugin to track changes made by this user and display them correctly in the Suggested Edits view. This option uses the xref:#userlookupapi[`UserLookup API`].
5+
6+
*Type:* `+String+`
7+
8+
.Example
9+
[source,javascript]
10+
----
11+
tinymce.init({
12+
selector: 'textarea', // Change this value according to your HTML
13+
plugins: 'suggestededits',
14+
toolbar: 'suggestededits',
15+
userlookup_userid: 'unique-identifier' // replace this with a unique string to identify the user
16+
});
17+
----

0 commit comments

Comments
 (0)