django-osm-field

Contents:

Installation

Install django-osm-field into your virtual environment or you site-packages using pip:

$ pip install django-osm-field

To make django-osm-field available in your Django project, you first have to add it to the INSTALLED_APPS in your settings.py. If you are unsure where to put it, just append it:

INSTALLED_APPS = (
    ...
    'osm_field',
    ...
)

Usage

Model Layer

You need to add three model fields to your model:

  1. OSMField
  2. LatitudeField
  3. LongitudeField

django-osm-field expects them to have a certain name schema: The OSMField defines the base name, the LatitudeField and LongitudeField have the same name appended with _lat and _lon respectively. See the following example to get an idea:

from django.db import models

from osm_field.fields import LatitudeField, LongitudeField, OSMField


class MyModel(models.Model):
    location = OSMField()
    location_lat = LatitudeField()
    location_lon = LongitudeField()

It is possible, though, to overwrite the default naming for latitude and longitude fields by giving their names as arguments to the OSMField:

class MyModel(models.Model):
    location = OSMField(lat_field='latitude', lon_field='longitude')
    latitude = LatitudeField()
    longitude = LongitudeField()

Form Layer

from django import forms

from .models import MyModel


class MyModelForm(forms.ModelForm):

    class Meta:
        fields = ('location', 'location_lat', 'location_lon', )
        model = MyModel

View Layer

from django.views.generic import CreateView

from .forms import MyModelForm
from .models import MyModel


class MyCreateView(CreateView):
    form_class = MyModelForm
    model = MyModel

Template Layer

django-osm-field shipps with a minimized jQuery version. To access it in a template use the static templatetag:

<script type="text/javascript" src="{% static "js/vendor/jquery-2.1.0.min.js" %}"></script>

You can of course load jQuery from a CDN as well:

<script type="text/javascript" src="//code.jquery.com/jquery-2.1.0.min.js"></script>

To get the front-end to work, you also need to include some CSS and JavaScript files. You can do this by simply using {{ form.media }} or by adding those lines explicitly:

<link href="{% static "css/vendor/leaflet.css" %}" type="text/css" media="screen" rel="stylesheet" />
<link href="{% static "css/osm_field.css" %}" type="text/css" media="screen" rel="stylesheet" />
<script type="text/javascript" src="{% static "js/vendor/leaflet.js" %}"></script>
<script type="text/javascript" src="{% static "js/osm_field.js" %}"></script>

In the end your template should look similar to this:

{% load static %}<!DOCTYPE HTML>
<html>
  <head>
    <title></title>
    <link rel="stylesheet" href="{% static "css/example.css" %}">
    <!-- Either serve jQuery yourself -->
    <script type="text/javascript" src="{% static "js/vendor/jquery-2.1.0.min.js" %}"></script>
    <!-- or from a CDN -->
    <script type="text/javascript" src="//code.jquery.com/jquery-2.1.0.min.js"></script>
  </head>
  <body>
    {{ form.media }}
    <form action="" method="post">
      {% csrf_token %}
      {{ form.as_p }}
      <input type="submit" value="Save" />
    </form>
  </body>
</html>

Credits

Contributors

  • Drew Hubl
  • Sascha Narr
  • Kamil Gałuszka

Project has been started by Sinnwerkstatt Medienagentur GmbH in April 2014.

History

Unreleased

0.4.0 (2020-04-17)

  • Added support for Django 2.2 and 3.0 and dropped support for everything before.

0.3.1 (2017-02-06)

  • Properly rendered widgets in formsets
  • Added preliminary support for Django 1.11

0.3.0 (2016-07-23)

  • Added support for Django 1.8, 1.9, 1.10
  • Dropped support for Django 1.4, 1.5, 1.6
  • Switched from MapQuest to CartoDB (#15)
  • Fixed bug in formsets (#7)
  • Added location_data field

0.2.0 (2014-11-10)

  • Added support for Django 1.7 migrations (#2)
  • Updated styling (#1)
  • Forced map refresh on show
  • Added tests
  • Changed license from BSD to MIT
  • Added support for non-default named form fields (those not ending with _lat and _lon respectively).
  • Added documentation

0.1.4 (2014-06-02)

  • Add minified JavaScript and CSS sources

0.1.3 (2014-05-28)

  • jQuery is not automatically added by the widgets media class anymore

0.1.0 (2014-05-20)

  • First release on PyPI.

References

Fields

class osm_field.fields.LatitudeField(*args, **kwargs)

Bases: django.db.models.fields.FloatField

Bases: django.db.models.FloatField

All default field options.

The validators parameter will be appended with validate_latitude() if not already present.

formfield(**kwargs)
Returns:A FloatField with max_value 90 and min_value -90.
class osm_field.fields.Location(lat, lon, text)

Bases: object

A wrapper class bundling the description of a location (text) and its geo coordinates, latitude (lat) and longitude (lon).

Parameters:
  • lat (float) – The latitude
  • lon (float) – The longitude
  • str – The description
class osm_field.fields.LongitudeField(*args, **kwargs)

Bases: django.db.models.fields.FloatField

Bases: django.db.models.FloatField

All default field options.

The validators parameter will be appended with validate_longitude() if not already present.

formfield(**kwargs)
Returns:A FloatField with max_value 180 and min_value -180.
class osm_field.fields.OSMField(*args, **kwargs)

Bases: django.db.models.fields.TextField

Bases: django.db.models.TextField

Parameters:
  • lat_field (str) – The name of the latitude field. None (and thus standard behavior) by default.
  • lon_field (str) – The name of the longitude field. None (and thus standard behavior) by default.

All default field options.

check(**kwargs)
contribute_to_class(cls, name)

Register the field with the model class it belongs to.

If private_only is True, create a separate instance of this field for every subclass of cls, even if cls is not an abstract model.

deconstruct()

Return enough information to recreate the field as a 4-tuple:

  • The name of the field on the model, if contribute_to_class() has been run.
  • The import path of the field, including the class:e.g. django.db.models.IntegerField This should be the most portable version, so less specific may be better.
  • A list of positional arguments.
  • A dict of keyword arguments.

Note that the positional or keyword arguments must contain values of the following types (including inner values of collection types):

  • None, bool, str, int, float, complex, set, frozenset, list, tuple, dict
  • UUID
  • datetime.datetime (naive), datetime.date
  • top-level classes, top-level functions - will be referenced by their full import path
  • Storage instances - these have their own deconstruct() method

This is because the values here must be serialized into a text format (possibly new Python code, possibly JSON) and these are the only types with encoding handlers defined.

There’s no need to return the exact way the field was instantiated this time, just ensure that the resulting field is the same - prefer keyword arguments over positional ones, and omit parameters with their default values.

formfield(**kwargs)
Returns:A OSMFormField with a OSMWidget.
latitude_field_name

The name of the related LatitudeField.

longitude_field_name

The name of the related LongitudeField.

Forms

class osm_field.forms.OSMFormField(*, max_length=None, min_length=None, strip=True, empty_value='', **kwargs)

Bases: osm_field.forms.PrefixedFormFieldMixin, django.forms.fields.CharField

class osm_field.forms.PrefixedBoundField(form, field, name)

Bases: django.forms.boundfield.BoundField

A bound field that passes the form’s prefix into the widget’s attrs

as_widget(widget=None, attrs=None, only_initial=False)

Render the field by rendering the passed widget, adding any HTML attributes passed as attrs. If a widget isn’t specified, use the field’s default widget.

class osm_field.forms.PrefixedFormFieldMixin

Bases: object

A form field that binds to a custom bound field class, so we can pass the form’s prefix into the widget’s attrs

get_bound_field(form, field_name)

For Django 1.9+

Return a BoundField instance that will be used when accessing the form field in a template.

Validators

osm_field.validators.validate_latitude(value)

Validates that the given value does not exceed the range [-90, 90].

Raises:Raises a ValidationError if value is not within the range.
osm_field.validators.validate_longitude(value)

Validates that the given value does not exceed the range [-180, 180].

Raises:Raises a ValidationError if value is not within the range.

Widgets

class osm_field.widgets.OSMWidget(lat_field, lon_field, data_field=None, attrs=None)

Bases: django.forms.widgets.TextInput

Adds a OpenStreetMap Leaflet dropdown map to the front-end once the user focuses the form field. See the usage chapter on how to integrate the CSS and JavaScript code.

media
render(name, value, attrs=None, renderer=None)

Render the widget as an HTML string.

render_osmfield(id_)

Indices and tables