DOC-2591: Improve documentation for importword, exportpdf and `ex…

…portword` for Cloud. (#3535) * DOC-2591: Improve documentation for importword, exportpdf and exportword to support Cloud. * Update modules/ROOT/pages/exportpdf.adoc Co-authored-by: Farzad Hayat <[email protected]> * Update modules/ROOT/pages/exportword.adoc Co-authored-by: Farzad Hayat <[email protected]> * Update modules/ROOT/pages/importword.adoc Co-authored-by: Farzad Hayat <[email protected]> * DOC-2591: Update exportpdf_converter_options value. * DOC-2591: File name changes for importword. * DOC-2591: remove second forward slash from pricing admin urls. --------- Co-authored-by: Farzad Hayat <[email protected]>
tinymce · Dec 11, 2024 · eb7f593 · eb7f593
1 parent debe7d9
commit eb7f593
Show file tree

Hide file tree

Showing 20 changed files with 449 additions and 274 deletions.
diff --git a/modules/ROOT/pages/exportpdf.adoc b/modules/ROOT/pages/exportpdf.adoc
@@ -1,4 +1,4 @@
-= Export to PDF plugin
+= {pluginname} plugin
 :navtitle: Export to PDF
 :description: The Export to PDF feature provides the ability to generate a PDF file directly from the editor.
 :description_short: Generate a PDF file directly from the editor.
@@ -18,7 +18,7 @@ The {pluginname} feature collects the HTML generated with the `tinymce.editor.ge
 
 liveDemo::exportpdf[]
 
-== Basic setup
+== Basic setup using the {companyname} Cloud service
 
 To add the {pluginname} plugin to the editor, add `{plugincode}` to the `plugins` option in the editor configuration.
 
@@ -30,15 +30,47 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'exportpdf',
   toolbar: 'exportpdf',
-  exportpdf_service_url: '<service url>'
 });
 ----
 
+[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:
+
+* xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Export to PDF with JWT authentication (Nodejs)].
+* xref:export-to-pdf-with-jwt-authentication-php.adoc[Export to PDF 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:
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  plugins: 'exportpdf',
+  toolbar: 'exportpdf',
+  exportpdf_service_url: 'http://localhost:8080/' // Update with the URL of the service you are using such  as 'http://myserver.com/'
+});
+----
+
+[IMPORTANT]
+====
+The `exportpdf_service_url` option automatically appends `/v1/convert` to the URL provided, so only the base URL is required. For example, if the service is hosted at `http://localhost:8080/v1/convert`, the `exportpdf_service_url` option should be set to `http://localhost:8080/`. When using in production, ensure that `exportpdf_service_url` is updated to the production URL such as `https://myserver.com/`.
+====
+
 == Options
 
 The following configuration options affect the behavior of the {pluginname} plugin.
 
-include::partial$configuration/{plugincode}.adoc[leveloffset=+1]
+include::partial$configuration/exportpdf_service_url.adoc[leveloffset=+1]
+
+include::partial$configuration/exportpdf_token_provider.adoc[leveloffset=+1]
+
+include::partial$configuration/exportpdf_converter_options.adoc[leveloffset=+1]
+
+include::partial$configuration/exportpdf_converter_style.adoc[leveloffset=+1]
 
 include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
 

diff --git a/modules/ROOT/pages/exportword.adoc b/modules/ROOT/pages/exportword.adoc
@@ -1,4 +1,4 @@
-= Export to Word
+= {pluginname} plugin
 :navtitle: exportword
 :description: The export to Word feature lets you generate a .docx file directly from the editor.
 :description_short: Generate a .docx file directly from the editor.
@@ -24,7 +24,7 @@ liveDemo::exportword[]
 * xref:introduction-to-mediaembed.adoc[Enhanced Media Embed] will not be included in the exported document, resulting in a console.error _"The Export to Word plugin requires the `exportword_service_url` to be configured"_.
 ====
 
-== Basic setup
+== Basic setup using the {companyname} Cloud service
 
 To add the {pluginname} plugin to the editor, add `{plugincode}` to the `plugins` option in the editor configuration.
 
@@ -36,24 +36,52 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'exportword',
   toolbar: 'exportword',
-  exportword_service_url: 'http://localhost:8080/' // update to your own self-hosted service URL
 });
 ----
 
 [IMPORTANT]
-The `exportword_service_url` option automatically appends `/v2/convert/html-docx` to the URL provided, so only the base URL is required. For example, if the service is hosted at `http://localhost:8080/v2/convert/html-docx`, the `exportword_service_url` option should be set to `http://localhost:8080/`.
+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:
+
+* xref:export-to-word-with-jwt-authentication-nodejs.adoc[Export to Word with JWT authentication].
+* xref:export-to-word-with-jwt-authentication-php.adoc[Export to Word with JWT authentication].
+
+== 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:
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  plugins: 'exportword',
+  toolbar: 'exportword',
+  exportword_service_url: 'http://localhost:8080/' // Update with the URL of the service you are using such  as 'http://myserver.com/'
+});
+----
+
+[IMPORTANT]
+====
+The `exportword_service_url` option automatically appends `/v2/convert/html-docx` to the URL provided, so only the base URL is required. For example, if the service is hosted at `http://localhost:8080/v2/convert/html-docx`, the `exportword_service_url` option should be set to `http://localhost:8080/`. When using in production, ensure that `exportword_service_url` is updated to the production URL such as `https://myserver.com/`.
+====
 
 == Options
 
 The following configuration options affect the behavior of the {pluginname} plugin.
 
-include::partial$configuration/{plugincode}.adoc[leveloffset=+1]
+include::partial$configuration/exportword_service_url.adoc[leveloffset=+1]
+
+include::partial$configuration/exportword_token_provider.adoc[leveloffset=+1]
+
+include::partial$configuration/exportword_converter_options.adoc[leveloffset=+1]
+
+include::partial$configuration/exportword_converter_style.adoc[leveloffset=+1]
 
 == Commands
 
 The {pluginname} plugin provides the following {productname} commands.
 
-include::partial$commands/{plugincode}-cmds.adoc[][leveloffset=+1]
+include::partial$commands/exportword-cmds.adoc[][leveloffset=+1]
 
 == API Reference
 

diff --git a/modules/ROOT/pages/importword.adoc b/modules/ROOT/pages/importword.adoc
@@ -1,5 +1,5 @@
 
-= Import from Word plugin
+= {pluginname} plugin
 :navtitle: Import from Word
 :description: Provides a way to import .docx (Word documents) or .dotx (Word templates) files into the editor.
 :description_short: Import .docx or .dotx files into the editor.
@@ -19,7 +19,7 @@ The {pluginname} plugin lets you import `.docx` (Word document) or `.dotx` (Word
 
 liveDemo::importword[]
 
-== Basic setup
+== Basic setup using the {companyname} Cloud service
 
 To add the {pluginname} plugin to the editor, add `{plugincode}` to the `plugins` option in the editor configuration.
 
@@ -31,17 +31,45 @@ tinymce.init({
   selector: 'textarea',
   plugins: 'importword',
   toolbar: 'importword',
-  importword_service_url: '<service_URL>'
 });
 ----
 
+[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:
+
+* xref:import-to-word-with-jwt-authentication-nodejs.adoc[Import to Word with JWT authentication].
+* xref:import-to-word-with-jwt-authentication-php.adoc[Import to Word with JWT authentication].
+
+== 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:
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  plugins: 'importword',
+  toolbar: 'importword',
+  importword_service_url: 'http://localhost:8080/' // Update with the URL of the service you are using such  as 'http://myserver.com/'
+});
+----
+
+[IMPORTANT]
+====
+The `importword_service_url` option automatically appends `/v2/convert/docx-html` to the URL provided, so only the base URL is required. For example, if the service is hosted at `http://localhost:8080/v2/convert/docx-html`, the `importword_service_url` option should be set to `http://localhost:8080/`. When using in production, ensure that the `importword_service_url` is updated to the production URL such as `https://myserver.com/`.
+====
+
 == Options
 
 The following configuration options affect the behavior of the {pluginname} plugin.
 
-include::partial$configuration/{plugincode}-service-url.adoc[leveloffset=+1]
+include::partial$configuration/importword_service_url.adoc[leveloffset=+1]
+
+include::partial$configuration/importword_token_provider.adoc[leveloffset=+1]
 
-include::partial$configuration/{plugincode}-converter-options.adoc[leveloffset=+1]
+include::partial$configuration/importword_converter_options.adoc[leveloffset=+1]
 
 include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
 
@@ -51,7 +79,7 @@ include::partial$misc/plugin-menu-item-id-boilerplate.adoc[]
 
 The {pluginname} plugin provides the following {productname} commands.
 
-include::partial$commands/{plugincode}-cmds.adoc[]
+include::partial$commands/importword-cmds.adoc[]
 
 == API Reference
 

diff --git a/modules/ROOT/partials/configuration/exportpdf.adoc b/modules/ROOT/partials/configuration/exportpdf.adoc
diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc
@@ -0,0 +1,42 @@
+[[exportpdf-converter-options]]
+== `exportpdf_converter_options`
+
+This option allows the editor to download a PDF document containing its content, along with the specified options defined in the `exportpdf_converter_options`.
+
+**Type:** `+Object+`
+
+[NOTE]
+As of {productname} 7.5.0, the `exportpdf_converter_options` setting now comes with a default value set to the following:
+
+.**Default value:**
+[source,js]
+----
+{
+  format: 'Letter',
+  margin_top: '1in',
+  margin_right: '1in',
+  margin_bottom: '1in',
+  margin_left: '1in'
+}
+----
+
+=== Example: using `exportpdf_converter_options`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  plugins: 'exportpdf',
+  toolbar: 'exportpdf',
+  exportpdf_service_url: '<service_url>', // required if using On-premises service
+  exportpdf_converter_options: {
+   	header_html: '<p>HEADER</p>', // example
+   	header_and_footer_css: 'p { color: blue }', // example
+  },
+})
+----
+
+[NOTE]
+The `exportpdf_service_url` option must be configured for the {pluginname} plugin to work.
+
+> For comprehensive details regarding the `exportpdf_converter_options`, please refer to the https://exportpdf.converter.tiny.cloud/docs[API documentation^] available for the {pluginname} Premium plugin.
diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc
@@ -0,0 +1,29 @@
+[[exportpdf-converter-style]]
+== `exportpdf_converter_style`
+
+The `exportpdf_converter_style` option allow for customization of the styles applied to the exported PDF document, providing flexibility in controlling its appearance.
+
+*Type:* `+String+`
+
+*Default value:* `''`
+
+=== Example: using `exportpdf_converter_style`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea.tinymce',
+  plugins: 'exportpdf',
+  toolbar: 'exportpdf',
+  exportpdf_service_url: '<service_URL>', // required if using On-premises service
+  exportpdf_converter_options: { // required to support "exportpdf_converter_style"
+    header: [
+      {
+        html: '<h1>First page header.</h1>', //example
+        css: 'h1 { font-size: 30px; }', //example
+      }
+    ],
+  },
+  exportpdf_converter_style: 'p { color: cyan !important }' // requires both "exportpdf_converter_style" and "exportpdf_service_url" to be set.
+});
+----