dj-geocomplete-address 0.1.5
An app that allow manage address.
License: The MIT License
Keywords: django,google,addresses,address,countries,localities,regions,postal codes,geocode

Django Addresses
================

An app that allow manage addresses.

Installation
------------

To get the latest stable release from PyPi

.. code-block:: bash

    pip install dj-geocomplete-addresses

To get the latest commit from GitHub

.. code-block:: bash

    pip install -e git+git@github.com:amgcorp-tech/dj-addresses.git#egg=addresses

Configuration
-------------

Add ``addresses`` to your ``INSTALLED_APPS``

.. code-block:: python

    INSTALLED_APPS = (
        ...,
        'addresses',
    )

You can either store your Google API key in an environment variable as GOOGLE_API_KEY or you can specify the key in settings.py.

Add ``dj-addresses`` configuration variables in your ``settings.py``

.. code-block:: python

    GOOGLE_API_KEY = 'AIzaSyD--your-google-maps-key-SjQBE'

Or export into your ``environment``

.. code-block:: python

    export GOOGLE_API_KEY=<your-api-key>

Add the ``addresses`` URLs to your ``urls.py``

.. code-block:: python

    urlpatterns = [
        path('addresses/', include('addresses.urls')),
    ]

Include a menu items in your template:

.. code-block:: python

    {% load addresses_tags %}
    {% render_addresses_menu %}

If you need to modify the template, update the menu template found in

.. code-block:: python

   /templates/addresses/inc/sidebar_menu.html

Don't forget to migrate your database

.. code-block:: bash

    ./manage.py migrate addresses


Run server and preview your app in the browser

.. code-block:: bash

    ./manage.py runserver


Usage
-----

The rationale behind the model structure is centered on trying to make it easy to enter addresses that may be poorly defined.
The model field included uses Google Maps API v3 (via the nicely done geocomplete jquery plugin) to determine a proper address where possible.
However if this isn't possible the raw address is used and the user is responsible for breaking the address down into components.

It's currently assumed any address is represent-able using four components: country, state, locality and street address.
In addition, country code, state code and postal code may be stored, if they exist.


- AddressField

    To simplify storage and access of addresses, a subclass of ForeignKey named AddressField has been created.
    It provides an easy method for setting new addresses.

- ON_DELETE behavior of Address Field

    By default, if you delete an Address that is related to another object, Django's cascade behavior is used.
    This means the related object will also be deleted.
    You may also choose to set null=True when defining an address field to have the address set to Null instead of deleting the related object.

- The model:

.. code-block:: bash

    from addresses.models import AddressField

    class Person(models.Model):
        address1 = AddressField()
        address2 = AddressField(on_delete=models.CASCADE)
        address3 = AddressField(related_name='+', blank=True, null=True)

- The form:

.. code-block:: bash

    from addresses.forms import AddressField

    class PersonForm(forms.Form):
      address = AddressField()


- The template:

.. code-block:: bash

    <head>
        {{ form.media }} <!-- needed for JS/GoogleMaps lookup -->
    </head>
    <body>
        {{ form }}
    </body>