django-postal's Introduction

django-postal

(Based upon http://github.com/mthornhill/django-postal)

Warning

This project is in ALPHA mode and the API is in flux.

A django application that provides a location agnostic model for postal addresses.

The motivation behind this project is that most countries have different forms of postal addresses e.g. http://www.bitboost.com/ref/international-address-formats.html , http://en.wikipedia.org/wiki/Address_%28geography%29

This app assumes that all postal addresses worldwide can be made up of 5 optional address lines plus a country code.

It then localizes the title of each line dependant on the country selected. Further information on each address line can be gleaned from django.contrib.localflavor fields and widgets e.g. for the UK :

from django import forms
from django.utils.translation import ugettext_lazy as _
from django.contrib.localflavor.uk.forms import UKPostcodeField, UKCountySelect

from postal.forms import PostalAddressForm

class GBPostalAddressForm(PostalAddressForm):
    line1 = forms.CharField(label=_(u"Street"), required=False, max_length=50)
    line2 = forms.CharField(label=_(u"Area"), max_length=50)
    city = forms.CharField(label=_(u"Town"), max_length=50)
    state = forms.CharField(label=_(u"County"), widget=UKCountySelect, max_length=50)
    code = UKPostcodeField(label=_(u"Postcode"))

It is hoped that various contributors will contribute address formats per country and that eventually this address information could find it's way back in to django.contrib.localflavor

Dependencies

django-countries (http://pypi.python.org/pypi/django-countries)

Usage

1. Add django-countries and django-postal to your INSTALLED_APPS in settings.py e.g.:

INSTALLED_APPS = (
    "countries",
    "postal",
    ...
    )

Add a postal_form to your templates:

some_template.html
{% load postal_tags %}
<html>
    <head>
        <script src="{{ MEDIA_URL }}js/jquery-1.4.2.min.js" type="text/javascript" charset="utf-8"></script>
    </head>
<body>
    <form method="POST" action="">
        {% csrf_token %}
        {{form.as_p}}
        {% monitor_country_change %}
        <script type="text/javascript">
            $('form').monitor_country_change('#id_country');
        </script>
        <input type="submit"/>
    </form>
</body>
</html>

Changing the country in the form above should localise the address form.

In your view code add code to save the addressform e.g.:

from postal.forms import PostalAddressForm

def my_view(request)
    if request.method == "POST":
        address_form = PostalAddressForm(request.POST, prefix=request.POST.get('prefix', ''))
        address_form.save()

How to use localised addresses

Address localisation is turned on by default. To turn off Address l10n in settings.py set:

POSTAL_ADDRESS_L10N = False

Customize address labels and requirement

If you wish to customize the address labels and whether the address line is required or not, you can add the following variables to settings.py:

POSTAL_ADDRESS_LINE1, POSTAL_ADDRESS_LINE2, POSTAL_ADDRESS_CITY, POSTAL_ADDRESS_STATE, POSTAL_ADDRESS_CODE

Each of these variables is set to a tuple of the format ('label', True/False) label is used to label the field, and the second boolean value sets whether the field is required or not, e.g.:

POSTAL_ADDRESS_LINE1 = ("Department", True)

BUILD HISTORY

0.9.6 Remove django-piston requirement Fixed django 1.7 compatibility issues Added Italian Postal Address Form (Thanks to Francesco Facconi for above changes)

0.7.2 Major refactor where all models removed so django-postal just provides localized forms. It is up to the supporting project to define their own address models

0.4 Don't enforce uniqueness on postal addresses

Developers, How to Contribute

Git foo:

$ git clone [email protected]:mthornhill/django-postal.git
$ cd django-postal
$ virtualenv . --no-site-packages
$ source bin/activate
$ python bootstrap.py
$ bin/buildout -v
$ bin/django syncdb
$ bin/django test postal
$ bin/django runserver

Browse to http://localhost:8000

New countries can be added to the src/postal/forms folder by their 2 letter country code e.g. us

Each country folder contains an __init__.py and a forms.py

forms.py contains the localized address.

django-postal's People

Contributors

Stargazers

Watchers

django-postal's Issues

difficult to use it with other forms

I can't guess, how i can merge PostalAddressForm with MyProfileForm.

I think i have a usual task - add address field to my ProfileModel.

my profile form is
class ProfileForm(ModelForm):
class Meta(object):
model = Profile

so inheritance can't work.

I'd like to combine them:

{% csrf_token %} {{ address_form.as_p }} {{ profile_form.as_p }} {% monitor_country_change %} <script type="text/javascript"> $('form').monitor_country_change('#id_country'); </script>

    <input type="submit" value="Submit" />

but monitor_country_change will overwrite the entire form.

Missing templates in pypi

The version of this that is uploaded to pypi is missing the templates directory:

http://pypi.python.org/pypi/django-postal/0.6.1#downloads

The form described in the README will not work if it is pip installed. To work around this, you have to pip install from github:

pip install -e git+git://github.com/mthornhill/django-postal.git#egg=postal

I don't use buildout and I don't know how you package this up so I'm not sure how to fix this.

Django 1.7 compatibility issues

Hi. I am trying to use Postal with Django 1.7, but I receive the following error:

ImportError: cannot import name simplejson

The issue is actually a django-piston one, but I think it would be better to django-postal not to depend on django-piston.

Style of office and company name

There isn't jet a field that server addressing people properly. In Germany it's very custom to address each individual by her/his proper title. The german mail office even requires it.

I'm sure there are other countries that require such a field too.

You'll find more about that topic here: http://en.wikipedia.org/wiki/Style_(manner_of_address)

Additionally they companies name is required in most countries as is the addressees name. Both are currently missing a field, which I think is wrong. Yes it could mean redundancy, but having a first and last name in auth.user doesn't mean it has to be the address the user wishes to commit.

I see great potential in this library as dealing with with postal addresses is something everyone struggles who develops an app for the real world.

Recommend Projects

mthornhill / django-postal Goto Github PK