# Documentation Django 5.2.8

# API des formulaires GeoDjango

GeoDjango propose quelques champs et composants de formulaires spécialisés afin d’afficher et de modifier visuellement des données géolocalisées sur une carte. Par défaut, ils utilisent des cartes motorisées par OpenLayers, avec une couche de base WMS fournie par la NASA.

## Paramètres de champs

En plus des paramètres de champs de formulaires habituels, les champs de formulaires GeoDjango acceptent les paramètres facultatifs suivants.

### `srid`

Field.srid

  Il s’agit du code SRID utilisé pour transformer la valeur du champ. Par exemple, si le SRID du composant de carte est différent du SRID utilisé plus généralement par votre application ou base de données, le champ convertit automatiquement les valeurs d’entrée dans ce SRID.

### `geom_type`

Field.geom_type

  Cet attribut n’a généralement pas besoin d’être défini ou modifié, car il est automatiquement défini en fonction de la classe du champ. Il correspond au nom d’objet géométrique du standard OpenGIS.

## Classes de champs de formulaires

### `GeometryField`

class GeometryField

### `PointField`

class PointField

### `LineStringField`

class LineStringField

### `PolygonField`

class PolygonField

### `MultiPointField`

class MultiPointField

### `MultiLineStringField`

class MultiLineStringField

### `MultiPolygonField`

class MultiPolygonField

### `GeometryCollectionField`

class GeometryCollectionField

## Composants de formulaires

Les composants de formulaires GeoDjango permettent d’afficher et de modifier des données géographiques visuellement sur une carte. Notez qu’aucun des composants actuellement disponibles ne prend en charge les objets géométriques 3D, ce qui fait que les champs géométriques se rabattent sur un composant `Textarea` s’ils ont affaire à de tels objets.

### Attributs de composants

Les composants GeoDjango sont basés sur les gabarits, ce qui fait que leurs attributs sont majoritairement différents des autres attributs de composants Django.

BaseGeometryWidget.base_layer
  New in Django 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`).

BaseGeometryWidget.geom_type

  Le type de géométrie OpenGIS, généralement défini par le champ de formulaire.

BaseGeometryWidget.map_srid

  Code SRID utilisé par la carte (la valeur par défaut est 4326).

BaseGeometryWidget.display_raw

  Valeur booléenne indiquant si une boîte de saisie de texte affichant la représentation sérialisée de l’objet géométrique en cours est visible, principalement à des fins de débogage (la valeur par défaut est `False`).

BaseGeometryWidget.supports_3d

  Indique si le composant prend en charge l’édition de données 3D (la valeur par défaut est `False`).

BaseGeometryWidget.template_name

  Le gabarit utilisé pour produire le composant de carte.

Vous pouvez transmettre des attributs de composants de la même façon que pour tout autre composant Django. Par exemple :

    from django.contrib.gis import forms

    class MyGeoForm(forms.Form):
        point = forms.PointField(widget=forms.OSMWidget(attrs={"display_raw": True}))

### Classes de composants

`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 `base_layer` class attribute.

`OpenLayersWidget`

class OpenLayersWidget

  This is the default widget used by all GeoDjango form fields. Attributes are:

  base_layer
    New in Django 6.0.

    `nasaWorldview`

  template_name

    `gis/openlayers.html`.

  map_srid

    `3857`

  `OpenLayersWidget` and `OSMWidget` include the `ol.js` and `ol.css` files hosted on the `cdn.jsdelivr.net` content-delivery network. These files can be overridden by subclassing the widget and setting the `js` and `css` properties of the inner `Media` class (see Fichiers annexes définis statiquement).

  External assets with CSP

  When `ContentSecurityPolicyMiddleware` is enabled, the default OpenLayers CDN assets (`ol.js` and `ol.css`) will be blocked unless explicitly allowed. This can be addressed in one of two ways: serve assets locally by subclassing the widget and provide local copies of the JavaScript and CSS files, or allow the CDN in the CSP policy.

  For example, to allow the default NASA Worldview base layer (replace `x.y.z` with the actual version):

      from django.utils.csp import CSP

      SECURE_CSP = {
          "default-src": [CSP.SELF],
          "script-src": [CSP.SELF, "https://cdn.jsdelivr.net/npm/ol@x.y.z/dist/ol.js"],
          "style-src": [CSP.SELF, "https://cdn.jsdelivr.net/npm/ol@x.y.z/ol.css"],
          "img-src": [CSP.SELF, "https://*.earthdata.nasa.gov"],
      }

`OSMWidget`

class OSMWidget

  This widget specialized `OpenLayersWidget` and uses an OpenStreetMap base layer to display geographic objects on. Attributes are:

  base_layer
    New in Django 6.0.

    `osm`

  default_lat
  default_lon

    Les latitude et longitude du centre sont respectivement `47` et `5` par défaut, ce qui correspond à un emplacement à l’est de la France.

  default_zoom

    Le zoom de carte par défaut est `12`.

  The `OpenLayersWidget` note about using external assets also applies here. See also this FAQ answer about `https` access to map tiles.

  OpenStreetMap tiles with CSP

  This widget uses OpenStreetMap tiles instead of NASA Worldview. If Content Security Policy enabled, both the OpenLayers CDN resources (as required by `OpenLayersWidget`) and the OpenStreetMap tile servers must be allowed:

      from django.utils.csp import CSP

      SECURE_CSP = {
          # other directives
          "img-src": [CSP.SELF, "https://tile.openstreetmap.org"],
      }

  Changed in Django 6.0:

  The `OSMWidget` no longer uses a custom template. Consequently, the `gis/openlayers-osm.html` template was removed.

### Customizing the base layer used in OpenLayers-based widgets

New in Django 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:

`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"]