Metadata-Version: 1.1
Name: django-map-widgets
Version: 0.1.3
Summary: Map widgets for Django PostGIS fields
Home-page: https://github.com/erdem/django-map-widgets
Author: Erdem Ozkol
Author-email: erdemozkol@gmail.com
License: MIT
Description: ### 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
        
        ```python
        INSTALLED_APPS = [
             ...
            'django.contrib.sessions',
            'django.contrib.messages',
            'django.contrib.staticfiles',
            
            'map_widgets',
        ]
        ```
        
        ### 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 <a href="https://developers.google.com/maps/documentation/javascript/examples/places-autocomplete" target="_blank">Google Places Autocomplete</a>. (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.
        
        - <a href="https://github.com/erdem/django-map-widgets/blob/master/mapwidgets/constants.py">Timezone Center Locations</a>
        - <a href="https://gist.github.com/erdem/8c7d26765831d0f9a8c62f02782ae00d">countries.json</a>
        
        
        ### Usage 
        
        **settings.py**    
        ```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. 
        
        ```python
        MAP_WIDGETS = {
            "GooglePointFieldWidget": (
                ("zoom", 15),
                ("mapCenterLocation", [57.7177013, -16.6300491]),
            ),
            "GOOGLE_MAP_API_KEY": "<google-map-api-key>"
        }
        ```
        
        #### Django Admin
        ```python
        from mapwidgets.widgets import GooglePointFieldWidget
        
        class CityAdmin(admin.ModelAdmin):
            formfield_overrides = {
                models.PointField: {"widget": GooglePointFieldWidget}
            }
        ```
        
        #### Django Forms
        ```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
        
        ![](http://i.imgur.com/QpBycQu.png)
        
        #### 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*
                
        
        ```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
        ```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
        ![](https://cloud.githubusercontent.com/assets/1518272/18221609/2cac10fe-7178-11e6-9990-a93176693ef7.gif)
        ### Google Static Map Widget (ReadOnly)
        
        #### Settings
        
        Django map widgets provide all Google Static Map API features. Check out this <a href="https://developers.google.com/maps/documentation/static-maps/intro" target="_blank">link</a> for google static map features. 
        
        Here is the all default settings attribute for google static map widget.
        
        ```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**
        ```python
        MAP_WIDGETS = {
            "GoogleStaticMapWidget": (
                ("zoom", 15),
                ("size", "320x320"),
            ),
            "GoogleStaticMapMarkerSettings": (
                ("color", "green"),
            )
            "GOOGLE_MAP_API_KEY": "<google-map-api-key>"
        }
        ```
        
        **forms.py**
        ```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 working with <a href="https://developers.google.com/maps/documentation/static-maps/intro" target="_blank">Magnific Popup</a> 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.
        
        ```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
        
        ```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
Platform: any
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Programming Language :: Python
