Fixed #25706 -- Refactored geometry widgets to remove inline JavaScript.

Refactored GIS-related JavaScript initialization to eliminate inline
scripts from templates. Added support for specifying a base layer using
the new `base_layer_name` attribute on `BaseGeometryWidget`, allowing
custom map tile providers via user-defined JavaScript.

As a result, the `gis/openlayers-osm.html` template was removed.

Thanks Sarah Boyce for reviews.

Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>

1 files changed, 66 insertions, 8 deletions

diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt
index 61308c5933..c05cef65d0 100644
--- a/docs/ref/contrib/gis/forms-api.txt
+++ b/docs/ref/contrib/gis/forms-api.txt
@@ -96,6 +96,14 @@ Widget attributes
 GeoDjango widgets are template-based, so their attributes are mostly different
 from other Django widget attributes.
 
+.. attribute:: BaseGeometryWidget.base_layer
+
+    .. versionadded:: 6.0
+
+    A string that specifies the identifier for the default base map layer to be
+    used by the corresponding JavaScript map widget. It is passed as part of
+    the widget options when rendering, allowing the ``MapWidget`` to determine
+    which map tile provider or base layer to initialize (default is ``None``).
 
 .. attribute:: BaseGeometryWidget.geom_type
 
@@ -137,15 +145,29 @@ Widget classes
 
     This is an abstract base widget containing the logic needed by subclasses.
     You cannot directly use this widget for a geometry field.
-    Note that the rendering of GeoDjango widgets is based on a template,
-    identified by the :attr:`template_name` class attribute.
+    Note that the rendering of GeoDjango widgets is based on a base layer name,
+    identified by the :attr:`base_layer` class attribute.
 
 ``OpenLayersWidget``
 
 .. class:: OpenLayersWidget
 
-    This is the default widget used by all GeoDjango form fields.
-    ``template_name`` is ``gis/openlayers.html``.
+    This is the default widget used by all GeoDjango form fields. Attributes
+    are:
+
+    .. attribute:: base_layer
+
+       .. versionadded:: 6.0
+
+        ``nasaWorldview``
+
+    .. attribute:: template_name
+
+        ``gis/openlayers.html``.
+
+    .. attribute:: map_srid
+
+        ``3857``
 
     ``OpenLayersWidget`` and :class:`OSMWidget` use the ``ol.js`` file hosted
     on the ``cdn.jsdelivr.net`` content-delivery network. You can subclass
@@ -157,12 +179,14 @@ Widget classes
 
 .. class:: OSMWidget
 
-    This widget uses an OpenStreetMap base layer to display geographic objects
-    on. Attributes are:
+    This widget specialized :class:`OpenLayersWidget` and uses an OpenStreetMap
+    base layer to display geographic objects on. Attributes are:
 
-    .. attribute:: template_name
+    .. attribute:: base_layer
+
+        .. versionadded:: 6.0
 
-        ``gis/openlayers-osm.html``
+        ``osm``
 
     .. attribute:: default_lat
     .. attribute:: default_lon
@@ -179,3 +203,37 @@ Widget classes
     tiles.
 
     .. _FAQ answer: https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site
+
+    .. versionchanged:: 6.0
+
+        The ``OSMWidget`` no longer uses a custom template. Consequently, the
+        ``gis/openlayers-osm.html`` template was removed.
+
+.. _geometry-widgets-customization:
+
+Customizing the base layer used in OpenLayers-based widgets
+-----------------------------------------------------------
+
+.. versionadded:: 6.0
+
+To customize the base layer displayed in OpenLayers-based geometry widgets,
+define a new layer builder in a custom JavaScript file. For example:
+
+.. code-block:: javascript
+   :caption: ``path-to-file.js``
+
+    MapWidget.layerBuilder.custom_layer_name = function () {
+        // Return an OpenLayers layer instance.
+        return new ol.layer.Tile({source: new ol.source.<ChosenSource>()});
+    };
+
+Then, subclass a standard geometry widget and set the ``base_layer``::
+
+    from django.contrib.gis.forms.widgets import OpenLayersWidget
+
+
+    class YourCustomWidget(OpenLayersWidget):
+        base_layer = "custom_layer_name"
+
+        class Media:
+            js = ["path-to-file.js"]