The Forms library

django-geoportail ships with rich form widgets, on which your users can draw geographic features. The forms library extends Django’s built-in library, and switching to django-geoportail’s form library is as simple as changing:

from django import forms

to:

from geoportal import forms

All the fields and widgets from django’s form library are available, plus a set of geographic fields and widgets. All the geographic widgets require javascript, so you have to make sure your users have it enabled.

Like with the template library, you need to load the javascript library each time you render a rich geographic widget in a template. See Loading the javascript library

Fields

The following fields are available. Each field correspond to a geographic model field.

• PointField
• MultiPointField
• LineStringField
• MultiLineStringField
• PolygonField
• MultiPolygonField

Basic usage

Suppose you need a simple form to let users enter a name and point to a location on a map. The form can be written as follows.

from geoportal import forms

class LocationForm(forms.Form):
    name = forms.CharField(max_length=200)
    location = forms.PointField()

When the form is rendered in the template, a map is displayed and the user can draw a point on the map. The drawn feature will be validated as a geographic field and can be saved to the database.

Integration with ModelForm ‘s

Let’s define a model with some geographic fields and generate a ModelForm for it:

# models.py
from django.contrib.gis.db import models

class Location(models.Model):
    name = models.CharField(max_length=255)
    point = models.PointField()

Unfortunately, it is not possible to automatically generate a rich widget for geographic fields (geodjango already sets the default widget to a <textarea>). However, it is very simple to change the default widget to a rich one:

# forms.py
from geoportal import forms
from models import Location

class LocationForm(forms.ModelForm):
    point = forms.PointField()
    class Meta:
        model = Location

Using a ModelForm and overriding the widget for geographic fields can be easier than manually declaring all the different fields.

Customizing the form widget

By default, all geographic widgets use the default or overridden settings for rendering the form fields (see Settings reference). Those settings can be overridden on a per-widget basis to allow better customization. This is done by manually specifying the widget instance with its options to the form field.

The following widgets are available:

• PointWidget
• MultiPointWidget
• LineStringWidget
• MultiLineStringWidget
• PolygonWidget
• MultiPolygonWidget

Each field has its default widget: a PointField has a PointWidget, a MultiPolygonField has a MultiPolygonWidget and so on. When you specify the widget, make sure it corresponds to the type of the field.

The following attributes can be passed to a form widget:

• width: the width of the map, in pixels.
• height: the height of the map, in pixels.
• color: the color of the drawn feature, in rrggbb format.
• opacity: the opacity of the inner part of the feature (for polygons), between 0 and 1.
• default_zoom: the zoom level for a form field with no value.
• default_lon: the longitude for a form field with no value.
• default_lat: the latitude for a form field with no value.
• layers: the layers to display on the map. See Admin options reference for the syntax.
• srid: the SRID to use with this field.

Let us rewrite the previous form to customize the map:

# forms.py
from geoportal import forms
from models import Location

class LocationForm(forms.ModelForm):
    point = forms.PointField(widget=forms.PointWidget(attrs={
            'width': 300,
            'height': 300,
            'srid': 900913,
            'layers': (
                        ('maps', 1),
                        ('photos', 0.3)
                      ),
            },
    ))
    class Meta:
        model = Location

While the syntax can be a little verbose, it allows a lot of customization. Also, remember to set the default settings: if you need to display 500x300px maps in the admin, the templates and the forms, set it in your settings and you’ll never have to specify it again.