182 lines
5.1 KiB
Plaintext
182 lines
5.1 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 `Metacarta`_.
|
|
|
|
.. _OpenLayers: http://openlayers.org/
|
|
.. _Metacarta: http://www.metacarta.com/
|
|
|
|
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.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 ``openlayers.org`` Web site. This works for basic usage
|
|
during development, but isn't appropriate for a production deployment as
|
|
``openlayers.org/api/`` has no guaranteed uptime and runs on a slow server.
|
|
You are therefore advised to subclass these widgets in order to specify
|
|
your own version of the ``openlayers.js`` file in the ``js`` property of
|
|
the inner ``Media`` class (see :ref:`assets-as-a-static-definition`). You
|
|
can host a copy of ``openlayers.js``
|
|
`tailored to your needs`_ on your own server or refer to a copy from a
|
|
content-delivery network like http://cdnjs.com/. This will also allow
|
|
you to serve the JavaScript file(s) using the ``https`` protocol if needed.
|
|
|
|
.. _tailored to your needs: http://docs.openlayers.org/library/deploying.html
|
|
|
|
``OSMWidget``
|
|
|
|
.. class:: OSMWidget
|
|
|
|
This widget uses an OpenStreetMap base layer (Mapnik) to display geographic
|
|
objects on.
|
|
``template_name`` is ``gis/openlayers-osm.html``.
|
|
|
|
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
|