From f2f6046c0f92ff1faed057da0711ac478eef439c Mon Sep 17 00:00:00 2001
From: Claude Paroz <claude@2xlibre.net>
Date: Sun, 18 Aug 2024 15:29:30 +0200
Subject: 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>
---
 docs/ref/contrib/gis/forms-api.txt | 74 +++++++++++++++++++++++++++++++++-----
 docs/releases/6.0.txt              |  8 +++++
 2 files changed, 74 insertions(+), 8 deletions(-)

(limited to 'docs')

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"]
diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt
index ade85a2173..118ad43cc9 100644
--- a/docs/releases/6.0.txt
+++ b/docs/releases/6.0.txt
@@ -73,6 +73,9 @@ Minor features
   function rotates a geometry by a specified angle around the origin or a
   specified point.
 
+* The new :attr:`.BaseGeometryWidget.base_layer` attribute allows specifying a
+  JavaScript map base layer, enabling customization of map tile providers.
+
 :mod:`django.contrib.messages`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -332,6 +335,11 @@ Miscellaneous
   refactored to use Python's :py:class:`email.message.Message` for parsing.
   Input headers exceeding 10000 characters will now raise :exc:`ValueError`.
 
+* Widgets from :mod:`django.contrib.gis.forms.widgets` now render without
+  inline JavaScript in templates. If you have customized any geometry widgets
+  or their templates, you may need to :ref:`update them
+  <geometry-widgets-customization>` to match the new layout.
+
 .. _deprecated-features-6.0:
 
 Features deprecated in 6.0
-- 
cgit v1.3