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

Author: kemister85

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/document_base_url.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/relative_urls.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/configuration/remove_script_host.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
 });
 ----