django-map-widgets 0.1.7

Map widgets for Django PostGIS fields

Django Map Widgets
~~~~~~~~~~~~~~~~~~

Configurable, pluggable and more user friendly map widgets for Django
PostGIS fields.

Achievements
~~~~~~~~~~~~

The aim of the Django map widgets is to make all the Django widgets more
user friendly and configurable. Map widgets support major map services
(GoogleMaps, OpenStreetMap) for your geoDjango fields.

Installation
~~~~~~~~~~~~

::

pip install django-map-widgets

Add ‘map\_widgets’ to your ``INSTALLED_APPS`` in settings.py

.. code:: python

INSTALLED_APPS = [
...
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',

'mapwidgets',
]

Requirements
~~~~~~~~~~~~

Django map widgets require the jQuery framework, it does not import a
jQuery library. It's working with your global jQuery. If you will use
map widgets in Django Admin, you don't need to add a jQuery. Map widgets
work with Django Admin jQuery file.

PointField Map Widgets
~~~~~~~~~~~~~~~~~~~~~~

Google Map Widget
^^^^^^^^^^^^^^^^^

Settings
''''''''

- **GOOGLE\_MAP\_API\_KEY**: Put your Google API key

- **mapCenterLocationName**: You can give specific location name for
center of map. Map widget will found this location coordinates using
Google Places Autocomplete. (Optional)

- **mapCenterLocation**: You can give specific coordinates for center
of the map. Coordinates must be list type. ([latitude, longitude])
(Optional)

- **zoom** : Default zoom value.

Note: If there is no set value for the map center,
(mapCenterLocationName, mapCenterLocation) the widget will be
centered by the timezone setting of the project.

Check out this links.

- Timezone Center Locations
- countries.json

Usage
~~~~~

**settings.py**

.. code:: python

MAP_WIDGETS = {
"GooglePointFieldWidget": (
("zoom", 15),
("mapCenterLocationName", "london"),
),
"GOOGLE_MAP_API_KEY": "<google-map-api-key>"
}

If you want to give specific coordinates for center of the map, you can
update your settings file like that.

.. code:: python

MAP_WIDGETS = {
"GooglePointFieldWidget": (
("zoom", 15),
("mapCenterLocation", [57.7177013, -16.6300491]),
),
"GOOGLE_MAP_API_KEY": "<google-map-api-key>"
}

Django Admin
^^^^^^^^^^^^

.. code:: python

from mapwidgets.widgets import GooglePointFieldWidget

class CityAdmin(admin.ModelAdmin):
formfield_overrides = {
models.PointField: {"widget": GooglePointFieldWidget}
}

Django Forms
^^^^^^^^^^^^

.. code:: python

from mapwidgets.widgets import GooglePointFieldWidget

class CityAdminForm(forms.ModelForm):
class Meta:
model = City
fields = ("coordinates", "city_hall")
widgets = {
'coordinates': GooglePointFieldWidget,
'city_hall': GooglePointFieldWidget,
}

Preview
^^^^^^^

.. figure:: https://cloud.githubusercontent.com/assets/1518272/18732352/724dd098-805a-11e6-8eb4-6ba9b5e06a81.png
:alt:

jQuery Triggers
^^^^^^^^^^^^^^^

If you want develop your map UI on front-end side, you can use map
widget jQuery triggers.

- **google\_point\_map\_widget:marker\_create**: Triggered when user
create first marker on map. *callback params: lat, lng,
locationInputElem, mapWrapID*

- **google\_point\_map\_widget:marker\_change**: Triggered when user
change marker position on map. *callback params: lat, lng,
locationInputElem, mapWrapID*

- **google\_point\_map\_widget:marker\_delete**: Triggered when user
delete marker on map. *callback params: lat, lng, locationInputElem,
mapWrapID*

.. code:: javascript

$(document).on("google_point_map_widget:marker_create", function (e, lat, lng, locationInputElem, mapWrapID) {
console.log(locationInputElem); // django widget textarea widget (hidden)
console.log(lat, lng); // created marker coordinates
console.log(mapWrapID); // map widget wrapper element ID
});

$(document).on("google_point_map_widget:marker_change", function (e, lat, lng, locationInputElem, mapWrapID) {
console.log(locationInputElem); // django widget textarea widget (hidden)
console.log(lat, lng); // changed marker coordinates
console.log(mapWrapID); // map widget wrapper element ID
});

$(document).on("google_point_map_widget:marker_delete", function (e, lat, lng, locationInputElem, mapWrapID) {
console.log(locationInputElem); // django widget textarea widget (hidden)
console.log(lat, lng); // deleted marker coordinates
console.log(mapWrapID); // map widget wrapper element ID
})

Google Map Widget for Django Admin Inlines
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As you know Django Admin has inline feature and you can add an inline
row with dynamically. In this case, Django default map widget doesn't
initialize widget when created a new inline row.

If you want to use Google Map Widget on admin inlines with no issue, you
just need to use ``GooglePointFieldInlineWidget`` class.

Example
^^^^^^^

.. code:: python

from mapwidgets.widgets import GooglePointFieldInlineWidget

class DistrictAdminInline(admin.TabularInline):
model = District
extra = 3
formfield_overrides = {
models.PointField: {"widget": GooglePointFieldInlineWidget}
}

class CityAdmin(admin.ModelAdmin):
inlines = (DistrictAdminInline,)

Preview
^^^^^^^

|image0| ### Google Static Map Widget (ReadOnly)

Settings
^^^^^^^^

Django map widgets provide all Google Static Map API features. Check out
this link for google static map features.

Here is the all default settings attribute for google static map widget.

.. code:: python

MAP_WIDGETS = {
"GoogleStaticMapWidget": (
("zoom", 15),
("size", "480x480"),
("scale", ""),
("format", ""),
("maptype", ""),
("path", ""),
("visible", ""),
("style", ""),
("language", ""),
("region", "")
),

"GoogleStaticMapMarkerSettings": (
("size", "normal"),
("color", ""),
("icon", ""),
)
"GOOGLE_MAP_API_SIGNATURE": "",
"GOOGLE_MAP_API_KEY": "",
}

Usage
'''''

If you are not using specific features on Google Static Map API, you
just need to update ``GOOGLE_MAP_API_KEY`` value in your Django settings
file. If you need also individual size map images, you can pass ``size``
and ``zoom`` parameter for each ``GoogleStaticMapWidget`` class.

Example
^^^^^^^

**settings.py**

.. code:: python

MAP_WIDGETS = {
"GoogleStaticMapWidget": (
("zoom", 15),
("size", "320x320"),
),
"GoogleStaticMapMarkerSettings": (
("color", "green"),
)
"GOOGLE_MAP_API_KEY": "<google-map-api-key>"
}

**forms.py**

.. code:: python

from mapwidgets.widgets import GoogleStaticMapWidget

class CityDetailForm(forms.ModelForm):

class Meta:
model = City
fields = ("name", "coordinates", "city_hall")
widgets = {
'coordinates': GoogleStaticMapWidget,
'city_hall': GoogleStaticMapWidget(zoom=12, size="240x240"),
}

Google Static Map Overlay Widget (ReadOnly)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This widget is working with Magnific Popup jQuery plugin.

Usage
'''''

You can use also all static map features in this widget. Besides you can
give a ``thumbnail_size`` value.

Here is the all default settings attribute for google static overlay map
widget.

.. code:: python

MAP_WIDGETS = {
"GoogleStaticMapMarkerSettings": (
("size", "normal"),
("color", ""),
("icon", ""),
),

"GoogleStaticOverlayMapWidget": (
("zoom", 15),
("size", "480x480"),
("thumbnail_size", "160x160"),
("scale", ""),
("format", ""),
("maptype", ""),
("path", ""),
("visible", ""),
("style", ""),
("language", ""),
("region", "")
),

"GOOGLE_MAP_API_SIGNATURE": "",
"GOOGLE_MAP_API_KEY": "",
}

Example
^^^^^^^

.. code:: python

from mapwidgets.widgets import GoogleStaticOverlayMapWidget


class CityDetailForm(forms.ModelForm):

class Meta:
model = City
fields = ("name", "coordinates", "city_hall")
widgets = {
'coordinates': GoogleStaticOverlayMapWidget,
'city_hall': GoogleStaticOverlayMapWidget(zoom=12, size="640x640", thumbnail_size="50x50"),
}

Preview
^^^^^^^

.. figure:: https://cloud.githubusercontent.com/assets/1518272/18732296/18f1813e-805a-11e6-8801-f1f48ed02a9c.png
:alt:

.. |image0| image:: https://cloud.githubusercontent.com/assets/1518272/18221609/2cac10fe-7178-11e6-9990-a93176693ef7.gif