Skip to content

suggestededits.adoc

Latest commit

 

History

History
163 lines (97 loc) · 8.68 KB

suggestededits.adoc

File metadata and controls

163 lines (97 loc) · 8.68 KB

Suggested Edits Plugin

The Suggested Edits plugin allows multiple users to collaborate on a document. The review window shows which user suggested which edits, whether they added, removed, modified, or replaced any content, and allows users to provide feedback on those suggestions or give a final review by accepting or rejecting them.

Interactive example

liveDemo::suggestededits[]

How it works

The Suggested Edits plugin keeps track of every edit made to the document by the current user and stores this metadata in an internal model of the document. These suggestions can then be reviewed in the Review Edits view, where each edit is highlighted in the document, and where users can accept, reject, or provide feedback. The Review Edits view is accessible via either the suggestededits toolbar button or menu button within the View menu.

The model

The Suggested Edits model is a JSON object representing the document along with all unreviewed edits and feedback. The model must be kept in sync with the editor content and loaded into the editor at the same time as the content.

The structure of the model is not documented and should not be relied upon.

The model can be retrieved from the plugin using the getModel API, saved externally alongside the document, and loaded into the editor with the suggestededits_model option. This ensures that the document and the model are in sync and every user’s contributions are tracked correctly. If the model and content are out of sync when the editor loads, the difference between them will be included in the next 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.

Alternatively the suggestededits_content option allows the model to generate the editor content, in which case the two do not need to be kept in sync.

Reviewing edits

The Review Edits view can be used to view and reviewing edits made by multiple authors. The available actions in this view depends on the suggestededits_access option.

Header

The view contains a few controls to manage the review process:

  • Show edits: Toggles whether suggested edits are shown. When hidden, the view shows what the document will look like if the review is completed.

  • Complete review: Ends the review, applying resolved suggestions to the document. Unresolved suggestions remain in the document for future review.

  • Cancel: Ignores any resolved suggestions and makes no change to the document. Feedback given on suggestions will be retained.

Document

The current editor document is displayed in a sandboxed iframe, with each suggested edit highlighted as they appear in the document. The following color coding is used to indicate the type of change:

  • Green: Added content.

  • Blue: Modified attributes or formatting (e.g. bold, italic, etc.).

  • Red: Removed content.

Replaced content is represented as both added and removed content, and indicates that some content was removed and replaced with new content in a single edit. When a suggestion is selected, whether in the document or in the sidebar, the corresponding highlighted suggestion in the document will be outlined in blue and scrolled into view.

Sidebar

Each suggested edit is listed as a card in the sidebar and color coded by the type of change, along with the user who made the suggestion, when the edit was made, and any feedback provided on that suggestion. When selected, each suggestion can be handled in the following ways:

  • Accept: Resolves the suggestion, applying the edit to the document when the review is completed.

  • Reject: Resolves the suggestion, turning back the edit to the original state.

  • Revert: Reverts the current "Accept" or "Reject" resolution on the suggestion.

  • Provide feedback: Opens a text area for users to provide feedback on the suggestion.

Feedback is shown in chronological order beneath the card details when the card is selected. Feedback allows users to discuss suggestions before resolving them. The feedback author can edit or delete their own feedback, with the appropriate permissions in the suggestededits_access option.

At the top of the sidebar there is a dropdown menu to apply review actions in bulk to all suggested edits:

  • Accept all.

  • Reject all.

  • Revert all.

Finishing a review

When completing a review, resolved suggestions will be applied to the document and will no longer be tracked in the model as a suggestion. Feedback on resolved suggestions is discarded. Any "accepted" edits will remain in the document, and any "rejected" edits will be reverted to the state before the suggestion was made.

Review actions will apply the following to the document:

When added content is:

  • Accepted: The content will remain in the document.

  • Rejected: The content will be removed from the document.

When modified content is:

  • Accepted: The content will retain the current formats and attributes.

  • Rejected: The content will revert to modified formats and attributes to match the content state before the edit was made.

When removed content is:

  • Accepted: The content will be removed from the document.

  • Rejected: The removed content will be restored to the document.

If a review is canceled, no resolved suggestions will be applied to the document. All suggestions, including any feedback provided during that review session, will remain stored in the model.

Initial setup

To setup the Suggested Edits plugin in the editor:

  • add suggestededits to the plugins option in the editor configuration;

  • add suggestededits to the toolbar option in the editor configuration;

For example:

tinymce.init({
  selector: 'textarea#suggestededits',  // change this value according to your HTML
  plugins: 'suggestededits',
  toolbar: 'suggestededits',
});

This configuration adds Suggested Edits to the editor toolbar, enabling access to the plugin features. To fully utilize the plugin, additional configuration options must be provided.

Options

The following configuration options affect the behavior of the Suggested Edits plugin.

Both the user_id and fetch_users options are required to configure the User Lookup API. This API is used in the Suggested Edits plugin to provide user information for each user who has made a change, allowing other users to see who made which suggestion.

  • The current user ID should be set with the user_id option. The user ID should be a unique string that identifies the user, such as a username or an email address.

  • The 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.

Commands

The Suggested Edits plugin provides the following {productname} commands.

Events

The Suggested Edits plugin provides the following events.

APIs

The Suggested Edits plugin provides the following APIs.