DOC-3147: Removed documentBaseUrl property from Editor instances, use documentBaseURI instead.

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 }'
 });

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]]

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]
 

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/)
+    });
+  }
+});
+----

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+`
 

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+`.

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+`