Debian Codegraph @

docs/ref/contrib/gis/forms-api.txt

raw
1 ===================
2 GeoDjango Forms API
3 ===================
4
5 .. module:: django.contrib.gis.forms
6 :synopsis: GeoDjango forms API.
7
8 GeoDjango provides some specialized form fields and widgets in order to visually
9 display and edit geolocalized data on a map. By default, they use
10 `OpenLayers`_-powered maps, with a base WMS layer provided by `NASA`_.
11
12 .. _OpenLayers: https://openlayers.org/
13 .. _NASA: https://www.earthdata.nasa.gov/
14
15 Field arguments
16 ===============
17 In addition to the regular :ref:`form field arguments <core-field-arguments>`,
18 GeoDjango form fields take the following optional arguments.
19
20 ``srid``
21 --------
22
23 .. attribute:: Field.srid
24
25 This is the SRID code that the field value should be transformed to. For
26 example, if the map widget SRID is different from the SRID more generally
27 used by your application or database, the field will automatically convert
28 input values into that SRID.
29
30 ``geom_type``
31 -------------
32
33 .. attribute:: Field.geom_type
34
35 You generally shouldn't have to set or change that attribute which should
36 be set up depending on the field class. It matches the OpenGIS standard
37 geometry name.
38
39 Form field classes
40 ==================
41
42 ``GeometryField``
43 -----------------
44
45 .. class:: GeometryField
46
47 ``PointField``
48 --------------
49
50 .. class:: PointField
51
52 ``LineStringField``
53 -------------------
54
55 .. class:: LineStringField
56
57 ``PolygonField``
58 ----------------
59
60 .. class:: PolygonField
61
62 ``MultiPointField``
63 -------------------
64
65 .. class:: MultiPointField
66
67 ``MultiLineStringField``
68 ------------------------
69
70 .. class:: MultiLineStringField
71
72 ``MultiPolygonField``
73 ---------------------
74
75 .. class:: MultiPolygonField
76
77 ``GeometryCollectionField``
78 ---------------------------
79
80 .. class:: GeometryCollectionField
81
82 Form widgets
83 ============
84
85 .. module:: django.contrib.gis.forms.widgets
86 :synopsis: GeoDjango widgets API.
87
88 GeoDjango form widgets allow you to display and edit geographic data on a
89 visual map.
90 Note that none of the currently available widgets supports 3D geometries, hence
91 geometry fields will fallback using a ``Textarea`` widget for such data.
92
93 Widget attributes
94 -----------------
95
96 GeoDjango widgets are template-based, so their attributes are mostly different
97 from other Django widget attributes.
98
99
100 .. attribute:: BaseGeometryWidget.geom_type
101
102 The OpenGIS geometry type, generally set by the form field.
103
104 .. attribute:: BaseGeometryWidget.map_srid
105
106 SRID code used by the map (default is 4326).
107
108 .. attribute:: BaseGeometryWidget.display_raw
109
110 Boolean value specifying if a textarea input showing the serialized
111 representation of the current geometry is visible, mainly for debugging
112 purposes (default is ``False``).
113
114 .. attribute:: BaseGeometryWidget.supports_3d
115
116 Indicates if the widget supports edition of 3D data (default is ``False``).
117
118 .. attribute:: BaseGeometryWidget.template_name
119
120 The template used to render the map widget.
121
122 You can pass widget attributes in the same manner that for any other Django
123 widget. For example::
124
125 from django.contrib.gis import forms
126
127
128 class MyGeoForm(forms.Form):
129 point = forms.PointField(widget=forms.OSMWidget(attrs={"display_raw": True}))
130
131 Widget classes
132 --------------
133
134 ``BaseGeometryWidget``
135
136 .. class:: BaseGeometryWidget
137
138 This is an abstract base widget containing the logic needed by subclasses.
139 You cannot directly use this widget for a geometry field.
140 Note that the rendering of GeoDjango widgets is based on a template,
141 identified by the :attr:`template_name` class attribute.
142
143 ``OpenLayersWidget``
144
145 .. class:: OpenLayersWidget
146
147 This is the default widget used by all GeoDjango form fields.
148 ``template_name`` is ``gis/openlayers.html``.
149
150 ``OpenLayersWidget`` and :class:`OSMWidget` use the ``ol.js`` file hosted
151 on the ``cdn.jsdelivr.net`` content-delivery network. You can subclass
152 these widgets in order to specify your own version of the ``ol.js`` file in
153 the ``js`` property of the inner ``Media`` class (see
154 :ref:`assets-as-a-static-definition`).
155
156 ``OSMWidget``
157
158 .. class:: OSMWidget
159
160 This widget uses an OpenStreetMap base layer to display geographic objects
161 on. Attributes are:
162
163 .. attribute:: template_name
164
165 ``gis/openlayers-osm.html``
166
167 .. attribute:: default_lat
168 .. attribute:: default_lon
169
170 The default center latitude and longitude are ``47`` and ``5``,
171 respectively, which is a location in eastern France.
172
173 .. attribute:: default_zoom
174
175 The default map zoom is ``12``.
176
177 The :class:`OpenLayersWidget` note about JavaScript file hosting above also
178 applies here. See also this `FAQ answer`_ about ``https`` access to map
179 tiles.
180
181 .. _FAQ answer: https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site