You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
140 lines
5.9 KiB
140 lines
5.9 KiB
= Revision History Plugin
|
|
:navtitle: Revision History
|
|
:description: A view that allows {productname} users to see historical snapshots of a document and an ability to restore from a snapshot
|
|
:description_short: View containing historical snapshots of a document.
|
|
:keywords: plugin, Revision History, history, version, snapshots, restore, changes, revision, diff
|
|
:pluginname: Revision History
|
|
:plugincode: revisionhistory
|
|
:plugincategory: premium
|
|
|
|
include::partial$misc/admon-revisionhistory-paid-addon-pricing.adoc[]
|
|
|
|
The {pluginname} plugin offers users the ability to view document changes over time and restore previous revisions effortlessly.
|
|
|
|
== Interactive example
|
|
|
|
liveDemo::{plugincode}[]
|
|
|
|
include::partial$misc/admon-iframe-only.adoc[]
|
|
|
|
== How it works
|
|
|
|
The {pluginname} view is accessible via either the `revisionhistory` toolbar button or menu button within the `View` menu.
|
|
|
|
The key components are:
|
|
|
|
1. In the {pluginname} view header, there are two buttons.
|
|
* `Restore this version`: Sets the selected revision's content to the editor and closes the view. Note: the button is disabled for the `initial` and `draft` revisions.
|
|
* `Close`: Closes the **Revision History** view.
|
|
|
|
2. The readonly diff view presents the changes between the selected revision and its immediate predecessor, clearly highlighting for easy recognition. The changes are also color-coded for clarity:
|
|
* Red: Removed content.
|
|
* Green: New content.
|
|
* Yellow: Content being modified. Modifications to HTML content implies attributes or formatting (e.g. bold, italic, etc.).
|
|
3. The revisions sidebar displays all available document revisions. When a revision is selected, the diff view is updated accordingly.
|
|
|
|
[NOTE]
|
|
The default highlighting colors can be customized using the xref:revisionhistory_css_url[`+revisionhistory_css_url+`] option.
|
|
|
|
[NOTE]
|
|
The {pluginname} plugin processes commented HTML as valid content but disregards it during the revision comparison process. Revisions containing only commented content appear as empty in the view.
|
|
|
|
== Basic setup
|
|
|
|
To setup the {pluginname} plugin in the editor:
|
|
|
|
* add `{plugincode}` to the `plugins` option in the editor configuration;
|
|
* add `{plugincode}` to the `toolbar` option in the editor configuration;
|
|
* add `{plugincode}_fetch` option to the editor configuration;
|
|
|
|
For example:
|
|
|
|
[source,js]
|
|
----
|
|
tinymce.init({
|
|
selector: 'textarea', // change this value according to your HTML
|
|
plugins: 'revisionhistory',
|
|
toolbar: 'revisionhistory',
|
|
revisionhistory_fetch: () => Promise.resolve([]), // Replace this with an API request to get saved revisions
|
|
});
|
|
----
|
|
|
|
== Understanding revision types
|
|
|
|
The {pluginname} plugin offers three revision types:
|
|
|
|
. **Initial**: This revision is generated during the {productname} `Loaded` event, capturing the editor's initial content.
|
|
. **Draft**: Generated upon opening the {pluginname}, this revision reflects the editor's current content. When included, it becomes the `latest revision` in the revisions list.
|
|
. **Saved**: These revisions are fetched from the client's storage when opening the {pluginname} view, using the `revisionhistory_fetch` and `revisionhistory_fetch_revision` options.
|
|
|
|
When working with a document that has no saved revisions, the {pluginname} plugin typically maintains two revisions: `initial` and `draft`. If no changes have been made to the content since initialization, the `initial` revision is not displayed, as it is identical to the `draft` revision.
|
|
|
|
For documents with saved revisions, the `initial` revision is disregarded, assuming it already exists among the saved revisions. To include the initial content, add it as a revision using the `revisionhistory_fetch` option.
|
|
|
|
== Data structure
|
|
|
|
=== Revision
|
|
|
|
The revision is an `+Object+` that contains the following fields:
|
|
|
|
[cols="1,1,1,3",options="header"]
|
|
|===
|
|
| Field | Type | Required? | Description
|
|
| `+revisionId+` | `+string+` | required | The unique string ID of the revision.
|
|
| `+createdAt+` | `+string+` | required | A UTC datetime string in ISO-8061 format.
|
|
| `+content+` | `+string+` | optional | HTML string of the revision content. Empty string is considered as valid content.
|
|
| `+author+` | xref:#author[Author] `+Object+` | optional | The author of the revision.
|
|
|===
|
|
|
|
=== Author
|
|
|
|
The author is an `+Object+` that represents the author or creator of a revision. It contains the following fields:
|
|
|
|
[cols="1,1,1,3",options="header"]
|
|
|===
|
|
| Field | Type | Required? | Description
|
|
| `+id+` | `+string+` | required | The unique string ID of the author.
|
|
| `+name+` | `+string+` | optional | The name of the revision author. If not provided, the default value is `Anonymous`.
|
|
| `+avatar+` | `+string+` | optional | The URL of the author's avatar image. If not provided or invalid, the {pluginname} will use a generated avatar using the author's initials.
|
|
|===
|
|
|
|
|
|
== Options
|
|
|
|
The following configuration options affect the behavior of the {pluginname} plugin.
|
|
|
|
include::partial$configuration/revisionhistory_fetch.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_fetch_revision.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_allow_restore.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_author.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_display_author.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_css_url.adoc[leveloffset=+1]
|
|
|
|
include::partial$configuration/revisionhistory_diff_classes.adoc[leveloffset=+1]
|
|
|
|
include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
|
|
|
|
include::partial$misc/plugin-menu-item-id-boilerplate.adoc[]
|
|
|
|
== Commands
|
|
|
|
The {pluginname} plugin provides the following {productname} commands.
|
|
|
|
include::partial$commands/{plugincode}-cmds.adoc[]
|
|
|
|
== Events
|
|
|
|
The {pluginname} plugin provides the following events.
|
|
|
|
include::partial$events/{plugincode}-events.adoc[]
|
|
|
|
== APIs
|
|
|
|
The {pluginname} plugin provide the following APIs.
|
|
|
|
include::partial$plugin-apis/{plugincode}-apis.adoc[]
|