mirror of
https://github.com/django/django.git
synced 2025-07-07 21:35:15 +00:00
f2f6046c0f
Some checks are pending
Docs / docs (push) Waiting to run
Docs / blacken-docs (push) Waiting to run
Linters / isort (push) Waiting to run
Linters / black (push) Waiting to run
Linters / flake8 (push) Waiting to run
Tests / Windows, SQLite, Python 3.13 (push) Waiting to run
Tests / JavaScript tests (push) Waiting to run
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>
239 lines
6.3 KiB
Text
239 lines
6.3 KiB
Text
===================
|
|
GeoDjango Forms API
|
|
===================
|
|
|
|
.. module:: django.contrib.gis.forms
|
|
:synopsis: GeoDjango forms API.
|
|
|
|
GeoDjango provides some specialized form fields and widgets in order to visually
|
|
display and edit geolocalized data on a map. By default, they use
|
|
`OpenLayers`_-powered maps, with a base WMS layer provided by `NASA`_.
|
|
|
|
.. _OpenLayers: https://openlayers.org/
|
|
.. _NASA: https://www.earthdata.nasa.gov/
|
|
|
|
Field arguments
|
|
===============
|
|
In addition to the regular :ref:`form field arguments <core-field-arguments>`,
|
|
GeoDjango form fields take the following optional arguments.
|
|
|
|
``srid``
|
|
--------
|
|
|
|
.. attribute:: Field.srid
|
|
|
|
This is the SRID code that the field value should be transformed to. For
|
|
example, if the map widget SRID is different from the SRID more generally
|
|
used by your application or database, the field will automatically convert
|
|
input values into that SRID.
|
|
|
|
``geom_type``
|
|
-------------
|
|
|
|
.. attribute:: Field.geom_type
|
|
|
|
You generally shouldn't have to set or change that attribute which should
|
|
be set up depending on the field class. It matches the OpenGIS standard
|
|
geometry name.
|
|
|
|
Form field classes
|
|
==================
|
|
|
|
``GeometryField``
|
|
-----------------
|
|
|
|
.. class:: GeometryField
|
|
|
|
``PointField``
|
|
--------------
|
|
|
|
.. class:: PointField
|
|
|
|
``LineStringField``
|
|
-------------------
|
|
|
|
.. class:: LineStringField
|
|
|
|
``PolygonField``
|
|
----------------
|
|
|
|
.. class:: PolygonField
|
|
|
|
``MultiPointField``
|
|
-------------------
|
|
|
|
.. class:: MultiPointField
|
|
|
|
``MultiLineStringField``
|
|
------------------------
|
|
|
|
.. class:: MultiLineStringField
|
|
|
|
``MultiPolygonField``
|
|
---------------------
|
|
|
|
.. class:: MultiPolygonField
|
|
|
|
``GeometryCollectionField``
|
|
---------------------------
|
|
|
|
.. class:: GeometryCollectionField
|
|
|
|
Form widgets
|
|
============
|
|
|
|
.. module:: django.contrib.gis.forms.widgets
|
|
:synopsis: GeoDjango widgets API.
|
|
|
|
GeoDjango form widgets allow you to display and edit geographic data on a
|
|
visual map.
|
|
Note that none of the currently available widgets supports 3D geometries, hence
|
|
geometry fields will fallback using a ``Textarea`` widget for such data.
|
|
|
|
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
|
|
|
|
The OpenGIS geometry type, generally set by the form field.
|
|
|
|
.. attribute:: BaseGeometryWidget.map_srid
|
|
|
|
SRID code used by the map (default is 4326).
|
|
|
|
.. attribute:: BaseGeometryWidget.display_raw
|
|
|
|
Boolean value specifying if a textarea input showing the serialized
|
|
representation of the current geometry is visible, mainly for debugging
|
|
purposes (default is ``False``).
|
|
|
|
.. attribute:: BaseGeometryWidget.supports_3d
|
|
|
|
Indicates if the widget supports edition of 3D data (default is ``False``).
|
|
|
|
.. attribute:: BaseGeometryWidget.template_name
|
|
|
|
The template used to render the map widget.
|
|
|
|
You can pass widget attributes in the same manner that for any other Django
|
|
widget. For example::
|
|
|
|
from django.contrib.gis import forms
|
|
|
|
|
|
class MyGeoForm(forms.Form):
|
|
point = forms.PointField(widget=forms.OSMWidget(attrs={"display_raw": True}))
|
|
|
|
Widget classes
|
|
--------------
|
|
|
|
``BaseGeometryWidget``
|
|
|
|
.. class:: BaseGeometryWidget
|
|
|
|
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 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. 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
|
|
these widgets in order to specify your own version of the ``ol.js`` file in
|
|
the ``js`` property of the inner ``Media`` class (see
|
|
:ref:`assets-as-a-static-definition`).
|
|
|
|
``OSMWidget``
|
|
|
|
.. class:: OSMWidget
|
|
|
|
This widget specialized :class:`OpenLayersWidget` and uses an OpenStreetMap
|
|
base layer to display geographic objects on. Attributes are:
|
|
|
|
.. attribute:: base_layer
|
|
|
|
.. versionadded:: 6.0
|
|
|
|
``osm``
|
|
|
|
.. attribute:: default_lat
|
|
.. attribute:: default_lon
|
|
|
|
The default center latitude and longitude are ``47`` and ``5``,
|
|
respectively, which is a location in eastern France.
|
|
|
|
.. attribute:: default_zoom
|
|
|
|
The default map zoom is ``12``.
|
|
|
|
The :class:`OpenLayersWidget` note about JavaScript file hosting above also
|
|
applies here. See also this `FAQ answer`_ about ``https`` access to map
|
|
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"]
|