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..d584251924 100644 --- a/modules/ROOT/partials/misc/url-handling.adoc +++ b/modules/ROOT/partials/misc/url-handling.adoc @@ -1,64 +1,82 @@ -== 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.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 +===== 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.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 +===== 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 }); ---- -Example: `+path2/file.htm+` >> `+http://www.example.com/path1/path2/file.htm+` +Example: `+path2/file.html+` >> `+http://www.example.com/path1/path2/file.html+`