From ccff857e7943d3904338bb7a1c5e6da03514ec77 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 2 Jul 2025 22:11:19 +1000 Subject: [PATCH 1/2] DOC-3147: Removed property from Editor instances, use instead. Add distinction between tinymce.documentBaseURL and editor.documentBaseURI Expand documentBaseURI documentation with accurate method examples Remove incorrect API method examples Add detailed path resolution explanations Retain documentBaseURL in TinyMCE root API docs --- .../url-conversion-relative-2/index.js | 7 +- modules/ROOT/pages/8.0-release-notes.adoc | 6 + modules/ROOT/pages/url-handling.adoc | 4 +- .../configuration/document_base_uri.adoc | 109 ++++++++++++++++++ .../configuration/document_base_url.adoc | 18 --- .../partials/configuration/relative_urls.adoc | 12 +- .../configuration/remove_script_host.adoc | 38 ++---- modules/ROOT/partials/misc/url-handling.adoc | 58 ++++++---- 8 files changed, 175 insertions(+), 77 deletions(-) create mode 100644 modules/ROOT/partials/configuration/document_base_uri.adoc delete mode 100644 modules/ROOT/partials/configuration/document_base_url.adoc diff --git a/modules/ROOT/examples/live-demos/url-conversion-relative-2/index.js b/modules/ROOT/examples/live-demos/url-conversion-relative-2/index.js index 50a24c9d73..f062020cfb 100644 --- a/modules/ROOT/examples/live-demos/url-conversion-relative-2/index.js +++ b/modules/ROOT/examples/live-demos/url-conversion-relative-2/index.js @@ -3,6 +3,11 @@ tinymce.init({ height: 300, plugins: 'link image code', relative_urls: true, - document_base_url: '//www.tiny.cloud/docs/demo', + // The documentBaseURI will be set to the current page's URL + setup: function(editor) { + editor.on('init', function() { + console.log('Base URI:', editor.documentBaseURI.getURI()); + }); + }, content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }' }); \ No newline at end of file diff --git a/modules/ROOT/pages/8.0-release-notes.adoc b/modules/ROOT/pages/8.0-release-notes.adoc index 7c62f25b54..1641f55e15 100644 --- a/modules/ROOT/pages/8.0-release-notes.adoc +++ b/modules/ROOT/pages/8.0-release-notes.adoc @@ -136,6 +136,12 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a // #TINY-vwxyz1 // CCFR here. +=== Removed `documentBaseUrl` property from Editor instances, use `documentBaseURI` instead. +// #TINY-12182 + +{productname} {release-version} has removed the undocumented `documentBaseUrl` property from `Editor` instances. This internal property was not part of the public API and may have caused confusion for developers accessing editor internals. The supported and documented alternative is `documentBaseURI`, which should be used instead. This change improves API clarity by eliminating unsupported and untracked editor properties. + +For more information on the `documentBaseURI` property, see the {api_url}/tinymce.editor/#documentBaseURI[Editor API - documentBaseURI] documentation. [[bug-fixes]] diff --git a/modules/ROOT/pages/url-handling.adoc b/modules/ROOT/pages/url-handling.adoc index e4668d6339..b9f9a7f3c3 100644 --- a/modules/ROOT/pages/url-handling.adoc +++ b/modules/ROOT/pages/url-handling.adoc @@ -1,7 +1,7 @@ = URL handling options :navtitle: URL handling options :description: These settings affect the way URLs are handled by the editor. -:keywords: url, urls, relative, absolute, domain, document_base_url +:keywords: url, urls, relative, absolute, domain, documentBaseURI include::partial$misc/url-handling.adoc[] @@ -17,7 +17,7 @@ include::partial$configuration/allow_script_urls.adoc[leveloffset=+1] include::partial$configuration/convert_urls.adoc[leveloffset=+1] -include::partial$configuration/document_base_url.adoc[leveloffset=+1] +include::partial$configuration/document_base_uri.adoc[leveloffset=+1] include::partial$configuration/relative_urls.adoc[leveloffset=+1] diff --git a/modules/ROOT/partials/configuration/document_base_uri.adoc b/modules/ROOT/partials/configuration/document_base_uri.adoc new file mode 100644 index 0000000000..fae8dc1451 --- /dev/null +++ b/modules/ROOT/partials/configuration/document_base_uri.adoc @@ -0,0 +1,109 @@ +[[document_base_uri]] +== `documentBaseURI` + +The `documentBaseURI` property provides methods for URL manipulation in the editor. It is an instance of the {api_url}/tinymce.util.uri/[URI] class that represents the editor's base URL. + +NOTE: This is different from `tinymce.documentBaseURL` (the global EditorManager property). While `tinymce.documentBaseURL` is a string property containing the document's base URL, `editor.documentBaseURI` is the recommended way to handle URL manipulations within an editor instance as it provides helpful methods for URL conversion. + +=== Example: URL Manipulation + +[source,js] +---- +tinymce.init({ + selector: 'textarea', + setup: function(editor) { + editor.on('init', function() { + const baseUri = editor.documentBaseURI; + + // Get the base URL + console.log('Base URL:', baseUri.getURI()); + // Output: "Base URL: https://fiddle.tiny.cloud/" + + // Convert relative to absolute URL + console.log('Absolute URL:', baseUri.toAbsolute('images/logo.png')); + // Output: "Absolute URL: https://fiddle.tiny.cloud/images/logo.png" + + // Convert absolute to relative URL + console.log('Relative URL:', baseUri.toRelative('https://fiddle.tiny.cloud/images/logo.png')); + // Output: "Relative URL: images/logo.png" + }); + } +}); +---- + +=== Available Methods + +The `documentBaseURI` object provides the following methods for URL handling: + +* `getURI()` - Gets the complete base URI as a string +* `toAbsolute(url)` - Converts a relative URL to an absolute URL based on the editor's base URL +* `toRelative(url)` - Converts an absolute URL to a relative URL based on the editor's base URL +* `toAbsPath(base, path)` - Converts a relative path to an absolute path + +NOTE: While `documentBaseURI` is an instance of the URI class, it primarily exposes methods for URL conversion. For more complex URI manipulation, you can create a new instance of `tinymce.util.URI`. + +=== Examples + +==== URL Manipulation + +[source,js] +---- +tinymce.init({ + selector: 'textarea', + setup: function(editor) { + editor.on('init', function() { + const baseUri = editor.documentBaseURI; + + // Get the complete base URL + console.log('Base URL:', baseUri.getURI()); + // Example output: "https://example.com/path/to/editor/" + + // Basic URL conversions + console.log('To Absolute:', baseUri.toAbsolute('images/logo.png')); + // Example output: "https://example.com/path/to/editor/images/logo.png" + + console.log('To Relative:', baseUri.toRelative('https://example.com/path/to/editor/images/logo.png')); + // Example output: "images/logo.png" + + console.log('To Absolute Path:', baseUri.toAbsPath('/root/', 'path/file.txt')); + // Example output: "/root/path/file.txt" + }); + } +}); +---- + +==== Additional URL Manipulation Examples + +[source,js] +---- +tinymce.init({ + selector: 'textarea', + setup: function(editor) { + editor.on('init', function() { + const baseUri = editor.documentBaseURI; + + // Working with content URLs + const imageUrl = 'images/logo.png'; + const styleUrl = '/styles/custom.css'; + const fullUrl = 'https://example.com/resources/file.pdf'; + + // Converting relative URLs to absolute + console.log('Image absolute:', baseUri.toAbsolute(imageUrl)); + console.log('Style absolute:', baseUri.toAbsolute(styleUrl)); + + // Converting absolute URLs to relative + console.log('Document relative:', baseUri.toRelative(fullUrl)); + + // Working with paths (resolves and normalizes paths) + console.log('Absolute path 1:', baseUri.toAbsPath('/content/', '../images/photo.jpg')); + // Output: "/images/photo.jpg" (../ moves up from /content/ to /, then adds images/photo.jpg) + + console.log('Absolute path 2:', baseUri.toAbsPath('/content/sub/', '../../images/photo.jpg')); + // Output: "/images/photo.jpg" (../../ moves up twice from /content/sub/ to /) + + console.log('Absolute path 3:', baseUri.toAbsPath('/content/', './images/photo.jpg')); + // Output: "/content/images/photo.jpg" (./ keeps us in /content/) + }); + } +}); +---- diff --git a/modules/ROOT/partials/configuration/document_base_url.adoc b/modules/ROOT/partials/configuration/document_base_url.adoc deleted file mode 100644 index a1295e2fa7..0000000000 --- a/modules/ROOT/partials/configuration/document_base_url.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[[document_base_url]] -== `+document_base_url+` - -This option specifies the base URL for all relative URLs in the document. The default value is the directory of the current document. If a value is provided, it must specify a directory (not a document) and must end with a `+/+`. - -This option also interacts with the xref:url-handling.adoc#relative_urls[relative_urls], xref:url-handling.adoc#remove_script_host[remove_script_host], and xref:url-handling.adoc#convert_urls[convert_urls] options to determine whether {productname} returns relative or absolute URLs. The xref:url-handling.adoc[URL handling options page] contains a thorough description and examples of working with relative and absolute URLs. - -*Type:* `+String+` - -=== Example: using `+document_base_url+` - -[source,js] ----- -tinymce.init({ - selector: 'textarea', // change this value according to your HTML - document_base_url: 'http://www.example.com/path1/' -}); ----- diff --git a/modules/ROOT/partials/configuration/relative_urls.adoc b/modules/ROOT/partials/configuration/relative_urls.adoc index 659862d05a..62018a4211 100644 --- a/modules/ROOT/partials/configuration/relative_urls.adoc +++ b/modules/ROOT/partials/configuration/relative_urls.adoc @@ -1,16 +1,12 @@ [[relative_urls]] == `+relative_urls+` -For URLs with the same domain as the page containing the {productname} editor. If set to: +For URLs with the same domain as the editor content. This option controls whether URLs are converted to: -* `+true+` -- All URLs created in {productname} will be converted to a link relative to the xref:url-handling.adoc#document_base_url[`+document_base_url+`]. -* `+false+` -- All URLs will be converted to absolute URLs. +* `+true+` (default) - Relative URLs based on the configured base URL (see xref:apis/tinymce.editor.adoc#documentBaseURI[documentBaseURI]) +* `+false+` - Absolute URLs -*Type:* `+Boolean+` - -*Default value:* `+true+` - -*Possible values:* `+true+`, `+false+` +The actual URL conversion is handled by the editor's `documentBaseURI` property. For more details on URL manipulation methods, see the {api_url}/tinymce.util.uri/[URI API documentation]. === Example: using `+relative_urls+` diff --git a/modules/ROOT/partials/configuration/remove_script_host.adoc b/modules/ROOT/partials/configuration/remove_script_host.adoc index 27851c0f90..99dde7d413 100644 --- a/modules/ROOT/partials/configuration/remove_script_host.adoc +++ b/modules/ROOT/partials/configuration/remove_script_host.adoc @@ -1,44 +1,26 @@ [[remove_script_host]] == `+remove_script_host+` -This option is used if the xref:url-handling.adoc#relative_urls[`+relative_urls+`] option is set to `+false+` and only applies to links with the same domain as the xref:url-handling.adoc#document_base_url[`+document_base_url+`]. +This option controls whether the protocol and domain are included in URLs when `relative_urls` is set to `false`. -If this option is set to `+true+`, the protocol and host of the `+document_base_url+` is _excluded_ for relative links. +* `+true+` (default) - Protocol and domain are removed from URLs +* `+false+` - Protocol and domain are included in URLs -If this option is set to `+false+`, the protocol and host of the `+document_base_url+` is _added_ for relative links. +This setting affects both the visual representation of URLs in the editor and the results from the `documentBaseURI` URL manipulation methods. -*Type:* `+Boolean+` - -*Default value:* `+true+` - -*Possible values:* `+true+`, `+false+` - -=== Examples: Using `+remove_script_host+` - -When `+remove_script_host+` is set to `+true+`, such as: +=== Example: URL handling with remove_script_host [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your HTML - document_base_url: 'http://www.example.com/path1/', + selector: 'textarea', relative_urls: false, remove_script_host: true }); ----- - -Adding a relative URL such as `+test.html+`, the editor will convert the URL to: `+/path1/test.html+`. -When `+remove_script_host+` is set to `+false+`, such as: +// With remove_script_host: true +editor.documentBaseURI.toAbsolute('page.html'); // Returns: /path1/page.html -[source,js] ----- -tinymce.init({ - selector: 'textarea', // change this value according to your HTML - document_base_url: 'http://www.example.com/path1/', - relative_urls: false, - remove_script_host: false -}); +// With remove_script_host: false +editor.documentBaseURI.toAbsolute('page.html'); // Returns: http://www.example.com/path1/page.html ---- - -Adding a relative URL such as `+test.html+`, the editor will convert the URL to: `+http://www.example.com/path1/test.html+`. diff --git a/modules/ROOT/partials/misc/url-handling.adoc b/modules/ROOT/partials/misc/url-handling.adoc index cac5c16711..5f12ee185f 100644 --- a/modules/ROOT/partials/misc/url-handling.adoc +++ b/modules/ROOT/partials/misc/url-handling.adoc @@ -1,63 +1,81 @@ -== Convert URLs to relative, absolute, or absolute with domain +== URL Handling in TinyMCE -=== Relative URLs +=== The documentBaseURI API -This will convert all URLs within the same domain to relative URLs. The URLs will be relative from the xref:url-handling.adoc#document_base_url[document_base_url]. +The `documentBaseURI` property on the editor instance provides methods for manipulating URLs. This URI object represents the base URL for the editor and provides methods for converting between relative and absolute URLs. + +For detailed information on using the documentBaseURI API, see: xref:apis/tinymce.editor.adoc#documentBaseURI[documentBaseURI]. + +=== URL Conversion Settings + +Two configuration options control how URLs are displayed in the editor: + +* `relative_urls` - When true, URLs are converted to be relative to the editor's base URL +* `remove_script_host` - When true, the protocol and host are excluded from absolute URLs + +=== URL Conversion Examples + +==== Relative URLs + +This converts URLs to be relative to the base URL: [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your HTML - relative_urls: true, - document_base_url: 'http://www.example.com/path1/' + selector: 'textarea', + relative_urls: true }); + +// The editor's documentBaseURI can be used to manipulate URLs: +editor.documentBaseURI.toRelative('http://www.example.com/path1/path2/file.htm'); // Returns: path2/file.htm ---- Example: `+http://www.example.com/path1/path2/file.htm+` >> `+path2/file.htm+` -==== Example: relative URLs on links and images +===== Example: relative URLs on links and images liveDemo::url-conversion-relative-1[] -==== Example: relative URLs on links and images to a specific page +===== Example: relative URLs on links and images to a specific page liveDemo::url-conversion-relative-2[] -=== Absolute URLs +==== Absolute URLs -This will convert all relative URLs to absolute URLs. The URLs will be absolute based on the xref:url-handling.adoc#document_base_url[document_base_url]. +This converts URLs to be absolute based on the document base URL: [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your HTML + selector: 'textarea', relative_urls: false, - remove_script_host: true, - document_base_url: 'http://www.example.com/path1/' + remove_script_host: true }); + +// The editor's documentBaseURI can be used to manipulate URLs: +editor.documentBaseURI.toAbsolute('path2/file.htm'); // Returns: /path1/path2/file.htm ---- Example: `+path2/file.htm+` >> `+/path1/path2/file.htm+` -==== Example: absolute URLs on links and images +===== Example: absolute URLs on links and images liveDemo::url-conversion-absolute-1[] -==== Example: absolute URLs and including domain on links and images +===== Example: absolute URLs and including domain on links and images liveDemo::url-conversion-absolute-2[] -=== Domain absolute URLs +==== Domain absolute URLs -This will convert all relative URLs to absolute URLs. The URLs will be absolute based on the xref:url-handling.adoc#document_base_url[document_base_url] with domain. +This converts URLs to be absolute with the domain included: [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your HTML + selector: 'textarea', relative_urls: false, - remove_script_host: false, - document_base_url: 'http://www.example.com/path1/' + remove_script_host: false }); ---- From 2868fd79c23927e917b1068e4f574e6f6cc7faba Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 2 Jul 2025 22:23:03 +1000 Subject: [PATCH 2/2] DOC-3147: Fix typo for missing l in html. --- modules/ROOT/partials/misc/url-handling.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/partials/misc/url-handling.adoc b/modules/ROOT/partials/misc/url-handling.adoc index 5f12ee185f..d584251924 100644 --- a/modules/ROOT/partials/misc/url-handling.adoc +++ b/modules/ROOT/partials/misc/url-handling.adoc @@ -27,10 +27,10 @@ tinymce.init({ }); // The editor's documentBaseURI can be used to manipulate URLs: -editor.documentBaseURI.toRelative('http://www.example.com/path1/path2/file.htm'); // Returns: path2/file.htm +editor.documentBaseURI.toRelative('http://www.example.com/path1/path2/file.html'); // Returns: path2/file.html ---- -Example: `+http://www.example.com/path1/path2/file.htm+` >> `+path2/file.htm+` +Example: `+http://www.example.com/path1/path2/file.html+` >> `+path2/file.html+` ===== Example: relative URLs on links and images @@ -53,10 +53,10 @@ tinymce.init({ }); // The editor's documentBaseURI can be used to manipulate URLs: -editor.documentBaseURI.toAbsolute('path2/file.htm'); // Returns: /path1/path2/file.htm +editor.documentBaseURI.toAbsolute('path2/file.html'); // Returns: /path1/path2/file.html ---- -Example: `+path2/file.htm+` >> `+/path1/path2/file.htm+` +Example: `+path2/file.html+` >> `+/path1/path2/file.html+` ===== Example: absolute URLs on links and images @@ -79,4 +79,4 @@ tinymce.init({ }); ---- -Example: `+path2/file.htm+` >> `+http://www.example.com/path1/path2/file.htm+` +Example: `+path2/file.html+` >> `+http://www.example.com/path1/path2/file.html+`