improvements to revisionhistory configuration options

tinymce · Feb 14, 2024 · 1b4bc3d · 1b4bc3d
1 parent 6cd60f2
commit 1b4bc3d
Show file tree

Hide file tree

Showing 5 changed files with 20 additions and 67 deletions.
diff --git a/...documentation-templates/ROOT/partials/configuration/<configuration_option>.adoc b/...documentation-templates/ROOT/partials/configuration/<configuration_option>.adoc
@@ -64,6 +64,6 @@ The `<configuration_option>` option has the following limitations.
 Known limitations.
 Complicated scenarios.
 Anything that warrants a CAUTION or WARNING admonition.
-///
+////
 
 // Remove all comment lines and comment blocks before publishing.
diff --git a/modules/ROOT/pages/revisionhistory.adoc b/modules/ROOT/pages/revisionhistory.adoc
@@ -61,11 +61,11 @@ liveDemo::{plugincode}[]
 
 The following configuration options affect the behavior of the {pluginname} plugin.
 
-// include::partial$configuration/revisionhistory_fetch.adoc[][leveloffset=+1]
+include::partial$configuration/revisionhistory_fetch.adoc[leveloffset=+1]
 
-// include::partial$configuration/revisionhistory_css_url.adoc[][leveloffset=+1]
+include::partial$configuration/revisionhistory_css_url.adoc[leveloffset=+1]
 
-// include::partial$configuration/revisionhistory_diff_classes.adoc[][leveloffset=+1]
+include::partial$configuration/revisionhistory_diff_classes.adoc[leveloffset=+1]
 
 include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
 

diff --git a/modules/ROOT/partials/configuration/revisionhistory_css_url.adoc b/modules/ROOT/partials/configuration/revisionhistory_css_url.adoc
@@ -1,10 +1,7 @@
 [[revisionhistory_css_url]]
 == `revisionhistory_css_url`
 
-This option provides the default location to load the change annotations css styling from. This option can be used along with `revisionhistory_diff_classes` to provide custom diff classes from a css file.
-
-// Add explanatory material as per the comment block below then remove
-// the block and this comment.
+This option provides the default location to load the change annotations css styling from. This option can be used along with `+revisionhistory_diff_classes+` to provide custom diff classes from a css file.
 
 ////
 What does the option do?
@@ -20,39 +17,25 @@ Are there risks?
 
 *Type:* `+String+`
 
-*Default value:* `'${pluginUrl}/css/revisionhistory.css'`
+*Default value:* `+'${pluginUrl}/css/revisionhistory.css'+`
 
 === Example: using `revisionhistory_css_url`
 
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your html
-	plugins: 'revisionhistory',
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'revisionhistory',
   toolbar: 'revisionhistory',
   revisionhistory_css_url: './revisionhistory.css'
 });
 ----
 
-// Add a working and tested configuration (edit as required)
-// or remove if not applicable.
-=== Example: disabling the <feature>
-
-To disable <feature>, set `revisionhistory_css_url` to `false`.
-
-[source,js]
-----
-tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
-  revisionhistory_css_url: 'false'
-});
-----
-
 // Remove if not applicable.
 // Edit the sub-head to singular or plural as required.
 === Limitation(s) of the `revisionhistory_css_url` option
 
-The `revisionhistory_css_url` option has the following limitations.
+The `+revisionhistory_css_url+` option has the following limitations.
 
 // Add explanatory material as per the comment block below then remove
 // the block and this comment.
@@ -61,6 +44,6 @@ The `revisionhistory_css_url` option has the following limitations.
 Known limitations.
 Complicated scenarios.
 Anything that warrants a CAUTION or WARNING admonition.
-///
+////
 
 // Remove all comment lines and comment blocks before publishing.
diff --git a/modules/ROOT/partials/configuration/revisionhistory_diff_classes.adoc b/modules/ROOT/partials/configuration/revisionhistory_diff_classes.adoc
@@ -1,10 +1,7 @@
 [[revisionhistory_diff_classes]]
 == `revisionhistory_diff_classes`
 
-This option configures what css classes should be applied to the change annotations. Note that the CSS class names must exist in the `revisionhistory_css_url` file for this option to work.
-
-// Add explanatory material as per the comment block below then remove
-// the block and this comment.
+This option configures what css classes should be applied to the change annotations. Note that the CSS class names must exist in the `revisionhistory_css_url` file for this option to work. This option can be used along with the `revisionhistory_css_url` to provide custom diff classes from a css file.
 
 ////
 What does the option do?
@@ -32,11 +29,10 @@ Are there risks?
 
 === Example: using `revisionhistory_diff_classes`
 
-// Add a working and tested configuration.
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your html
+  selector: 'textarea',  // change this value according to your HTML
 	plugins: 'revisionhistory',
   toolbar: 'revisionhistory',
 	revisionhistory_css_url: './revisionhistory.css',
@@ -48,20 +44,6 @@ tinymce.init({
 });
 ----
 
-// Add a working and tested configuration (edit as required)
-// or remove if not applicable.
-=== Example: disabling the <feature>
-
-To disable <feature>, set `revisionhistory_diff_classes` to `false`.
-
-[source,js]
-----
-tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
-  revisionhistory_diff_classes: 'false'
-});
-----
-
 // Remove if not applicable.
 // Edit the sub-head to singular or plural as required.
 === Limitation(s) of the `revisionhistory_diff_classes` option
@@ -75,6 +57,6 @@ The `revisionhistory_diff_classes` option has the following limitations.
 Known limitations.
 Complicated scenarios.
 Anything that warrants a CAUTION or WARNING admonition.
-///
+////
 
 // Remove all comment lines and comment blocks before publishing.
diff --git a/modules/ROOT/partials/configuration/revisionhistory_fetch.adoc b/modules/ROOT/partials/configuration/revisionhistory_fetch.adoc
@@ -1,11 +1,13 @@
 [[revisionhistory_fetch]]
 == `revisionhistory_fetch`
 
-// Add explanatory material as per the comment block below then remove
-// the block and this comment.
-
 The plugin uses the `revisionhistory_fetch` asynchronous function to retreive the revision history list.
 
+The `revisionhistory_fetch` option is a function that returns a https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise[Promise] that resolves to an array of objects representing the revision history.
+
+[NOTE]
+The revision history plugin does not automatically sort results before displaying. It is the responsibility of the user to sort the results according to their preferences, such as sorting them in reverse chronological order based on the `createdAt` date.
+
 ////
 What does the option do?
 Why use it?
@@ -68,7 +70,7 @@ The data returned by `revisionhistory_fetch` must adhere to the following requir
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your html
+  selector: 'textarea',  // change this value according to your HTML
 	plugins: 'revisionhistory',
   toolbar: 'revisionhistory',
   revisionhistory_fetch: () =>
@@ -81,20 +83,6 @@ tinymce.init({
 });
 ----
 
-// Add a working and tested configuration (edit as required)
-// or remove if not applicable.
-=== Example: disabling the <feature>
-
-To disable <feature>, set `revisionhistory_fetch` to `false`.
-
-[source,js]
-----
-tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
-  revisionhistory_fetch: 'false'
-});
-----
-
 // Remove if not applicable.
 // Edit the sub-head to singular or plural as required.
 === Limitation(s) of the `revisionhistory_fetch` option
@@ -108,6 +96,6 @@ The `revisionhistory_fetch` option has the following limitations.
 Known limitations.
 Complicated scenarios.
 Anything that warrants a CAUTION or WARNING admonition.
-///
+////
 
 // Remove all comment lines and comment blocks before publishing.