Metadata-Version: 1.1
Name: wagtailgeowidget
Version: 5.0.0
Summary: A Google Maps widget for Wagtail that supports both GeoDjango PointField, StreamField and CharField.
Home-page: https://github.com/frojd/wagtail-geo-widget
Author: Fröjd
Author-email: martin@marteinn.se
License: MIT
Description: |Build Status| |PyPI version|
        
        Wagtail-Geo-Widget
        ==================
        
        A Google Maps widget for Wagtail that supports both GeoDjango
        PointField, StreamField and the standard CharField.
        
        .. figure:: https://raw.githubusercontent.com/frojd/wagtail-geo-widget/develop/img/screen1.png
           :alt: Screen1
        
           Screen1
        
        Requirements
        ------------
        
        -  Python 2.7 / Python 3.5+
        -  Wagtail 2.3+ and Django
        -  A API key for Google Maps
        
        Installation
        ------------
        
        Install the library with pip:
        
        ::
        
           $ pip install wagtailgeowidget
        
        Quick Setup
        -----------
        
        Make sure ``wagtailgeowidget`` is added to your ``INSTALLED_APPS``.
        
        .. code:: python
        
           INSTALLED_APPS = (
               # ...
               'wagtailgeowidget',
           )
        
        Obtain a Google Maps API key and add it to your Django settings
        ``GOOGLE_MAPS_V3_APIKEY``
        
        This should be enough to get started.
        
        Usage
        -----
        
        -  `Standard
           CharField <https://github.com/Frojd/wagtail-geo-widget/blob/develop/README.md#standard-charfield>`__
        -  `StreamField <https://github.com/Frojd/wagtail-geo-widget/blob/develop/README.md#streamfield>`__
        -  `GeoDjango/PointField <https://github.com/Frojd/wagtail-geo-widget/blob/develop/README.md#geodjango-pointfield>`__
        
        Standard CharField
        ------------------
        
        Define a CharField representing your location, then add a GeoPanel.
        
        .. code:: python
        
           from django.db import models
           from wagtailgeowidget.edit_handlers import GeoPanel
        
        
           class MyPage(Page):
               location = models.CharField(max_length=250, blank=True, null=True)
        
               content_panels = Page.content_panels + [
                   GeoPanel('location'),
               ]
        
        The data is stored as a ``GEOSGeometry`` string (Example:
        ``SRID=4326;POINT(17.35448867187506 59.929179873751934)``. To use the
        data, we recommend that you add helper methods to your model.
        
        .. code:: python
        
           from django.utils.functional import cached_property
           from wagtailgeowidget.helpers import geosgeometry_str_to_struct
        
           class MyPage(Page):
               # ...
        
               @cached_property
               def point(self):
                   return geosgeometry_str_to_struct(self.location)
        
               @property
               def lat(self):
                   return self.point['y']
        
               @property
               def lng(self):
                   return self.point['x']
        
        NOTE: While this implementation is quick and easy to setup, the drawback
        is that it will prevent you from making spatial queries, if that is what
        you need, use the `GeoDjango/Pointer field <#geodjango-pointfield>`__
        implementation instead.
        
        With an address field
        ~~~~~~~~~~~~~~~~~~~~~
        
        The panel accepts an ``address_field`` if you want to use the map in
        coordination with a geo-lookup (like the screenshot on top).
        
        .. code:: python
        
           from django.db import models
           from django.utils.translation import ugettext as _
           from wagtail.admin.edit_handlers import FieldPanel, MultiFieldPanel
           from wagtailgeowidget.edit_handlers import GeoPanel
        
        
           class MyPageWithAddressField(Page):
               address = models.CharField(max_length=250, blank=True, null=True)
               location = models.CharField(max_length=250, blank=True, null=True)
        
               content_panels = Page.content_panels + [
                   MultiFieldPanel([
                       FieldPanel('address'),
                       GeoPanel('location', address_field='address'),
                   ], _('Geo details')),
               ]
        
        For more examples, look at the
        `example <https://github.com/Frojd/wagtail-geo-widget/blob/develop/example/geopage/models.py#L82>`__.
        
        StreamField
        -----------
        
        To add a map in a StreamField, import and use the GeoBlock.
        
        .. code:: python
        
           from wagtail.core.models import Page
           from wagtail.core.fields import StreamField
           from wagtailgeowidget.blocks import GeoBlock
        
           class GeoStreamPage(Page):
               body = StreamField([
                   ('map', GeoBlock()),
               ])
        
               content_panels = Page.content_panels + [
                   StreamFieldPanel('body'),
               ]
        
        The data is stored as a json struct and you can access it by using
        value.lat / value.lng
        
        .. code:: html
        
           <article>
               {% for map_block in page.stream_field %}
                   <hr />
                   {{ map_block.value }}
                   <p>Latitude: {{ map_block.value.lat}}</p>
                   <p>Longitude: {{ map_block.value.lng }}</p>
               {% endfor %}
           </article>
        
        .. _with-an-address-field-1:
        
        With an address field
        ~~~~~~~~~~~~~~~~~~~~~
        
        Make sure you define a field representing the address at the same level
        as your GeoBlock, either in the StreamField or in a StructBlock.
        
        .. code:: python
        
           from wagtail.admin.edit_handlers import StreamFieldPanel
           from wagtailgeowidget.blocks import GeoBlock, GeoAddressBlock
        
        
           class GeoStreamPage(Page):
               body = StreamField([
                   ('map_struct', blocks.StructBlock([
                       ('address', GeoAddressBlock(required=True)),
                       ('map', GeoBlock(address_field='address')),
                   ]))
        
               ])
        
               content_panels = Page.content_panels + [
                   StreamFieldPanel('body'),
               ]
        
        For more examples, look at the
        `example <https://github.com/Frojd/wagtail-geo-widget/blob/develop/example/geopage/models.py#L64>`__.
        
        GeoDjango (PointField)
        ----------------------
        
        First make sure you have
        `GeoDjango <https://docs.djangoproject.com/en/1.10/ref/contrib/gis/>`__
        correctly setup and a PointField field defined in your model, then add a
        GeoPanel among your content_panels.
        
        .. code:: python
        
           from django.contrib.gis.db import models
           from wagtailgeowidget.edit_handlers import GeoPanel
        
        
           class MyPage(Page):
               location = models.PointField(srid=4326, null=True, blank=True)
        
               content_panels = Page.content_panels + [
                   GeoPanel('location'),
               ]
        
        .. _with-an-address-field-2:
        
        With an address field
        ~~~~~~~~~~~~~~~~~~~~~
        
        The panel accepts an ``address_field`` if you want to use the map in
        coordination with a geo-lookup (like the screenshot on top).
        
        .. code:: python
        
           from django.contrib.gis.db import models
           from django.utils.translation import ugettext as _
           from wagtail.admin.edit_handlers import FieldPanel, MultiFieldPanel
           from wagtailgeowidget.edit_handlers import GeoPanel
        
        
           class MyPageWithAddressField(Page):
               address = models.CharField(max_length=250, blank=True, null=True)
               location = models.PointField(srid=4326, null=True, blank=True)
        
               content_panels = Page.content_panels + [
                   MultiFieldPanel([
                       FieldPanel('address'),
                       GeoPanel('location', address_field='address'),
                   ], _('Geo details')),
               ]
        
        For more examples, look at the
        `example <https://github.com/Frojd/wagtail-geo-widget/blob/develop/example/geopage/models.py#L35>`__.
        
        Settings
        --------
        
        -  ``GOOGLE_MAPS_V3_APIKEY``: API key for Google Maps (required).
        -  ``GOOGLE_MAPS_V3_LANGUAGE``: The language you want to set for the map
           interface (default is ``en``)
        -  ``GEO_WIDGET_DEFAULT_LOCATION``: Default map location when no
           coordinates are set, accepts a dict with lat and lng keys (default is
           ``{'lat': 59.3293, 'lng': 18.0686}`` that is Stockholm/Sweden).
        -  ``GEO_WIDGET_ZOOM``: Default zoom level for map (7 is default).
        
        FAQ
        ---
        
        Is it possible to hide the lat/lng field?
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Yes, by passing ``hide_latlng=True`` to the GeoPanel.
        
        .. code:: python
        
           GeoPanel('location', address_field='address', hide_latlng=True)
        
        It is currently not supported in streamfields.
        
        Roadmap
        -------
        
        -  ☒ Editable map widget for GeoDjango PointerField
        -  ☒ Global default map location
        -  ☒ Streamfield map widget
        
        Contributing
        ------------
        
        Want to contribute? Awesome. Just send a pull request.
        
        License
        -------
        
        Wagtail-Geo-Widget is released under the `MIT
        License <http://www.opensource.org/licenses/MIT>`__.
        
        .. |Build Status| image:: https://travis-ci.org/Frojd/wagtail-geo-widget.svg?branch=master
           :target: https://travis-ci.org/Frojd/wagtail-geo-widget
        .. |PyPI version| image:: https://badge.fury.io/py/wagtailgeowidget.svg
           :target: https://badge.fury.io/py/wagtailgeowidget
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Classifier: Topic :: Utilities
