From 91203a22e2c5deecd710c0e9b7deaaa0b34e94cc Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 6 Mar 2026 17:26:33 +1000 Subject: [PATCH 1/4] DOC-3243: Add new exportpdf v2 converter documentation. --- antora.yml | 2 +- .../live-demos/exportpdf-v2/index.html | 78 ++++++++++++ .../examples/live-demos/exportpdf-v2/index.js | 31 +++++ modules/ROOT/nav.adoc | 16 ++- ...pdf-v2-with-jwt-authentication-nodejs.adoc | 73 +++++++++++ ...to-pdf-v2-with-jwt-authentication-php.adoc | 71 +++++++++++ modules/ROOT/pages/exportpdf-v2.adoc | 117 ++++++++++++++++++ modules/ROOT/pages/exportpdf.adoc | 8 +- .../pages/html-to-pdf-converter-api-v2.adoc | 45 +++++++ .../exportpdf_converter_options.adoc | 4 +- .../exportpdf_converter_options_v2.adoc | 91 ++++++++++++++ .../exportpdf_converter_style.adoc | 7 +- 12 files changed, 531 insertions(+), 12 deletions(-) create mode 100644 modules/ROOT/examples/live-demos/exportpdf-v2/index.html create mode 100644 modules/ROOT/examples/live-demos/exportpdf-v2/index.js create mode 100644 modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc create mode 100644 modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-php.adoc create mode 100644 modules/ROOT/pages/exportpdf-v2.adoc create mode 100644 modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc create mode 100644 modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc diff --git a/antora.yml b/antora.yml index bd5735dda8..676022a1ee 100644 --- a/antora.yml +++ b/antora.yml @@ -10,7 +10,7 @@ asciidoc: companyurl: https://www.tiny.cloud cdnurl: https://cdn.tiny.cloud/1/no-api-key/tinymce/8/tinymce.min.js tdcdnurl: https://cdn.tiny.cloud/1/_your_api_key_/tinydrive/8/tinydrive.min.js - tinymce_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinymce/8/tinymce.min.js + tinymce_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinymce/8-dev/tinymce.min.js tinydrive_live_demo_url: https://cdn.tiny.cloud/1/qagffr3pkuv17a8on1afax661irst1hbr4e6tbv888sz91jc/tinydrive/8/tinydrive.min.js webcomponent_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent/dist/tinymce-webcomponent.min.js jquery_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@2/dist/tinymce-jquery.min.js diff --git a/modules/ROOT/examples/live-demos/exportpdf-v2/index.html b/modules/ROOT/examples/live-demos/exportpdf-v2/index.html new file mode 100644 index 0000000000..d016fa3b9e --- /dev/null +++ b/modules/ROOT/examples/live-demos/exportpdf-v2/index.html @@ -0,0 +1,78 @@ + diff --git a/modules/ROOT/examples/live-demos/exportpdf-v2/index.js b/modules/ROOT/examples/live-demos/exportpdf-v2/index.js new file mode 100644 index 0000000000..68fac1e295 --- /dev/null +++ b/modules/ROOT/examples/live-demos/exportpdf-v2/index.js @@ -0,0 +1,31 @@ +tinymce.init({ + selector: 'textarea#exportpdf-v2', + height: '800px', + plugins: [ + "exportpdf", "advlist", "anchor", "autolink", "charmap", "code", "codesample", "fullscreen", + "help", "image", "insertdatetime", "link", "lists", "media", + "preview", "searchreplace", "table", "visualblocks", + ], + toolbar: "undo redo | exportpdf | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image", + image_caption: true, + exportpdf_converter_options: { + version: '2', + document: { + size: 'A4', + orientation: 'portrait', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in', + enable_mirror_margins: true + } + }, + metadata: { + title: 'Streamline LMS Overview', + author: 'TinyMCE', + subject: 'Learning Management System', + keywords: [ 'LMS', 'education', 'Streamline' ] + } + } +}); diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 35fd12a1c3..562b151df2 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -277,11 +277,17 @@ **** xref:mediaembed-server-config.adoc[Configure Enhanced Media Embed Server] **** xref:mediaembed-server-integration.adoc[Integrate Enhanced Media Embed Server] *** xref:advtable.adoc[Enhanced Tables] -*** xref:exportpdf.adoc[Export to PDF] -**** xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API] -**** JWT Authentication -***** xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Node.js] -***** xref:export-to-pdf-with-jwt-authentication-php.adoc[PHP] +*** Export to PDF +**** xref:exportpdf.adoc[Export to PDF v1] +***** xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API] +***** JWT Authentication +****** xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Node.js] +****** xref:export-to-pdf-with-jwt-authentication-php.adoc[PHP] +**** xref:exportpdf-v2.adoc[Export to PDF v2] +***** xref:html-to-pdf-converter-api-v2.adoc[HTML to PDF Converter API v2] +***** JWT Authentication +****** xref:export-to-pdf-v2-with-jwt-authentication-nodejs.adoc[Node.js] +****** xref:export-to-pdf-v2-with-jwt-authentication-php.adoc[PHP] *** xref:exportword.adoc[Export to Word] **** xref:html-to-docx-converter-api.adoc[HTML to DOCX Converter API] **** JWT Authentication diff --git a/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc new file mode 100644 index 0000000000..c413ae9016 --- /dev/null +++ b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc @@ -0,0 +1,73 @@ += {pluginname} with JWT authentication (Node.js) Guide – (v2) +:plugincode: exportpdf +:pluginname: Export to PDF +:navtitle: JWT Authentication setup for {pluginname} v2 +:description: Guide on how to setup JWT Authentication for exporting PDF files with {pluginname} (version 2) +:keywords: jwt, authentication, exportpdf, pdf, node.js, v2 + + +include::partial$auth/document-converters/nodejs/intro-and-prerequisites.adoc[] + +include::partial$auth/document-converters/nodejs/initial-project-setup.adoc[] + +== Setup + +=== Generate a Public/Private Key Pair + +include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+2] + +include::partial$auth/document-converters/nodejs/server-setup-jwt.adoc[] + +=== Web Page (public/index.html) + +Inside the `public` folder where you created the `index.html` file add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with Export to PDF v2 + + + + +

TinyMCE Export to PDF Demo (v2)

+ + + +---- + +include::partial$auth/document-converters/nodejs/configuration-steps.adoc[] diff --git a/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-php.adoc b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-php.adoc new file mode 100644 index 0000000000..cbc9881f7e --- /dev/null +++ b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-php.adoc @@ -0,0 +1,71 @@ += {pluginname} with JWT authentication (PHP) Guide – (v2) +:navtitle: JWT Authentication setup for Export to PDF v2 +:description: Guide on how to setup JWT Authentication for exporting PDF files with {productname} (version 2) +:keywords: jwt, authentication, exportpdf, pdf, php, v2 +:pluginname: Export to PDF +:plugincode: exportpdf + +include::partial$auth/document-converters/php/intro-and-prerequisites.adoc[] + +include::partial$auth/document-converters/php/initial-project-setup.adoc[] + +== Setup + +=== Generate a Public/Private Key Pair + +include::partial$auth/document-converters/jwt-setup-document-converters.adoc[leveloffset=+2] + +include::partial$auth/document-converters/php/server-setup-php.adoc[] + +=== Web Page Setup (index.html) + +Inside the `public` folder where you created the `index.html` file add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with PDF Export (v2) + + + + +

TinyMCE Export to PDF Demo (v2)

+ + + +---- + +include::partial$auth/document-converters/php/configuration-steps.adoc[] diff --git a/modules/ROOT/pages/exportpdf-v2.adoc b/modules/ROOT/pages/exportpdf-v2.adoc new file mode 100644 index 0000000000..cc1f789f00 --- /dev/null +++ b/modules/ROOT/pages/exportpdf-v2.adoc @@ -0,0 +1,117 @@ += {pluginname} plugin (v2) +:plugincode: exportpdf +:pluginname: Export to PDF +:pluginfilename: export-to-pdf-v2 +:navtitle: Export to PDF v2 +:description: The {pluginname} feature provides the ability to generate a PDF file directly from the editor using the nested configuration structure. +:description_short: Generate a PDF file directly from the editor. +:keywords: plugin, {plugincode}, {pluginname} +:plugincategory: premium + + +include::partial$misc/admon-export-pdf-paid-addon-pricing.adoc[] + +The {pluginname} feature collects the HTML generated with the `tinymce.editor.getContent()` method and combines it with the default editor content styles along with the styles provided in the plugin configuration. The combined content and styles are then processed by the included server-side converter service, which can be either self-hosted or cloud-based. Following this processing, a PDF file is generated, which is subsequently returned to the user's browser, enabling them to save it onto their disk or drive. + +== Interactive example + +liveDemo::exportpdf-v2[] + +== 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. + +.Example: +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + // Required for the cloud-based Export to PDF plugin with Tiny Cloud + // Create a JWT key in the Customer Portal for trial functionality to enable watermark-free exports 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()); + }, + exportpdf_converter_options: { + version: '2', + document: { + size: 'Letter', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in' + } + } + } +}); +---- + +For more information on the exportpdf_token_provider option, see xref:exportpdf-v2.adoc#exportpdf-token-provider[exportpdf_token_provider]. + +include::partial$misc/admon-jwt-authentication-requirements.adoc[] + + +== 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. + +.Example: +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + exportpdf_service_url: 'http://localhost:8080/', + exportpdf_converter_options: { + version: '2', + document: { + size: 'Letter', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in' + } + } + } +}); +---- + +[IMPORTANT] +The `exportpdf_service_url` option automatically appends `/v2/convert/html-pdf` 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-pdf`, 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/`. + +== Additional Configuration + +include::partial$misc/pagebreak-export-note.adoc[] + +== Options + +The following configuration options affect the behavior of the {pluginname} plugin. + +include::partial$configuration/exportpdf_service_url.adoc[leveloffset=+1] + +include::partial$configuration/exportpdf_token_provider.adoc[leveloffset=+1] + +include::partial$configuration/exportpdf_converter_options_v2.adoc[leveloffset=+1] + +include::partial$configuration/exportpdf_converter_style.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[] + +== API Reference + +> Explore the comprehensive API documentation for the {pluginname} Premium plugin at https://exportpdf.api.tiny.cloud/v2/convert/docs[{pluginname} API Reference Documentation.^] diff --git a/modules/ROOT/pages/exportpdf.adoc b/modules/ROOT/pages/exportpdf.adoc index 7bdb1c607e..a991d2a689 100644 --- a/modules/ROOT/pages/exportpdf.adoc +++ b/modules/ROOT/pages/exportpdf.adoc @@ -2,7 +2,7 @@ :plugincode: exportpdf :pluginname: Export to PDF :pluginfilename: export-to-pdf -:navtitle: {pluginname} +:navtitle: Export to PDF v1 :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. :keywords: plugin, {plugincode}, {pluginname} @@ -13,6 +13,8 @@ include::partial$misc/admon-export-pdf-paid-addon-pricing.adoc[] The {pluginname} feature collects the HTML generated with the `tinymce.editor.getContent()` method and combines it with the default editor content styles along with the styles provided in the plugin configuration. The combined content and styles are then processed by the included server-side converter service, which can be either self-hosted or cloud-based. Following this processing, a PDF file is generated, which is subsequently returned to the user's browser, enabling them to save it onto their disk or drive. +NOTE: Version 1 of the {pluginname} plugin uses the flat configuration structure for backward compatibility. To use the `/latest` version of the {pluginname} plugin, see xref:exportpdf-v2.adoc[Export to PDF v2]. + == Interactive example liveDemo::exportpdf[] @@ -39,7 +41,7 @@ tinymce.init({ }); ---- -For more infomation on the exportpdf_token_provider option, see xref:exportpdf.adoc#exportpdf-token-provider[exportpdf_token_provider]. +For more information on the exportpdf_token_provider option, see xref:exportpdf.adoc#exportpdf-token-provider[exportpdf_token_provider]. include::partial$misc/admon-jwt-authentication-requirements.adoc[] @@ -61,7 +63,7 @@ tinymce.init({ [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/`. +The `exportpdf_service_url` option automatically appends `/v2/convert/html-pdf` 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-pdf`, 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/`. ==== == Additional Configuration diff --git a/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc b/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc new file mode 100644 index 0000000000..a94db65f1a --- /dev/null +++ b/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc @@ -0,0 +1,45 @@ += HTML to PDF Converter API (version 2) +:navtitle: Export to PDF Standalone Service v2 +:description: The HTML to PDF Converter API v2 service feature provides the ability to generate PDF files directly without the need for an editor. +:description_short: Generate a .pdf file directly from any application (version 2). +:keywords: service, exportpdf, export to pdf, HTML to PDF Converter API, v2, version 2 +:pluginname: Export to PDF +:servicename: HTML to PDF Converter API (v2) + +[NOTE] +This is a premium feature. link:https://www.tiny.cloud/contact/[Contact us] to purchase a license or to learn more about our tailored offers. Note that any documents generated without authentication will be watermarked. + +== Overview + +The {servicename} is a powerful tool that seamlessly integrates advanced document conversion capabilities into developers workflows. This API allows for the efficient conversion of HTML content into PDF documents, catering to a wide range of use cases. + +Version 2 uses a nested configuration structure and supports per-page headers and footers, PDF metadata, security, and digital signatures. For version 1, see xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API]. + +=== Key Features + +* **Versatile Document Conversion**: Convert HTML content into high-quality PDF documents, providing flexibility for various document needs. +* **Preprocessing Capabilities**: Pre-process content before conversion, such as resolving merge tags, ensuring fully customized and ready-to-use PDF documents. +* **Customizable Output**: Tailor the appearance and structure of the converted PDFs with customizable output xref:html-to-pdf-converter-api-v2.adoc#options[options], including page sizes, margins, and formatting. +* **Scalability**: Handle large volumes of PDF documents with consistent performance and reliability, supporting business growth and varying demands. +* **Ease of Integration**: Integrate the API into existing workflows easily with comprehensive documentation and straightforward API endpoints. +* **Security and Compliance**: Ensure secure document conversion processes that adhere to data protection standards and industry regulations, crucial for handling sensitive information. + +[[options]] +== Flexible Configuration Options + +Tailor your PDF documents to suit your needs: + +* **Custom CSS Styling:** Apply link:https://exportpdf.api.tiny.cloud/v2/convert/docs#section/General/CSS[custom CSS^] styles to your PDFs for brand consistency and enhanced presentation. +* **Header and Footer Options:** Add link:https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Headers-and-footers[headers and footers^], and other branding elements to your PDF documents for a professional touch. +* **Page Formatting:** Control page settings such as orientation, link:https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Document[document^] (margins, size), and link:https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Metadata[metadata^] to optimize readability. + +== Ideal for Various Use Cases + +* **Aggregating Content from Multiple Sources**: Combine content from various editors into a single cohesive PDF document, simplifying content management for organizations using multiple tools. +* **Centralized Document Management**: Store generated PDF documents centrally for better organization and accessibility, facilitating team collaboration and efficient document retrieval. +* **Preprocessing and Customization**: Pre-process content to resolve merge tags and customize PDF document formatting, ensuring that the final output meets specific requirements and is ready for immediate use. +* **Large-Scale Document Processing**: Utilize the API's scalability to handle large volumes of PDF documents, maintaining consistent performance and reliability, essential for growing businesses. + +== PDF Converter API Reference + +> Explore the comprehensive API documentation at link:https://exportpdf.api.tiny.cloud/v2/convert/docs[PDF Converter API Reference documentation.^] diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc index 667d77a730..9286ee3d6f 100644 --- a/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc +++ b/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc @@ -30,8 +30,8 @@ tinymce.init({ toolbar: 'exportpdf', exportpdf_service_url: '', // required if using On-premises service exportpdf_converter_options: { - header_html: '

HEADER

', // example - header_and_footer_css: 'p { color: blue }', // example + header_html: '

HEADER

', // example + header_and_footer_css: 'p { color: blue }', // example }, }) ---- diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc new file mode 100644 index 0000000000..469b43cada --- /dev/null +++ b/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc @@ -0,0 +1,91 @@ +[[exportpdf-converter-options-v2]] +== `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+` + +Set `version: '2'` to use the nested structure and access features such as per-page headers and footers, PDF metadata, security, and digital signatures. + +.**Default value:** +[source,js] +---- +{ + version: '2', + document: { + size: 'Letter', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in' + } + } +} +---- + +**Main option groups:** + +[cols="1,3",options="header"] +|=== +| Option | Description +| `document` | Page size, orientation, and margins +| `headers` / `footers` | Per-page headers and footers (`default`, `first`, `odd`, `even`) with `html` and `css` +| `metadata` | PDF metadata (`title`, `author`, `subject`, `keywords` array, `custom_fields`) +|=== + +Other options: `rendering` (wait_for_network, wait_time), `security` (owner_password), `signature` (certificate, certificate_password), `base_url`, `extra_http_headers`, `disable_compression`. Security and signature cannot be used together. + +For full details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Configuration[PDF Converter API documentation^]. + +.Example: per-page headers and footers +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + exportpdf_service_url: '', + exportpdf_converter_options: { + version: '2', + document: { + size: 'Letter', + orientation: 'portrait', + margins: { + top: '2cm', + bottom: '2cm', + left: '1cm', + right: '3cm', + enable_mirror_margins: true + } + }, + headers: { + default: { html: '

HEADER

', css: 'p { color: blue }' }, + first: { html: '

FIRST PAGE

', css: 'p { font-weight: bold }' } + }, + footers: { + default: { html: '

FOOTER

', css: 'p { color: green }' } + } + }, +}); +---- + +.Example: metadata +[source,js] +---- +exportpdf_converter_options: { + version: '2', + metadata: { + title: 'My Document', + author: 'John Doe', + subject: 'Quarterly Report', + keywords: [ 'report', '2024', 'sales' ], + custom_fields: { 'Department': 'Sales' } + } +} +---- + +[NOTE] +The `exportpdf_service_url` option must be configured for the {pluginname} plugin to work. + +> For comprehensive details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs[PDF Converter API documentation^]. For migration guidance from v1 to v2, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Migration-guide-from-v1-to-v2[migration guide^]. diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc index bab144bf40..0c02506a6f 100644 --- a/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc +++ b/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc @@ -29,7 +29,12 @@ tinymce.init({ ---- [TIP] -Watermarks can be added to exported PDF documents using CSS. Add the watermark styles to the `exportpdf_converter_style` option, targeting `body::after` instead of `#tinymce::after` for proper rendering. For more information see: link:https://exportpdf.converter.tiny.cloud/docs#section/General/CSS[General/CSS]. +==== +Watermarks can be added to exported PDF documents using CSS. + +* Add the watermark styles to the `exportpdf_converter_style` option, targeting **`body::after`** instead of **`#tinymce::after`** for proper rendering. +* For more information see: link:https://exportpdf.converter.tiny.cloud/docs#section/General/CSS[General/CSS]. +==== === Example: Adding watermarks to exported PDF documents From 2d6ca3736b5f7a53d2a083397a24656c84cb08f9 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 6 Mar 2026 17:38:29 +1000 Subject: [PATCH 2/4] DOC-3243: Add release notes. --- modules/ROOT/pages/8.4.0-release-notes.adoc | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/8.4.0-release-notes.adoc b/modules/ROOT/pages/8.4.0-release-notes.adoc index 45dc460ba9..d139e8cb48 100644 --- a/modules/ROOT/pages/8.4.0-release-notes.adoc +++ b/modules/ROOT/pages/8.4.0-release-notes.adoc @@ -57,17 +57,18 @@ For information on the **** plugin, see xref: +=== Export to PDF -The {productname} {release-version} release includes an accompanying release of the **** premium plugin. +The {productname} {release-version} release includes an accompanying release of the **Export to PDF** premium plugin. -**** includes the following . +**Export to PDF** includes the following addition. -==== +==== exportpdf supports API version 2 converter options +// #TINY-13700 -// CCFR here. +`{productname}` `{release-version}` adds support for version `2` of the `exportpdf` API through `exportpdf_converter_options`. Version `1` remains the default for backward compatibility. The new nested structure organizes options under `document`, `headers`, `footers`, `metadata`, `security`, and `signature`, enabling per-page headers and footers, PDF metadata, password protection, and certificate-based signing. -For information on the **** plugin, see: xref:.adoc[]. +For information on the **Export to PDF** plugin, see: xref:exportpdf-v2.adoc[Export to PDF v2] and xref:exportpdf.adoc[Export to PDF v1]. [[accompanying-premium-plugin-end-of-life-announcement]] From 6b230d89f3be77179f7b7a325975ff417498b44e Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 11 Mar 2026 15:32:56 +1000 Subject: [PATCH 3/4] DOC-3243: Consolidate Export to PDF docs, improve clarity - Merge exportpdf and exportpdf-v2 into single plugin page - Add backwards compatibility and conversion section - Add exportpdf_converter_options_combined partial (flat + nested formats) - Side-by-side demos (flat vs nested) in single exportpdf demo - Update JWT guides: remove v2 branding, add 8.4.0+ note, link to v1 for pre-8.4.0 - Add v1 JWT guides to nav (pre-8.4.0) - Rename HTML to PDF Converter API v2 to HTML to PDF Converter API - Fix exportpdf_converter_style example (invalid header structure) - Remove orphaned exportpdf_converter_options and exportpdf_converter_options_v2 partials --- .../examples/live-demos/exportpdf/index.html | 90 ++++++++++- .../examples/live-demos/exportpdf/index.js | 34 +++- modules/ROOT/nav.adoc | 15 +- modules/ROOT/pages/8.4.0-release-notes.adoc | 2 +- ...pdf-v2-with-jwt-authentication-nodejs.adoc | 21 ++- ...to-pdf-v2-with-jwt-authentication-php.adoc | 21 ++- modules/ROOT/pages/exportpdf-v2.adoc | 117 -------------- modules/ROOT/pages/exportpdf.adoc | 15 +- .../pages/html-to-pdf-converter-api-v2.adoc | 14 +- .../exportpdf_converter_options.adoc | 42 ----- .../exportpdf_converter_options_combined.adoc | 150 ++++++++++++++++++ .../exportpdf_converter_options_v2.adoc | 91 ----------- .../exportpdf_converter_style.adoc | 10 +- 13 files changed, 329 insertions(+), 293 deletions(-) delete mode 100644 modules/ROOT/pages/exportpdf-v2.adoc delete mode 100644 modules/ROOT/partials/configuration/exportpdf_converter_options.adoc create mode 100644 modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc delete mode 100644 modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc diff --git a/modules/ROOT/examples/live-demos/exportpdf/index.html b/modules/ROOT/examples/live-demos/exportpdf/index.html index 6dd3537e02..0d0ec28f2d 100644 --- a/modules/ROOT/examples/live-demos/exportpdf/index.html +++ b/modules/ROOT/examples/live-demos/exportpdf/index.html @@ -1,4 +1,7 @@ - \ No newline at end of file + + +
+

Nested format (v2)

+ +
+ diff --git a/modules/ROOT/examples/live-demos/exportpdf/index.js b/modules/ROOT/examples/live-demos/exportpdf/index.js index 04bec75035..c5de2fc6d7 100644 --- a/modules/ROOT/examples/live-demos/exportpdf/index.js +++ b/modules/ROOT/examples/live-demos/exportpdf/index.js @@ -1,5 +1,5 @@ tinymce.init({ - selector: 'textarea#exportpdf', + selector: 'textarea.exportpdf-flat', height: '800px', plugins: [ "exportpdf", "advlist", "anchor", "autolink", "charmap", "code", "codesample", "fullscreen", @@ -16,3 +16,35 @@ tinymce.init({ margin_left: '1in' } }); + +tinymce.init({ + selector: 'textarea.exportpdf-nested', + height: '800px', + plugins: [ + "exportpdf", "advlist", "anchor", "autolink", "charmap", "code", "codesample", "fullscreen", + "help", "image", "insertdatetime", "link", "lists", "media", + "preview", "searchreplace", "table", "visualblocks", + ], + toolbar: "undo redo | exportpdf | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image", + image_caption: true, + exportpdf_converter_options: { + version: '2', + document: { + size: 'A4', + orientation: 'portrait', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in', + enable_mirror_margins: true + } + }, + metadata: { + title: 'Streamline LMS Overview', + author: 'TinyMCE', + subject: 'Learning Management System', + keywords: [ 'LMS', 'education', 'Streamline' ] + } + } +}); diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 562b151df2..f72ccecb45 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -278,16 +278,13 @@ **** xref:mediaembed-server-integration.adoc[Integrate Enhanced Media Embed Server] *** xref:advtable.adoc[Enhanced Tables] *** Export to PDF -**** xref:exportpdf.adoc[Export to PDF v1] -***** xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API] +**** xref:exportpdf.adoc[Export to PDF] +***** xref:html-to-pdf-converter-api-v2.adoc[HTML to PDF Converter API] ***** JWT Authentication -****** xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Node.js] -****** xref:export-to-pdf-with-jwt-authentication-php.adoc[PHP] -**** xref:exportpdf-v2.adoc[Export to PDF v2] -***** xref:html-to-pdf-converter-api-v2.adoc[HTML to PDF Converter API v2] -***** JWT Authentication -****** xref:export-to-pdf-v2-with-jwt-authentication-nodejs.adoc[Node.js] -****** xref:export-to-pdf-v2-with-jwt-authentication-php.adoc[PHP] +****** xref:export-to-pdf-v2-with-jwt-authentication-nodejs.adoc[Node.js (8.4.0+)] +****** xref:export-to-pdf-v2-with-jwt-authentication-php.adoc[PHP (8.4.0+)] +****** xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[Node.js (pre-8.4.0)] +****** xref:export-to-pdf-with-jwt-authentication-php.adoc[PHP (pre-8.4.0)] *** xref:exportword.adoc[Export to Word] **** xref:html-to-docx-converter-api.adoc[HTML to DOCX Converter API] **** JWT Authentication diff --git a/modules/ROOT/pages/8.4.0-release-notes.adoc b/modules/ROOT/pages/8.4.0-release-notes.adoc index d139e8cb48..47d90a4c5c 100644 --- a/modules/ROOT/pages/8.4.0-release-notes.adoc +++ b/modules/ROOT/pages/8.4.0-release-notes.adoc @@ -68,7 +68,7 @@ The {productname} {release-version} release includes an accompanying release of `{productname}` `{release-version}` adds support for version `2` of the `exportpdf` API through `exportpdf_converter_options`. Version `1` remains the default for backward compatibility. The new nested structure organizes options under `document`, `headers`, `footers`, `metadata`, `security`, and `signature`, enabling per-page headers and footers, PDF metadata, password protection, and certificate-based signing. -For information on the **Export to PDF** plugin, see: xref:exportpdf-v2.adoc[Export to PDF v2] and xref:exportpdf.adoc[Export to PDF v1]. +For information on the **Export to PDF** plugin, see xref:exportpdf.adoc[Export to PDF]. [[accompanying-premium-plugin-end-of-life-announcement]] diff --git a/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc index c413ae9016..e5ad951ee4 100644 --- a/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc +++ b/modules/ROOT/pages/export-to-pdf-v2-with-jwt-authentication-nodejs.adoc @@ -1,13 +1,18 @@ -= {pluginname} with JWT authentication (Node.js) Guide – (v2) += {pluginname} with JWT authentication (Node.js) Guide :plugincode: exportpdf :pluginname: Export to PDF -:navtitle: JWT Authentication setup for {pluginname} v2 -:description: Guide on how to setup JWT Authentication for exporting PDF files with {pluginname} (version 2) -:keywords: jwt, authentication, exportpdf, pdf, node.js, v2 +:navtitle: JWT Authentication setup for {pluginname} +:description: Guide on how to set up JWT authentication for exporting PDF files with {pluginname} using Node.js +:keywords: jwt, authentication, exportpdf, pdf, node.js include::partial$auth/document-converters/nodejs/intro-and-prerequisites.adoc[] +[NOTE] +==== +This guide uses the nested format (`version: '2'`) for `exportpdf_converter_options`. Requires {productname} 8.4.0 or newer. For full option documentation, see xref:exportpdf.adoc[Export to PDF]. For integrators on older versions, see xref:export-to-pdf-with-jwt-authentication-nodejs.adoc[JWT Authentication setup for Export to PDF (Node.js) – flat format]. +==== + include::partial$auth/document-converters/nodejs/initial-project-setup.adoc[] == Setup @@ -27,7 +32,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML - TinyMCE with Export to PDF v2 + TinyMCE with Export to PDF -

TinyMCE Export to PDF Demo (v2)

+

TinyMCE Export to PDF Demo

@@ -69,3 +74,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML ---- include::partial$auth/document-converters/php/configuration-steps.adoc[] + +== Further configuration + +For additional options such as per-page headers and footers, PDF metadata, and security settings, see the xref:exportpdf.adoc#exportpdf-converter-options[`exportpdf_converter_options`] section on the Export to PDF plugin page. diff --git a/modules/ROOT/pages/exportpdf-v2.adoc b/modules/ROOT/pages/exportpdf-v2.adoc deleted file mode 100644 index cc1f789f00..0000000000 --- a/modules/ROOT/pages/exportpdf-v2.adoc +++ /dev/null @@ -1,117 +0,0 @@ -= {pluginname} plugin (v2) -:plugincode: exportpdf -:pluginname: Export to PDF -:pluginfilename: export-to-pdf-v2 -:navtitle: Export to PDF v2 -:description: The {pluginname} feature provides the ability to generate a PDF file directly from the editor using the nested configuration structure. -:description_short: Generate a PDF file directly from the editor. -:keywords: plugin, {plugincode}, {pluginname} -:plugincategory: premium - - -include::partial$misc/admon-export-pdf-paid-addon-pricing.adoc[] - -The {pluginname} feature collects the HTML generated with the `tinymce.editor.getContent()` method and combines it with the default editor content styles along with the styles provided in the plugin configuration. The combined content and styles are then processed by the included server-side converter service, which can be either self-hosted or cloud-based. Following this processing, a PDF file is generated, which is subsequently returned to the user's browser, enabling them to save it onto their disk or drive. - -== Interactive example - -liveDemo::exportpdf-v2[] - -== 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. - -.Example: -[source,js] ----- -tinymce.init({ - selector: 'textarea', - plugins: 'exportpdf', - toolbar: 'exportpdf', - // Required for the cloud-based Export to PDF plugin with Tiny Cloud - // Create a JWT key in the Customer Portal for trial functionality to enable watermark-free exports 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()); - }, - exportpdf_converter_options: { - version: '2', - document: { - size: 'Letter', - margins: { - top: '1in', - right: '1in', - bottom: '1in', - left: '1in' - } - } - } -}); ----- - -For more information on the exportpdf_token_provider option, see xref:exportpdf-v2.adoc#exportpdf-token-provider[exportpdf_token_provider]. - -include::partial$misc/admon-jwt-authentication-requirements.adoc[] - - -== 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. - -.Example: -[source,js] ----- -tinymce.init({ - selector: 'textarea', - plugins: 'exportpdf', - toolbar: 'exportpdf', - exportpdf_service_url: 'http://localhost:8080/', - exportpdf_converter_options: { - version: '2', - document: { - size: 'Letter', - margins: { - top: '1in', - right: '1in', - bottom: '1in', - left: '1in' - } - } - } -}); ----- - -[IMPORTANT] -The `exportpdf_service_url` option automatically appends `/v2/convert/html-pdf` 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-pdf`, 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/`. - -== Additional Configuration - -include::partial$misc/pagebreak-export-note.adoc[] - -== Options - -The following configuration options affect the behavior of the {pluginname} plugin. - -include::partial$configuration/exportpdf_service_url.adoc[leveloffset=+1] - -include::partial$configuration/exportpdf_token_provider.adoc[leveloffset=+1] - -include::partial$configuration/exportpdf_converter_options_v2.adoc[leveloffset=+1] - -include::partial$configuration/exportpdf_converter_style.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[] - -== API Reference - -> Explore the comprehensive API documentation for the {pluginname} Premium plugin at https://exportpdf.api.tiny.cloud/v2/convert/docs[{pluginname} API Reference Documentation.^] diff --git a/modules/ROOT/pages/exportpdf.adoc b/modules/ROOT/pages/exportpdf.adoc index a991d2a689..9ac9700f0f 100644 --- a/modules/ROOT/pages/exportpdf.adoc +++ b/modules/ROOT/pages/exportpdf.adoc @@ -2,7 +2,7 @@ :plugincode: exportpdf :pluginname: Export to PDF :pluginfilename: export-to-pdf -:navtitle: Export to PDF v1 +:navtitle: Export to PDF :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. :keywords: plugin, {plugincode}, {pluginname} @@ -13,7 +13,14 @@ include::partial$misc/admon-export-pdf-paid-addon-pricing.adoc[] The {pluginname} feature collects the HTML generated with the `tinymce.editor.getContent()` method and combines it with the default editor content styles along with the styles provided in the plugin configuration. The combined content and styles are then processed by the included server-side converter service, which can be either self-hosted or cloud-based. Following this processing, a PDF file is generated, which is subsequently returned to the user's browser, enabling them to save it onto their disk or drive. -NOTE: Version 1 of the {pluginname} plugin uses the flat configuration structure for backward compatibility. To use the `/latest` version of the {pluginname} plugin, see xref:exportpdf-v2.adoc[Export to PDF v2]. +== Backwards compatibility and conversion + +The plugin always uses the v2 API endpoint (`/v2/convert/html-pdf`). Two option formats are supported: + +* **Flat format** – Top-level properties such as `format`, `margin_top`, `header_html`, and `footer_html`. Existing integrations using this format continue to work without changes. The plugin converts flat options to the nested structure automatically before the request. +* **Nested format** – Set `version: '2'` to use the nested structure and access features such as per-page headers and footers, PDF metadata, security, and digital signatures. + +Both formats produce equivalent output when configured for the same result. Requires {productname} 8.4.0 or newer for v2 API support and automatic conversion. == Interactive example @@ -78,7 +85,7 @@ 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_options_combined.adoc[leveloffset=+1] include::partial$configuration/exportpdf_converter_style.adoc[leveloffset=+1] @@ -94,4 +101,4 @@ include::partial$commands/{plugincode}-cmds.adoc[] == API Reference -> Explore the comprehensive API documentation for the {pluginname} Premium plugin at https://exportpdf.api.tiny.cloud/v1/convert/docs[{pluginname} API Reference Documentation.^] +> Explore the comprehensive API documentation for the {pluginname} Premium plugin at https://exportpdf.api.tiny.cloud/v2/convert/docs[{pluginname} API Reference Documentation.^] diff --git a/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc b/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc index a94db65f1a..ba9bbf49c2 100644 --- a/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc +++ b/modules/ROOT/pages/html-to-pdf-converter-api-v2.adoc @@ -1,10 +1,10 @@ -= HTML to PDF Converter API (version 2) -:navtitle: Export to PDF Standalone Service v2 -:description: The HTML to PDF Converter API v2 service feature provides the ability to generate PDF files directly without the need for an editor. -:description_short: Generate a .pdf file directly from any application (version 2). -:keywords: service, exportpdf, export to pdf, HTML to PDF Converter API, v2, version 2 += HTML to PDF Converter API +:navtitle: HTML to PDF Converter API +:description: The HTML to PDF Converter API service provides the ability to generate PDF files directly without the need for an editor. +:description_short: Generate a .pdf file directly from any application. +:keywords: service, exportpdf, export to pdf, HTML to PDF Converter API :pluginname: Export to PDF -:servicename: HTML to PDF Converter API (v2) +:servicename: HTML to PDF Converter API [NOTE] This is a premium feature. link:https://www.tiny.cloud/contact/[Contact us] to purchase a license or to learn more about our tailored offers. Note that any documents generated without authentication will be watermarked. @@ -13,7 +13,7 @@ This is a premium feature. link:https://www.tiny.cloud/contact/[Contact us] to p The {servicename} is a powerful tool that seamlessly integrates advanced document conversion capabilities into developers workflows. This API allows for the efficient conversion of HTML content into PDF documents, catering to a wide range of use cases. -Version 2 uses a nested configuration structure and supports per-page headers and footers, PDF metadata, security, and digital signatures. For version 1, see xref:html-to-pdf-converter-api.adoc[HTML to PDF Converter API]. +The API uses a nested configuration structure and supports per-page headers and footers, PDF metadata, security, and digital signatures. === Key Features diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc deleted file mode 100644 index 9286ee3d6f..0000000000 --- a/modules/ROOT/partials/configuration/exportpdf_converter_options.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[[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: '', // required if using On-premises service - exportpdf_converter_options: { - header_html: '

HEADER

', // 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.api.tiny.cloud/v1/convert/docs[API documentation^] available for the {pluginname} Premium plugin. \ No newline at end of file diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc new file mode 100644 index 0000000000..48f5e2699d --- /dev/null +++ b/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc @@ -0,0 +1,150 @@ +[[exportpdf-converter-options]] +== `exportpdf_converter_options` + +Configures page layout, headers, footers, and other PDF output options. The editor sends this configuration to the converter service when exporting. + +**Type:** `+Object+` + +[TIP] +==== +**Which format to use** + +* **Flat format** – Use for existing integrations (no changes required) or when a simple structure is preferred. Properties such as `format`, `margin_top`, `header_html` at the top level. +* **Nested format** – Use for new integrations or when per-page headers, PDF metadata, security, or digital signatures are needed. Set `version: '2'` and organize options under `document`, `headers`, `footers`, `metadata`. +==== + +Both formats use the same API endpoint. Flat-format options are converted to the nested structure automatically before the request. + +[NOTE] +Requires {productname} 8.4.0 or newer. + +=== Flat format + +Top-level properties: `format`, `margin_top`, `margin_right`, `margin_bottom`, `margin_left`, `header_html`, `footer_html`, `header_and_footer_css`, `page_orientation`, `wait_for_network`, `wait_time`, `base_url`, `extra_http_headers`. Supported for backward compatibility. + +[NOTE] +As of {productname} 7.5.0, the `exportpdf_converter_options` setting now comes with a default value set to the following: + +.**Default value (flat format):** +[source,js] +---- +{ + format: 'Letter', + margin_top: '1in', + margin_right: '1in', + margin_bottom: '1in', + margin_left: '1in' +} +---- + +.Example: flat format +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + exportpdf_service_url: '', // required if using On-premises service + exportpdf_converter_options: { + header_html: '

HEADER

', // example + header_and_footer_css: 'p { color: blue }', // example + }, +}) +---- + +=== Nested format + +Set `version: '2'` to use the nested structure. Access per-page headers and footers, PDF metadata, security, and digital signatures. + +.**Default value (nested format):** +[source,js] +---- +{ + version: '2', + document: { + size: 'Letter', + margins: { + top: '1in', + right: '1in', + bottom: '1in', + left: '1in' + } + } +} +---- + +**Main option groups:** + +[cols="1,3",options="header"] +|=== +| Option | Description +| `document` | Page size, orientation, and margins +| `headers` / `footers` | Per-page headers and footers (`default`, `first`, `odd`, `even`) with `html` and `css` +| `metadata` | PDF metadata (`title`, `author`, `subject`, `keywords` array, `custom_fields`) +|=== + +**Additional options:** + +* `rendering` – `wait_for_network`, `wait_time` +* `security` – `owner_password` (password protection) +* `signature` – `certificate`, `certificate_password` (digital signing; cannot be used with `security`) +* `base_url`, `extra_http_headers`, `disable_compression` + +For full details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Configuration[PDF Converter API documentation^]. + +.Example: per-page headers and footers +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + exportpdf_service_url: '', + exportpdf_converter_options: { + version: '2', + document: { + size: 'Letter', + orientation: 'portrait', + margins: { + top: '2cm', + bottom: '2cm', + left: '1cm', + right: '3cm', + enable_mirror_margins: true + } + }, + headers: { + default: { html: '

HEADER

', css: 'p { color: blue }' }, + first: { html: '

FIRST PAGE

', css: 'p { font-weight: bold }' } + }, + footers: { + default: { html: '

FOOTER

', css: 'p { color: green }' } + } + }, +}); +---- + +.Example: metadata +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'exportpdf', + toolbar: 'exportpdf', + exportpdf_converter_options: { + version: '2', + metadata: { + title: 'My Document', + author: 'John Doe', + subject: 'Quarterly Report', + keywords: [ 'report', '2024', 'sales' ], + custom_fields: { 'Department': 'Sales' } + } + } +}); +---- + +[NOTE] +The `exportpdf_service_url` option must be configured for the {pluginname} plugin to work. + +> For comprehensive details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs[PDF Converter API documentation^]. For migration guidance from flat to nested format, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Migration-guide-from-v1-to-v2[migration guide^]. diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc deleted file mode 100644 index 469b43cada..0000000000 --- a/modules/ROOT/partials/configuration/exportpdf_converter_options_v2.adoc +++ /dev/null @@ -1,91 +0,0 @@ -[[exportpdf-converter-options-v2]] -== `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+` - -Set `version: '2'` to use the nested structure and access features such as per-page headers and footers, PDF metadata, security, and digital signatures. - -.**Default value:** -[source,js] ----- -{ - version: '2', - document: { - size: 'Letter', - margins: { - top: '1in', - right: '1in', - bottom: '1in', - left: '1in' - } - } -} ----- - -**Main option groups:** - -[cols="1,3",options="header"] -|=== -| Option | Description -| `document` | Page size, orientation, and margins -| `headers` / `footers` | Per-page headers and footers (`default`, `first`, `odd`, `even`) with `html` and `css` -| `metadata` | PDF metadata (`title`, `author`, `subject`, `keywords` array, `custom_fields`) -|=== - -Other options: `rendering` (wait_for_network, wait_time), `security` (owner_password), `signature` (certificate, certificate_password), `base_url`, `extra_http_headers`, `disable_compression`. Security and signature cannot be used together. - -For full details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Configuration[PDF Converter API documentation^]. - -.Example: per-page headers and footers -[source,js] ----- -tinymce.init({ - selector: 'textarea', - plugins: 'exportpdf', - toolbar: 'exportpdf', - exportpdf_service_url: '', - exportpdf_converter_options: { - version: '2', - document: { - size: 'Letter', - orientation: 'portrait', - margins: { - top: '2cm', - bottom: '2cm', - left: '1cm', - right: '3cm', - enable_mirror_margins: true - } - }, - headers: { - default: { html: '

HEADER

', css: 'p { color: blue }' }, - first: { html: '

FIRST PAGE

', css: 'p { font-weight: bold }' } - }, - footers: { - default: { html: '

FOOTER

', css: 'p { color: green }' } - } - }, -}); ----- - -.Example: metadata -[source,js] ----- -exportpdf_converter_options: { - version: '2', - metadata: { - title: 'My Document', - author: 'John Doe', - subject: 'Quarterly Report', - keywords: [ 'report', '2024', 'sales' ], - custom_fields: { 'Department': 'Sales' } - } -} ----- - -[NOTE] -The `exportpdf_service_url` option must be configured for the {pluginname} plugin to work. - -> For comprehensive details, see the https://exportpdf.api.tiny.cloud/v2/convert/docs[PDF Converter API documentation^]. For migration guidance from v1 to v2, see the https://exportpdf.api.tiny.cloud/v2/convert/docs#section/Export-to-PDF-(v2)/Migration-guide-from-v1-to-v2[migration guide^]. diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc index 0c02506a6f..c7cc600390 100644 --- a/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc +++ b/modules/ROOT/partials/configuration/exportpdf_converter_style.adoc @@ -1,7 +1,7 @@ [[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. +The `exportpdf_converter_style` option allows customization of the styles applied to the exported PDF document, providing flexibility in controlling its appearance. *Type:* `+String+` @@ -17,12 +17,8 @@ tinymce.init({ toolbar: 'exportpdf', exportpdf_service_url: '', // required if using On-premises service exportpdf_converter_options: { // required to support "exportpdf_converter_style" - header: [ - { - html: '

First page header.

', //example - css: 'h1 { font-size: 30px; }', //example - } - ], + header_html: '

First page header.

', + header_and_footer_css: 'h1 { font-size: 30px; }' }, exportpdf_converter_style: 'p { color: cyan !important }' // requires both "exportpdf_converter_style" and "exportpdf_service_url" to be set. }); From a65702af578478b5e8f4b79756ce16c3678e6d9c Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 11 Mar 2026 15:35:01 +1000 Subject: [PATCH 4/4] DOC-3243: Add on-premises Docker v2 API upgrade notes - exportpdf_service_url: IMPORTANT note about v2-compatible Docker image - export-to-pdf-overview: IMPORTANT note with changelog link - exportpdf_converter_options_combined: Expand NOTE for on-premises --- .../configuration/exportpdf_converter_options_combined.adoc | 4 +++- .../ROOT/partials/configuration/exportpdf_service_url.adoc | 5 +++++ .../export-to-pdf/export-to-pdf-overview.adoc | 5 +++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc b/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc index 48f5e2699d..fe17afa27f 100644 --- a/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc +++ b/modules/ROOT/partials/configuration/exportpdf_converter_options_combined.adoc @@ -16,7 +16,9 @@ Configures page layout, headers, footers, and other PDF output options. The edit Both formats use the same API endpoint. Flat-format options are converted to the nested structure automatically before the request. [NOTE] -Requires {productname} 8.4.0 or newer. +==== +Requires {productname} 8.4.0 or newer. On-premises deployments require a Docker image version that supports the v2 API. +==== === Flat format diff --git a/modules/ROOT/partials/configuration/exportpdf_service_url.adoc b/modules/ROOT/partials/configuration/exportpdf_service_url.adoc index 1348e22c2b..13424b60d8 100644 --- a/modules/ROOT/partials/configuration/exportpdf_service_url.adoc +++ b/modules/ROOT/partials/configuration/exportpdf_service_url.adoc @@ -5,6 +5,11 @@ The {pluginname} plugin uses an HTML-to-PDF converter service to generate `docum This option is **required** when configuring the {pluginname} plugin for `on-premise` setups. If you require access to this feature, please link:https://www.tiny.cloud/contact/[contact us]. For detailed instructions on deploying the {pluginname} service server-side component using Docker, refer to the xref:individual-export-to-pdf-on-premises.adoc[on-premises documentation]. +[IMPORTANT] +==== +On-premises deployments require a Docker image version that supports the v2 API (`/v2/convert/html-pdf`). Upgrade to the latest image or a v2-compatible version to use {productname} 8.4.0 or newer with the Export to PDF plugin. +==== + [TIP] When using a custom host, set the `exportpdf_service_url` option in your {productname} configuration to match your host. For example, if your custom host is `mycustomhost.com`, set the URL to `https://mycustomhost.com/`. diff --git a/modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc b/modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc index faa4fa789c..42dff818cd 100644 --- a/modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc +++ b/modules/ROOT/partials/individually-licensed-components/export-to-pdf/export-to-pdf-overview.adoc @@ -3,6 +3,11 @@ The On-Premises version of the {pluginname} Converter is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the {pluginname} Converter available as SaaS. +[IMPORTANT] +==== +To use {productname} 8.4.0 or newer with the Export to PDF plugin, the on-premises Docker image must support the v2 API (`/v2/convert/html-pdf`). Use the latest image or a v2-compatible version. See the link:https://registry.containers.tiny.cloud/api/changelogs/pdf-converter-tiny[changelog^] for version details. +==== + A valid license key is required in order to install {pluginname} Converter On-Premises. You will also need an access token to access the {companyname} Cloud Docker registry and pull the Docker image. To get started, link:https://www.tiny.cloud/contact/[Contact Tiny Support] for a trial license key and Docker access token.