jquery.addressfield
The simple, configurable, dynamic postal address field plugin.
Features
This plugin helps you enhance user experience and data quality on your address (shipping/PO) forms by dynamically...
- Updating field labels (e.g. "ZIP code" vs. "Postcode"),
- Adding or removing fields that are irrelevant (e.g. countries that do not have a postal code system),
- Converting fields between select lists and text fields (e.g. US States vs. counties in the UK),
- Updating select options (e.g. US states vs. Canadian provinces)
- Updating field order (e.g. city, state, zip for US, different elsewhere),
- Validating fields on a field-by-field basis (e.g. between various postal code standards--depends on jQuery.validate),
- Providing placeholder text for configured fields (helpful when validating above).
Installation and usage
Include the script after your jQuery include (unless you're packaging scripts in some other magical way):
<script src="/path/to/jquery.js"></script>
<!-- Optionally, install jquery validation to handle field validation. -->
<script src="/path/to/jquery.validate.js"></script>
<script src="/path/to/jquery.addressfield.js"></script>
Also available on NPM, for browserified builds.
Install into node_modules
:
$ npm install jquery.addressfield
In your application module;
var $ = require('jquery');
require('jquery.addressfield');
$(...).addressfield(...);
Basic usage
Using jquery.addressfield is easy! Instantiate the plugin against a form or form wrapper with a few special configuration keys and the plugin takes care of the rest:
// If jquery.validate is in use, instantiate it here with your options:
$('#my-address-form').validate({/* ... */});
// Instantiate jquery.addressfield with your configs:
$('#my-address-form').addressfield({
json: '/path/to/addressfield.json',
fields: {
country: 'select#country-field',
administrativearea: '.state',
postalcode: '.zipcode'
},
});
Where json
is a path to addressfield.json (packaged with this plugin) or any
endpoint serving JSON in the same configuration schema. And where fields
is
an object mapping xNAL field names to jQuery selectors of form field elements
that correspond. At a bare minimum, the country
field is required.
Once instantiated, this plugin binds a change handler to the country element.
The change handler will trigger a mutation process on the form that handles all
of the features outlined above based on the configuration provided in the json
key.
Expected markup
Note that this plugin makes certain assumptions about the structure of your form markup. Please be sure to see the usage and configuration guide for complete details.
Detailed documentation
More detailed, topic-based documentation on usage and configuration options is available here below.
Contributing
Check out the Contributing guidelines