205 lines
5.5 KiB
Plaintext
205 lines
5.5 KiB
Plaintext
===================
|
|
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: http://openlayers.org/
|
|
.. _NASA: https://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 setup 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 simple ``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.geom_type
|
|
|
|
The OpenGIS geometry type, generally set by the form field.
|
|
|
|
.. attribute:: BaseGeometryWidget.map_height
|
|
.. attribute:: BaseGeometryWidget.map_width
|
|
|
|
Height and width of the widget map (default is 400x600).
|
|
|
|
.. 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={'map_width': 800, 'map_height': 500}))
|
|
|
|
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 template,
|
|
identified by the :attr:`template_name` class attribute.
|
|
|
|
``OpenLayersWidget``
|
|
|
|
.. class:: OpenLayersWidget
|
|
|
|
This is the default widget used by all GeoDjango form fields.
|
|
``template_name`` is ``gis/openlayers.html``.
|
|
|
|
``OpenLayersWidget`` and :class:`OSMWidget` use the ``openlayers.js`` file
|
|
hosted on the ``cdnjs.cloudflare.com`` content-delivery network. You can
|
|
subclass these widgets in order to specify your own version of the
|
|
``OpenLayers.js`` file `tailored to your needs`_ in the ``js`` property of
|
|
the inner ``Media`` class (see :ref:`assets-as-a-static-definition`).
|
|
|
|
.. versionchanged:: 1.11
|
|
|
|
Older versions use ``OpenLayers.js`` from ``openlayers.org`` which
|
|
isn't suitable for production use since it offers no guaranteed uptime
|
|
and runs on a slow server.
|
|
|
|
Also, the widget nows uses OpenLayers 3 instead of OpenLayers 2.
|
|
|
|
.. _tailored to your needs: http://openlayers.org/en/latest/doc/tutorials/custom-builds.html
|
|
|
|
``OSMWidget``
|
|
|
|
.. class:: OSMWidget
|
|
|
|
This widget uses an OpenStreetMap base layer to display geographic objects
|
|
on. Attributes are:
|
|
|
|
.. attribute:: template_name
|
|
|
|
``gis/openlayers-osm.html``
|
|
|
|
.. 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
|
|
|
|
.. versionadded:: 2.0
|
|
|
|
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.
|
|
|
|
.. versionchanged:: 1.11
|
|
|
|
OpenLayers 2.x has been dropped in favor of OpenLayers 3. If you extend
|
|
the ``gis/openlayers-osm.html`` template, please review your custom
|
|
template.
|
|
|
|
.. _FAQ answer: https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site
|