mholcer/jquery.addressfield

The simple, configurable, dynamic address field plugin.

jquery.addressfield

The simple, configurable, dynamic address field plugin.

Installation

Include the script after your jQuery include (unless you're packaging scripts in some other magical way):

<script src="/path/to/jquery.js"></script>
<script src="/path/to/jquery.addressfield.js"></script>

Usage

This plugin expects you have a form with a set of fields that represent an address (e.g. for shipping/billing or generating POs), but you want the fields to be displayed dynamically, based on some configuration (e.g. different labels or select options based on the selected country).

At a high level, all you're doing is calling jQuery.addressfield on a fieldset or other field/form wrapper, with a given configuration mapping and a list of fields you want to be dynamic.

$('#address-form').addressfield(config, dynamicFields);

Where config is an object that fits this format:

{
  "_comment" : "Note that field order will be respected.",
  "fieldname1" : {
    "_comment" : "All fields must include labels.",
    "label" : "Label for field1"
  }
  "fieldname2" : {
    "label" : "Label for field2"
    "_comment" : "Fields with options will be converted to selects.",
    "options" : {
      "AA" : "AA Value",
      "BB" : "BB Value"
    }
  }
}

And dynamicFields is just an array of fields you care about.

dynamicFields = ['fieldname1', 'fieldname2', 'fieldname3'];

And the input elements include their respective field names as classes, e.g.

<form id="address-form">
  <input class="fieldname1" />
  <select class="fieldname2 some-other-class">
    <option value="AA">AA Value</option>
  </select>
</form>

A more realistic usage example

Here's a sample configuration for Canada, which has a known, distinct list of provinces, and the United Kingdom, which doesn't have a list of administrative regions. Also note the labels for province/county and postal code/postcode.

{
  "CA" : {
    "administrativearea" : {
      "label" : "Province",
      "options" : {
        "AB" : "Alberta",
        "BC" : "British Columbia",
        "MB" : "Manitoba",
        "NB" : "New Brunswick",
        "NL" : "Newfoundland",
        "NT" : "Northwest Territories",
        "NS" : "Nova Scotia",
        "NU" : "Nunavut",
        "ON" : "Ontario",
        "PE" : "Prince Edward Island",
        "QC" : "Quebec",
        "SK" : "Saskatchewan",
        "YT" : "Yukon Territory"
      }
    },
    "postalcode" : {
      "label" : "Postal code"
    }
  },
  "GB" : {
    "administrativearea" : {
      "label" : "County"
    },
    "postalcode" : {
      "label" : "Postcode"
    }
  }
}

And here's some sample markup:

<form class="shipping">
  <div class="country-wrapper">
    <label for="address-country">Country</label>
    <select class="country" id="address-country" name="address[country]">
      <option value="CA">Canada</option>
      <option value="GB" selected>United Kingdom</option>
    </select>
  </div>
  <div class="thoroughfare-wrapper">
    <label for="address-thoroughfare">Address 1</label>
    <input class="thoroughfare" type="text" id="address-thoroughfare" name="address[thoroughfare]" value="">
  </div>
  <div class="premise-wrapper">
    <label for="address-premise">Address 2 </label>
    <input class="premise" type="text" id="address-premise" name="address[premise]" value="">
  </div>
  <div class="locality">
    <div class="localityname-wrapper">
      <label for="address-localityname">City</label>
      <input class="localityname" type="text" id="address-localityname" name="address[localityname]" value="">
    </div>
    <div class="administrativearea-wrapper">
      <label for="address-administrativearea">State</label>
      <input class="administrativearea" type="text" id="address-administrativearea" name="address[administrativearea]" value="">
    </div>
    <div class="postalcode-wrapper">
      <label for="address-postalcode">ZIP code</label>
      <input class="postalcode" type="text" id="address-postalcode" name="address[postalcode]" value="">
    </div>
  </div>
</form>

You might write some JavaScript like this to make it very simply dynamic:

// Load the JSON asynchronously.
$.getJSON('path/to/above.json', function(config) {
  // On country change...
  $('.country').bind('change', function () {
    // Trigger the addressfield plugin with the country's data.
    $('.shipping').addressfield(config[this.value], [
      'administrativearea',
      'postalcode'
    ]);
  });
});

Looking for a full, compatible dataset of field configurations by country? You might be interested in addressfield.json.

Contributing

Check out the Contributing guidelines