Skip to content

Commit 4edf9b8

Browse files
MitchC1999MitchC1999
committed
DOC-3246: Final edits
1 parent cbc5d5d commit 4edf9b8

File tree

9 files changed

+128
-109
lines changed

9 files changed

+128
-109
lines changed

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

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

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -430,8 +430,8 @@ tinymce.init({
430430
resolve(userDb[userId] || { id: userId }))
431431
)),
432432
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
433-
suggestededits_model: model,
433+
readonly: false,
434+
suggestededits_access: 'feedback',
434435
suggestededits_content: 'html',
435-
suggestededits_access: 'feedback', // Change this value to set the user's permission to the Suggested Edits view
436-
readonly: false, // Set to true to restrict a user's editing permission
436+
suggestededits_model: model
437437
});

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

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

‎modules/ROOT/examples/live-demos/suggestededits-access-read/index.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -430,8 +430,8 @@ tinymce.init({
430430
resolve(userDb[userId] || { id: userId }))
431431
)),
432432
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
433-
suggestededits_model: model,
433+
readonly: false,
434+
suggestededits_access: 'read',
434435
suggestededits_content: 'html',
435-
suggestededits_access: 'read', // Change this value to set the user's permission to the Suggested Edits view
436-
readonly: false, // Set to true to restrict a user's editing permission
436+
suggestededits_model: model,
437437
});

‎modules/ROOT/examples/live-demos/suggestededits/index.js‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
11
/** Fake user database */
22
const userDb = {
3-
adamhayes: {
4-
id: 'adamhayes',
5-
name: 'Adam Hayes',
6-
avatar: `https://randomuser.me/api/portraits/men/4.jpg`,
7-
},
8-
martincook: {
9-
id: 'martincook',
10-
name: 'Martin Cook',
11-
avatar: `https://randomuser.me/api/portraits/men/5.jpg`,
12-
},
13-
kalebwilson: {
14-
id: 'kalebwilson',
15-
name: 'Kaleb Wilson',
16-
avatar: `https://randomuser.me/api/portraits/men/6.jpg`,
17-
},
18-
sarahjones: {
19-
id: 'sarahjones',
20-
name: 'Sarah Jones',
21-
avatar: `https://randomuser.me/api/portraits/women/1.jpg`,
22-
}
3+
adamhayes: {
4+
id: 'adamhayes',
5+
name: 'Adam Hayes',
6+
avatar: `https://randomuser.me/api/portraits/men/4.jpg`,
7+
},
8+
martincook: {
9+
id: 'martincook',
10+
name: 'Martin Cook',
11+
avatar: `https://randomuser.me/api/portraits/men/5.jpg`,
12+
},
13+
kalebwilson: {
14+
id: 'kalebwilson',
15+
name: 'Kaleb Wilson',
16+
avatar: `https://randomuser.me/api/portraits/men/6.jpg`,
17+
},
18+
sarahjones: {
19+
id: 'sarahjones',
20+
name: 'Sarah Jones',
21+
avatar: `https://randomuser.me/api/portraits/women/1.jpg`,
22+
}
2323
};
2424

2525
const model = {
@@ -420,17 +420,17 @@ const model = {
420420
};
421421

422422
tinymce.init({
423-
selector: 'textarea#suggestededits',
424-
height: 500,
425-
plugins: 'suggestededits advlist anchor autolink code charmap emoticons fullscreen help image link lists media preview searchreplace table',
426-
toolbar: 'undo redo | suggestededits | styles fontsizeinput | bold italic | align bullist numlist | table link image | code',
427-
user_id: 'kalebwilson',
428-
fetch_users: (userIds) => Promise.all(userIds
429-
.map((userId) => new Promise((resolve) =>
430-
resolve(userDb[userId] || { id: userId }))
431-
)),
432-
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
433-
suggestededits_model: model,
434-
suggestededits_content: 'html',
435-
suggestededits_access: 'full'
423+
selector: 'textarea#suggestededits',
424+
height: 500,
425+
plugins: 'suggestededits advlist anchor autolink code charmap emoticons fullscreen help image link lists media preview searchreplace table',
426+
toolbar: 'undo redo | suggestededits | styles fontsizeinput | bold italic | align bullist numlist | table link image | code',
427+
user_id: 'kalebwilson',
428+
fetch_users: (userIds) => Promise.all(userIds
429+
.map((userId) => new Promise((resolve) =>
430+
resolve(userDb[userId] || { id: userId }))
431+
)),
432+
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }',
433+
suggestededits_model: model,
434+
suggestededits_content: 'html',
435+
suggestededits_access: 'full'
436436
});

‎modules/ROOT/pages/suggestededits.adoc‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,15 @@ include::partial$misc/admon-iframe-only.adoc[]
1919

2020
== How it works
2121

22-
The {pluginname} plugin keeps track of every suggested edit made to the document by the current user, as the edits are made, and stores this metadata in an internal model of the document. These suggestions can then be reviewed in the `'suggestededits'` xref:custom-view.adoc[editor view], where each edit is highlighted in the document, and where you can accept, reject, or provide feedback. The `'suggestededits'` view is accessible via either the `suggestededits` toolbar button or menu button within the `View` menu. These edits, and any feedback provided, are stored in the model provided by the plugin xref:#get_model[`+get_model()+` API].
22+
The {pluginname} plugin keeps track of every suggested edit made to the document by the current user, as the edits are made, and stores this metadata in an internal model of the document. These suggestions can then be reviewed in the `'suggestededits'` xref:custom-view.adoc[editor view], where each edit is highlighted in the document, and where you can accept, reject, or provide feedback. The `'suggestededits'` view is accessible via either the `suggestededits` toolbar button or menu button within the `View` menu.
2323

24-
[IMPORTANT]
25-
This model should be saved externally alongside the document, and loaded into the editor with the xref:#suggestededits_model[`+suggestededits_model+`] option. This ensures that both the document and the model are in sync, and that every user's contributions are tracked correctly.
24+
== The model
25+
26+
The {pluginname} model is a JSON object representing the document along with all unreviewed edits. The model should be kept in sync with the editor content and loaded into the editor each time the document is opened.
27+
28+
The model should be retrieved from the plugin using the xref:#get_model[`+getModel+`] API, then saved externally alongside the document, and loaded into the editor with the xref:#suggestededits_model[`+suggestededits_model+`] option each time the document is opened. This ensures that both the document and the model are in sync, and that every user's contributions are tracked correctly. If the model and content are out of sync, the difference between them will be applied as a suggested edit by the current user. If a model is not provided in the editor configuration or is set to `+undefined+`, the plugin will generate a new model from the initial content.
29+
30+
When the xref:#suggestededits_content[`+suggestededits_content+`] option is set to `'model'`, only the model is required, so keeping a synchronised document is not necessary. This also means that there will be no accidental suggestions caused by the editor content being out of sync with the model.
2631

2732
== Reviewing edits
2833

@@ -55,9 +60,9 @@ Each suggested edit is listed as a card in the sidebar and color coded by the ty
5560
* Revert: Reverts the current "Accept" or "Reject" resolution on the suggestion.
5661
* Provide feedback: Opens a text area for you to provide feedback on the suggestion.
5762

58-
Any feedback will be stored in the model and displayed underneath the card details and in chronological order. This feedback thread can be used to discuss the suggestion with the author or other reviewers. The feedback author can edit or delete their own feedback.
63+
Feedback is shown in chronological order beneath the card details, when the card is selected. Feedback threads allows users to discuss suggestions before resolving them. The feedback author can edit or delete their own feedback, with the appropriate permissions in the xref:#suggestededits_access[`+suggestededits_access+`] option.
5964

60-
At the top of the sidebar, there is also a dropdown menu to apply review actions in bulk to all suggested edits:
65+
At the top of the sidebar, there is a dropdown menu to apply review actions in bulk to all suggested edits:
6166

6267
* Accept all.
6368
* Reject all.
@@ -108,14 +113,6 @@ This configuration adds {pluginname} to the editor toolbar, enabling access to t
108113

109114
== Options
110115

111-
The {pluginname} plugin requires a model for storing suggestions. If a model is not provided in the editor configuration or is set to `+undefined+`, the plugin generates a new model. This model contains all current suggested edits. To maintain continuity across sessions, the current model for the document should always be supplied unless initializing a new document. The model can be retrieved from the editor at any time using the xref:#get_model[getModel API], and should be saved externally alongside the document.
112-
113-
Both the xref:#user_id[`+user_id+`] and xref:#fetch_users[`+fetch_users+`] options are required to configure the xref:userlookup.adoc[User Lookup API]. This API is used in the {pluginname} plugin to provide user information for each user who has made a change, allowing other users to see who made which suggestion.
114-
115-
* The current user ID should be set with the xref:#user_id[`+user_id+` option]. The user ID should be a unique string that identifies the user, such as a username or an email address.
116-
117-
* The xref:#fetch_users[`+fetch_users+` option] is required to provide the name and avatar for each user who has made a change, to then appear in the review. This option can be configured to retrieve this information from a backend service, as it provides an array of user IDs and expects a promise of an array, containing the appropriate data for the requested user IDs.
118-
119116
The following configuration options affect the behavior of the {pluginname} plugin.
120117

121118
include::partial$configuration/suggestededits_model.adoc[leveloffset=+1]
@@ -128,6 +125,11 @@ include::partial$configuration/user_id.adoc[leveloffset=+1]
128125

129126
include::partial$configuration/fetch_users.adoc[leveloffset=+1]
130127

128+
Both the xref:#user_id[`+user_id+`] and xref:#fetch_users[`+fetch_users+`] options are required to configure the xref:userlookup.adoc[User Lookup API]. This API is used in the {pluginname} plugin to provide user information for each user who has made a change, allowing other users to see who made which suggestion.
129+
130+
* The current user ID should be set with the xref:#user_id[`+user_id+`] option. The user ID should be a unique string that identifies the user, such as a username or an email address.
131+
* The xref:#fetch_users[`+fetch_users+`] option is required to provide the name and avatar for users who have made suggestions. This option can be configured to fetch data from a backend service. The `+fetch_users+` function is given an array of user IDs and should return a promise, which resolves to an array containing data for the requested user IDs.
132+
131133
include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
132134

133135
include::partial$misc/plugin-menu-item-id-boilerplate.adoc[]

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

Lines changed: 14 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,44 @@
11
[[suggestededits_access]]
22
== `suggestededits_access`
33

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.
4+
The `suggestededits_access` option determines the level of access a user has to the {pluginname} view. This setting is crucial for controlling who can accept or reject suggestions, add feedback, or view the document in read-only mode. When used in conjunction with the `readonly` option, it allows for fine-grained control over user permissions.
5+
6+
When set to:
7+
8+
* `'full'`: The user has full access to the {pluginname} view, with permission to accept or reject suggestions.
9+
* `'feedback'`: The user has access to the {pluginname} view, with permission to add feedback to suggestions.
10+
* `'read'`: The user has read-only access to the {pluginname} view.
11+
* `'none'`: The user has no access to the {pluginname} view.
512

613
*Type:* `+String+`
714

815
*Possible Values*: `'full'`, `'feedback'`, `'read'`, `'none'`
916

1017
*Default Value*: `'full'`
1118

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 or reject suggestions.
20-
21-
|`+'feedback'+`
22-
|Access to the {pluginname} view, with permission to add feedback to suggestions.
23-
24-
|`+'read'+`
25-
|Read-only access to the {pluginname} view.
26-
27-
|`+'none'+`
28-
|No access to the {pluginname} view.
29-
|===
30-
31-
=== Example: `suggestededits_access: 'feedback'`
19+
.Example: `suggestededits_access: 'feedback'`
3220
[source,javascript]
3321
----
3422
tinymce.init({
3523
selector: 'textarea', // Change this value according to your HTML
3624
plugins: 'suggestededits',
3725
toolbar: 'suggestededits',
38-
suggestededits_access: 'feedback', // Change this value to set the Suggested Edits view permissions
39-
readonly: false // Set to true to restrict a user's editing permission
26+
suggestededits_access: 'feedback', // Change this value to set the {pluginname} view permissions
27+
readonly: false // Set to true to restrict editing
4028
});
4129
----
4230

4331
liveDemo::suggestededits-access-feedback[]
4432

45-
=== Example: `suggestededits_access: 'read'`
33+
.Example: `suggestededits_access: 'read'`
4634
[source,javascript]
4735
----
4836
tinymce.init({
4937
selector: 'textarea', // Change this value according to your HTML
5038
plugins: 'suggestededits',
5139
toolbar: 'suggestededits',
52-
suggestededits_access: 'feedback', // Change this value to set the Suggested Edits view permissions
53-
readonly: false // Set to true to restrict a user's editing permission
40+
suggestededits_access: 'feedback', // Change this value to set the {pluginname} view permissions
41+
readonly: false // Set to true to restrict editing
5442
});
5543
----
5644
liveDemo::suggestededits-access-read[]

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

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,29 @@
11
[[suggestededits_content]]
22
== `suggestededits_content`
3-
The `suggestededits_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.
43

5-
In a `'html'`-first approach, the editor loads content normally and the {pluginname} plugin provides augmentation. The integrator is responsible for saving the model at the same time as the editor content and providing it on the next load using the `suggestededits_model` option. This allows {pluginname} to be integrated quickly into a CMS by adding the model as an additional hidden field alongside the editor content.
4+
The `suggestededits_content` option controls whether the content is loaded from the editor or the `suggestededits_model` model, allowing you to define the source of truth for the document. In either case, if a model is not provided, the plugin will generate a new model from the initial editor content.
65

7-
If a model is not provided the plugin will generate a new one from the initial content of the editor.
6+
When set to:
87

9-
When `suggestededits_content` is set to `'model'`, the plugin bypasses the editor's content load procedures and instead uses the `suggestededits_model` option to generate the initial content. This would allow an integrator to only require the model for document tracking, and treat the editor content as simply a rendering of it.
8+
* `'html'`: the editor loads content normally, and the plugin synchronises the model with the content. This simplifies the configuration of {pluginname} in an existing integration, by attaching the {pluginname} model as an additional field alongside the editor content.
9+
* `'model'`: the editor uses the `suggestededits_model` option to generate the initial content, ignoring any pre-existing content in the editor. With this configuration, you only need to store and provide the model, simplifying the integration of the {pluginname} plugin.
1010

11-
If a model is not provided, the plugin will allow the editor to load content normally and generate a new model from there (the same way `html` works).
11+
NOTE: The integrator is responsible for saving the model and providing it on the next load using the `suggestededits_model` option.
1212

1313
*Type:* `+String+`
1414

1515
*Possible Values*: `'html'`, `'model'`
1616

1717
*Default value:* `'html'`
1818

19-
=== Example: using `suggestededits_content`
20-
19+
.Example: using `suggestededits_content`
2120
[source,js]
2221
----
2322
tinymce.init({
2423
selector: 'textarea', // Change this value according to your HTML
2524
plugins: 'suggestededits',
2625
toolbar: 'suggestededits',
27-
user_id: 'unique-identifier', // Replace this with a unique string to identify the user
28-
fetch_users, // Function to fetch users for the user lookup API
2926
suggestededits_model, // Load the saved model into the editor
30-
suggestededits_content: 'model' // Only set this if you want to load the initial content from the model
27+
suggestededits_content: 'model' // Set to 'model' if you want to load the initial content from the `suggestededits_model` option
3128
});
3229
----

0 commit comments

Comments
 (0)