Skip to content

Commit 25127a5

Browse files
committed
DOC-3174: Updating suggestedits docs
1 parent 9b7ef26 commit 25127a5

File tree

3 files changed

+160
-32
lines changed

3 files changed

+160
-32
lines changed

modules/ROOT/pages/suggestededits.adoc

Lines changed: 10 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -49,37 +49,30 @@ The sidebar also displays all tracked changes that need to be resolved. Each cha
4949

5050
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`.
5151

52-
== Basic setup
52+
== Initial setup
53+
54+
The Suggested Edits plugin uses a document model to track changes. 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], and should be saved externally
5355

5456
To setup the {pluginname} plugin in the editor:
5557

5658
* add `{plugincode}` to the `plugins` option in the editor configuration;
5759
* add `{plugincode}` to the `toolbar` option in the editor configuration;
58-
* add `{plugincode}_model` to the editor configuration.
59-
* add `{plugincode}_uid` to the editor configuration.
60+
* add `{plugincode}_model` to the editor configuration, if a document is already being tracked.
6061

6162
For example:
6263

6364
[source,js]
6465
----
66+
const suggestededits_model = `<YOUR_DOCUMENT_MODEL>` // model provided by suggestededits plugin API
67+
6568
tinymce.init({
66-
selector: 'textarea', // change this value according to your HTML
69+
selector: 'textarea#suggestededits', // change this value according to your HTML
6770
plugins: 'suggestededits',
6871
toolbar: 'suggestededits',
69-
suggestededits_model: {
70-
version: 1,
71-
maxId: 0,
72-
contents: [
73-
{
74-
type: 'p',
75-
children: [
76-
{ text: 'Hello, World!' }
77-
]
78-
}
79-
]
80-
},
81-
suggestededits_uid: 'unique-identifier' // replace this with a unique string to identify the user
72+
suggestededits_model, // model provided by suggestededits plugin API
8273
});
74+
75+
<textarea id="suggestededits"><p>Your initial content here </p></textarea>
8376
----
8477

8578
== Options

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

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ tinymce.init({
2121
[[suggestededits_model]]
2222
== `suggestededits_model`
2323

24-
The `{plugincode}_model` option sets the initial model of the document to begin tracking changes. It takes as input an object representing the document. If no value is set, the plugin will generate the model by default.
24+
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.
2525

26+
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].
2627
//*Type:* xref:#trackeddocument[TrackedDocument] `+Object+`
2728

2829
=== Example: using `{plugincode}_model`
@@ -35,18 +36,7 @@ tinymce.init({
3536
plugins: 'suggestededits',
3637
toolbar: 'suggestededits',
3738
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
38-
suggestededits_model: {
39-
version: 1,
40-
maxId: 0,
41-
contents: [
42-
{
43-
type: 'p',
44-
children: [
45-
{ text: 'Hello, World!' }
46-
]
47-
}
48-
]
49-
}
39+
suggestededits_model // Model representing the document with up to date edits
5040
});
5141
----
5242

@@ -57,7 +47,7 @@ To configure a user's permission to edit the document and review changes, the `{
5747

5848
*Type:* `+String+`
5949

60-
*Possible Values*: `'full'`, `'suggest'`, `'read'`, `'none'`
50+
*Possible Values*: `'full'`, `'suggest'`, `'read'`, `'none'`
6151

6252
*Default Value*: `'full'`
6353

@@ -98,6 +88,37 @@ tinymce.init({
9888

9989
liveDemo::suggestededits-access[]
10090

91+
[[suggestededits_content]]
92+
== `suggestededits_content`
93+
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.
94+
95+
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
96+
97+
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.
98+
99+
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.
100+
101+
*Type:* `+String+`
102+
103+
*Possible Values*: `'html'`, `'model'`
104+
105+
*Default value:* `'html'`
106+
107+
=== Example: using `{plugincode}_css_url`
108+
109+
// Add a working and tested configuration.
110+
[source,js]
111+
----
112+
tinymce.init({
113+
selector: 'textarea', // Change this value according to your HTML
114+
plugins: 'suggestededits',
115+
toolbar: 'suggestededits',
116+
suggestededits_uid: 'unique-identifier', // replace this with a unique string to identify the user
117+
suggestededits_model,
118+
suggestededits_content: 'model' // change this value to set the content source
119+
});
120+
----
121+
101122
[[suggestededits_css_url]]
102123
== `suggestededits_css_url`
103124

modules/ROOT/partials/plugin-apis/suggestededits-apis.adoc

Lines changed: 115 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
|Name |Arguments |Description
44

55
|getModel |N/A |Return an object representing the document model used to store data of the tracked changes.
6-
//|setModel |xref:#trackeddocument[TrackedDocument] `+Object+` | Set the current model of the document.
6+
|setModel |xref:#trackeddocument[TrackedDocument] `+Object+` | Set the current model of the document.
77
//|resetModel |N/A |Reset the document to its original state.
88
|hasChanges |N/A |Return a boolean value indicating whether the document contains changes to be reviewed.
99
|===
@@ -14,10 +14,124 @@
1414
// Get the current model of the document
1515
tinymce.activeEditor.plugins.suggestededits.getModel();
1616
17+
// Set current model of the document
18+
tinymce.activeEditor.plugins.suggestededits.setModel(model);
19+
1720
// Check if document contains changes to be reviewed
1821
tinymce.activeEditor.plugins.suggestededits.hasChanges();
1922
----
2023

24+
[[get_model]]
25+
.`getModel` Example
26+
[source,js]
27+
----
28+
const documentId = '<YOUR_DOCUMENT_ID>'; // Replace with the actual document ID
29+
30+
tinymce.init({
31+
selector: 'textarea#suggestededits', // change this value according to your HTML
32+
plugins: 'suggestededits',
33+
toolbar: 'suggestededits save',
34+
suggestededits_model,
35+
setup: (editor) => {
36+
editor.ui.registry.addButton('save', {
37+
text: 'Save',
38+
onAction: () => {
39+
// Get the current content of the editor
40+
const content = editor.getContent();
41+
42+
// Get the current model of the document
43+
const model = editor.plugins.suggestededits.getModel();
44+
45+
fetch(`/api/documents/${documentId}`, {
46+
method: 'POST',
47+
headers: {
48+
'Content-Type': 'application/json',
49+
},
50+
body: JSON.stringify({ content, model }),
51+
})
52+
.then((response) => response.json())
53+
.then((data) => console.log('Document saved:', data))
54+
.catch((error) => console.error('Error saving document:', error));
55+
56+
// Save the model to the server
57+
fetch(`/api/models/${documentId}`, {
58+
method: 'POST',
59+
headers: {
60+
'Content-Type': 'application/json',
61+
},
62+
body: JSON.stringify(model),
63+
})
64+
.then((response) => response.json())
65+
.then((data) => console.log('Model saved:', data))
66+
.catch((error) => console.error('Error saving model:', error));
67+
}
68+
});
69+
}
70+
});
71+
72+
----
73+
74+
[[set_model]]
75+
.`setModel` Example
76+
[source,js]
77+
----
78+
const documentId = '<YOUR_DOCUMENT_ID>'; // Replace with the actual document ID
79+
80+
tinymce.init({
81+
selector: 'textarea#suggestededits', // change this value according to your HTML
82+
plugins: 'suggestededits',
83+
toolbar: 'suggestededits',
84+
// No model provided in the editor configuration, it will be fetched from the server
85+
init_instance_callback: (editor) => {
86+
// Fetch the document from the server
87+
fetch(`/api/documents/${documentId}`)
88+
.then((response) => {
89+
// Set the content in the editor
90+
editor.setContent(response);
91+
})
92+
.catch((error) => console.error(`Error fetching document ${documentId}:`, error));
93+
94+
// Fetch the document model from the server
95+
fetch(`/api/models/${documentId}`)
96+
.then((response) => response.json())
97+
.then((model) => {
98+
// Set the model in the editor
99+
editor.plugins.suggestededits.setModel(model);
100+
})
101+
.catch((error) => console.error(`Error fetching document ${documentId} model:`, error));
102+
}
103+
});
104+
----
105+
106+
[[has_changes]]
107+
.`hasChanges` Example
108+
[source,js]
109+
----
110+
tinymce.init({
111+
selector: 'textarea#suggestededits', // change this value according to your HTML
112+
plugins: 'suggestededits',
113+
toolbar: 'suggestededits',
114+
setup: (editor) => {
115+
editor.ui.registry.addButton('save', {
116+
text: 'Save',
117+
onAction: () => {
118+
// Get the current model of the document
119+
const hasChanges = editor.plugins.suggestededits.hasChanges();
120+
121+
if (hasChanges) {
122+
editor.notificationManager.open({
123+
text: 'There are changes to be reviewed.',
124+
type: 'warning',
125+
timeout: 5000,
126+
});
127+
} else {
128+
// Insert save logic here
129+
}
130+
}
131+
});
132+
}
133+
});
134+
----
21135
////
22136
.Examples
23137
[source,js]

0 commit comments

Comments
 (0)