forked from mthornhill/django-postal
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
144 lines (102 loc) · 4.38 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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",
...
)
3. 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.
3. 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.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.