citizenfish / django-maps

django-maps

Overview

A django app to provide maps and map widgets for django projects. It uses mapbox-libre to provide the maps and widgets for various map styles and features.

It was written to replace to standard django admin map widget and later to provide a more flexible solution for the client side maps in various of our projects @ nautoguide

You can see examples of the maps in action at geovey , brixham steps

Roadmap

Currently the app is in a beta state and is being used in production on a number of projects. The roadmap is to stablise the features and then improve the documentation and testing. At that point I will rewrite the javascript to use a class based approach as the current code is a bit of a mess due to the evolution of the project.

Support

If you need help or support then please raise an issue on the github project page. Always happy to help and improve the project. We will always consider new features and improvements and are happy to take pull requests or paid work to add features at speed.

Install

Local dev mode using built package

python3 -m pip install --user ~/projects/django-maps/dist/django-maps-0.1.tar.gz

Local dev mode in edit mode

sudo python3 -m pip install --user -e ~/projects/django-maps

Despite usermode you may need the sudo and note that you will need to restart the runserver process on the local project your editing to see some changes

From github

pip install git+https://github.com/nautoguide/django-maps.git

If your using requirements.txt

git+https://github.com/nautoguide/django-maps.git

Quick start

Add 'maps' to your INSTALLED_APPS apps

    INSTALLED_APPS = [
        ...
        'maps',
    ]

If you need any API KEYS then add them to your settings.py

MAP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxx

Adding a map location to your model

in models.py

from maps.fields import Location


class Feature(models.Model):
    title = models.CharField(null=True, max_length=200, help_text="Title of feature")
    location = Location()

This will use a default map, if you want to provide settings to the admin map then in admin.py

defs = {
    'attrs': {
        'map_center': [-4.142467699252791,50.369191887081485]
    }
}

class MyModelAdmin(admin.ModelAdmin):
    .....
    formfield_overrides = {
        Location: {"widget": LocationWidget(attrs=defs['attrs'])},
    }

Using maps in your templates

To any template where you need a map add:

{% load maps %}

Then for a map add

<!- Simple map  -->
{% mapbox_simple json_url=json_url icons=icons style='/mapfiles/?file=os-styles.json' maxZoom=20 center='[-3.510486, 50.395822]' %}

<!- Simple map with links -->
{% mapbox_cluster json_url %}

json_url string

This points the map at the location to get its geojson, normally this would be an api end point that returns geojson from the database

links True|False

Add a links layer base on the geojson.

icons array

For icon you need to pass in an array of icons to use and their references. A good way to do this is have them defined in your view in a single place and then pass them into the view context that uses the map:

icons = [
    {
        'name': 'sailor',
        'url': "/static/map_images/map_sailor.png",
    },
    {
        'name': 'ship',
        'url': "/static/map_images/map_ship.png",
    },
    {
        'name': 'homeport',
        'url': "/static/map_images/map_artefact.png",
    },
    {
        'name': 'memorial',
        'url': "/static/map_images/map_memorial.png",
    },
    {
        'name': 'school',
        'url': "/static/map_images/map_school.png",
    },
    {
        'name': 'submarine',
        'url': "/static/map_images/map_submarine.png",
    }
]

def map(request):
    context = {
        'page_title': 'Mappy',
        'json_url': "/Map/API/json/",
        'icons': icons
    }
    return render(request, 'map.html', context)

{% load maps %}

{% mapbox_simple json_url=json_url links=True icons=icons %}

To use the goejson serializer:

from maps.serializers import feature_serialize_geojson

geojson = feature_serialize_geojson(features, False)

If you need to use the mapfiles included with maps then you need to include a urls.py to cope with it as we use template processing to deal with live and local urls:

from maps.views import mapfiles


urlpatterns = [
    path('Admin/',  admin.site.urls),
   ....
    path('mapfiles/', mapfiles)

] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Development

Build the package

python3 setup.py sdist