mirror of
https://github.com/django/django.git
synced 2024-12-01 15:42:04 +01:00
b16b72d415
Largely inspired from django-floppyforms. Designed to not depend on OpenLayers at code level.
166 lines
4.0 KiB
Plaintext
166 lines
4.0 KiB
Plaintext
.. _ref-gis-forms-api:
|
|
|
|
===================
|
|
GeoDjango Forms API
|
|
===================
|
|
|
|
.. module:: django.contrib.gis.forms
|
|
:synopsis: GeoDjango forms API.
|
|
|
|
.. versionadded:: 1.6
|
|
|
|
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://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_wkt
|
|
|
|
Boolean value specifying if a textarea input showing the WKT 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``.
|
|
|
|
``OSMWidget``
|
|
|
|
.. class:: OSMWidget
|
|
|
|
This widget uses an OpenStreetMap base layer (Mapnik) to display geographic
|
|
objects on.
|
|
``template_name`` is ``gis/openlayers-osm.html``.
|