DOC-3143: Update key information about trial period behaviour for document converters on Tiny Cloud. (#3640)

* DOC-3143: update key information about trial period behaviour for document converters on Tiny Cloud.

* Update modules/ROOT/pages/exportpdf.adoc

Co-authored-by: shirqa <[email protected]>

* Update modules/ROOT/pages/exportword.adoc

Co-authored-by: shirqa <[email protected]>

* Update modules/ROOT/pages/importword.adoc

Co-authored-by: shirqa <[email protected]>

* DOC-3143: add partial file for expected data structure for auth token.

* Update modules/ROOT/pages/exportpdf.adoc

* Update modules/ROOT/pages/exportword.adoc

* Update modules/ROOT/pages/importword.adoc

* Update JWT authentication documentation across export and import plugins including use of partials.

---------

Co-authored-by: shirqa <[email protected]>
Co-authored-by: tiny-ben-tran <[email protected]>

Author: 3 people

modules/ROOT/pages/exportpdf.adoc

@@ -1,6 +1,7 @@
 = {pluginname} plugin
 :plugincode: exportpdf
 :pluginname: Export to PDF
+:pluginfilename: export-to-pdf
 :navtitle: {pluginname}
 :description: The {pluginname} feature provides the ability to generate a PDF file directly from the editor.
 :description_short: Generate a PDF file directly from the editor.
@@ -22,29 +23,34 @@ liveDemo::exportpdf[]
 
 To add the {pluginname} plugin to the editor, add `{plugincode}` to the `plugins` option in the editor configuration.
 
-For example:
-
+.Example:
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',
   plugins: 'exportpdf',
   toolbar: 'exportpdf',
+// Below option is only required when using the cloud-based Export to PDF plugin from Tiny.Cloud.
+// Avoid setting it up during the trial period.
+  exportpdf_token_provider: () => { 
+    return fetch('http://localhost:3000/jwt', { // specify your token endpoint
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }).then(response => response.json());
+  },
 });
 ----
 
-[IMPORTANT]
-When using the {pluginname} plugin with the {companyname} Cloud service, JWT authentication is required to use the service. For more information on how to set up JWT authentication with {pluginname}, see examples:
+For more infomation on the exportpdf_token_provider option, see xref:exportpdf.adoc#exportpdf-token-provider[exportpdf_token_provider].
+
+include::partial$misc/admon-jwt-authentication-requirements.adoc[]
 
-* xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[{pluginname} with JWT authentication (Node.js)]
-* xref:export-to-pdf-with-jwt-authentication-php.adoc[{pluginname} with JWT authentication (PHP)]
 
 == Basic setup using the self-hosted service
 
 To use the self-hosted version of the {pluginname} plugin, you need to set the `exportpdf_service_url` option to the URL of the service.
 
-For example:
-
+.Example:
 [source,js]
 ----
 tinymce.init({

modules/ROOT/pages/exportword.adoc

@@ -1,6 +1,7 @@
 = {pluginname} plugin
 :plugincode: exportword
 :pluginname: Export to Word
+:pluginfilename: export-to-word
 :navtitle: {pluginname}
 :description: The {pluginname} feature lets you generate a .docx (Microsoft Word document) file directly from the editor.
 :description_short: Generate a .docx file directly from the editor.
@@ -36,20 +37,27 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'exportword',
   toolbar: 'exportword',
+// Below option is only required when using the cloud-based Export to Word plugin from Tiny.Cloud.
+// Avoid setting it up during the trial period.
+  exportword_token_provider: () => {
+    return fetch('http://localhost:3000/jwt', { // specify your token endpoint
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }).then(response => response.json());
+  },
 });
 ----
 
-[IMPORTANT]
-When using the {pluginname} plugin with the {companyname} Cloud service, JWT authentication is required to use the service. For more information on how to set up JWT authentication with {pluginname}, see examples:
+For more infomation on the exportword_token_provider option, see xref:exportword.adoc#exportword-token-provider[exportword_token_provider]
+
+include::partial$misc/admon-jwt-authentication-requirements.adoc[]
 
-* xref:export-to-word-with-jwt-authentication-nodejs.adoc[{pluginname} with JWT authentication (Node.js)]
-* xref:export-to-word-with-jwt-authentication-php.adoc[{pluginname} with JWT authentication (PHP)]
 
 == Basic setup using the self-hosted service
 
 To use the self-hosted version of the {pluginname} plugin, you need to set the `exportword_service_url` option to the URL of the service.
 
-For example:
+.Example:
 [source,js]
 ----
 tinymce.init({

modules/ROOT/pages/importword.adoc

@@ -2,6 +2,7 @@
 = {pluginname} plugin
 :plugincode: importword
 :pluginname: Import from Word
+:pluginfilename: import-from-word
 :navtitle: {pluginname}
 :description: Provides a way to import .docx (Microsoft Word documents) or .dotx (Microsoft Word templates) files into the editor.
 :description_short: Import .docx or .dotx files into the editor.
@@ -31,21 +32,27 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'importword',
   toolbar: 'importword',
+// Below option is only required when using the cloud-based Import from Word plugin from Tiny.Cloud.
+// Avoid setting it up during the trial period.
+  importword_token_provider: () => { // required when using the Import from Word plugin with Tiny Cloud.
+    return fetch('http://localhost:3000/jwt', { // specify your token endpoint
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }).then(response => response.json());
+  },
 });
 ----
 
-[IMPORTANT]
-When using the {pluginname} plugin with the {companyname} Cloud service, JWT authentication is required to use the service. For more information on how to set up JWT authentication with {pluginname}, see examples:
+For more infomation on the importword_token_provider option, see xref:importword.adoc#importword-token-provider[importword_token_provider].
+
+include::partial$misc/admon-jwt-authentication-requirements.adoc[]
 
-* xref:import-from-word-with-jwt-authentication-nodejs.adoc[{pluginname} with JWT authentication (Node.js)]
-* xref:import-from-word-with-jwt-authentication-php.adoc[{pluginname} with JWT authentication (PHP)]
 
 == Basic setup using the self-hosted service
 
 To use the self-hosted version of the {pluginname} plugin, you need to set the `importword_service_url` option to the URL of the service.
 
-For example:
-
+.Example:
 [source,js]
 ----
 tinymce.init({

modules/ROOT/partials/configuration/exportpdf_token_provider.adoc

@@ -7,6 +7,8 @@ The `exportpdf_token_provider` option enables integration with a token-based aut
 
 *Default value:* `undefined`
 
+*Return data:* xref:exportpdf.adoc#data-structure[`Token` object]
+
 === Example: using `exportpdf_token_provider`
 
 [source,js]
@@ -15,7 +17,7 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'exportpdf',
   toolbar: 'exportpdf',
-  exportpdf_token_provider: () => {
+  exportpdf_token_provider: () => { // required when using the Export to PDF plugin with Tiny Cloud.
     return fetch('http://localhost:3000/jwt', { // specify your token endpoint
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -24,8 +26,4 @@ tinymce.init({
 });
 ----
 
-[NOTE]
-The `exportpdf_token_provider` option is required when using the {companyname} Cloud service. For more information on how to set up JWT authentication with {pluginname}, see examples:
-
-* xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Export to PDF with JWT authentication (Node.js)]
-* xref:export-to-pdf-with-jwt-authentication-php.adoc[Export to PDF with JWT authentication (PHP)]
+include::partial$misc/admon-document-converters-jwt-expected-data-structure.adoc[]

modules/ROOT/partials/configuration/exportword_token_provider.adoc

@@ -7,6 +7,8 @@ The `exportword_token_provider` option enables integration with a token-based au
 
 *Default value:* `undefined`
 
+*Return data:* xref:exportword.adoc#data-structure[`Token` object]
+
 === Example: using `exportword_token_provider`
 
 [source,js]
@@ -15,7 +17,7 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'exportword',
   toolbar: 'exportword',
-  exportword_token_provider: () => {
+  exportword_token_provider: () => { // required when using the Export to Word plugin with Tiny Cloud.
     return fetch('http://localhost:3000/jwt', { // specify your token endpoint
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -24,9 +26,4 @@ tinymce.init({
 });
 ----
 
-
-[NOTE]
-The `exportword_token_provider` option is required when using the {companyname} Cloud service. For more information on how to set up JWT authentication with {pluginname}, see examples:
-
-* xref:export-to-word-with-jwt-authentication-nodejs.adoc[Export to Word with JWT authentication (Node.js)]
-* xref:export-to-word-with-jwt-authentication-php.adoc[Export to Word with JWT authentication (PHP)]
+include::partial$misc/admon-document-converters-jwt-expected-data-structure.adoc[]

modules/ROOT/partials/configuration/importword_token_provider.adoc

@@ -7,6 +7,8 @@ The `importword_token_provider` option enables integration with a token-based au
 
 *Default value:* `undefined`
 
+*Return data:* xref:importword.adoc#data-structure[`Token` object]
+
 === Example: using `importword_token_provider`
 
 [source,js]
@@ -15,7 +17,7 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'importword',
   toolbar: 'importword',
-  importword_token_provider: () => {
+  importword_token_provider: () => { // required when using the Import from Word plugin with Tiny Cloud.
     return fetch('http://localhost:3000/jwt', { // specify your token endpoint
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -24,8 +26,4 @@ tinymce.init({
 });
 ----
 
-[NOTE]
-The `importword_token_provider` option is required when using the {companyname} Cloud service. For more information on how to set up JWT authentication with {pluginname}, see examples:
-
-* xref:import-from-word-with-jwt-authentication-nodejs.adoc[Import to Word with JWT authentication (Node.js)]
-* xref:import-from-word-with-jwt-authentication-php.adoc[Import to Word with JWT authentication (PHP)]
+include::partial$misc/admon-document-converters-jwt-expected-data-structure.adoc[]

modules/ROOT/partials/misc/admon-document-converters-jwt-expected-data-structure.adoc

@@ -0,0 +1,17 @@
+[[data-structure]]
+=== Data structure for the JWT token
+
+The object containing the valid encoded token must match the following structure:
+
+[source,js]
+----
+{
+  token: "<encoded JWT string>"
+}
+----
+
+[cols="1,1,1,3",options="header"]
+|===
+|Field |Type |Required? |Description
+|`+token+` |`+string+` |required |A Base64-encoded JSON Web Token (JWT) used for authentication and authorization.
+|===

modules/ROOT/partials/misc/admon-jwt-authentication-requirements.adoc

@@ -0,0 +1,18 @@
+[IMPORTANT]
+====
+The {pluginname} plugin **requires** JWT authentication when using the {companyname} Cloud service.
+
+* Configure the `{plugincode}_token_provider` option to specify the endpoint for retrieving a valid JWT token.
+
+For more information on how to set up JWT authentication with {pluginname}, see examples:
+
+* xref:{pluginfilename}-with-jwt-authentication-nodejs.adoc[{pluginname} with JWT authentication (Node.js)]
+* xref:{pluginfilename}-with-jwt-authentication-php.adoc[{pluginname} with JWT authentication (PHP)]
+
+**Trial period behavior:**
+
+* The {pluginname} plugin runs in evaluation mode and adds a watermark to exported content.
+* The `{plugincode}_token_provider` option is "not required" during the trial period.
+* If the trial period "expires" or the plugin lacks the necessary entitlement, it becomes _non-functional_.
+* Attempting to use JWT authentication during the trial will result in an _error_.
+====