country-region-selector/README.md

country-region-dropdowns

A common thing you often see in forms is a country dropdown which populates a second region field when a country is selected. It's super easy to do this, but requires a lot of leg work tracking down the data and rigging it all up in your form. So this script does exactly that - and gives you a few options to cover the most likely scenarios you may need to handle.

The script comes in two versions:

• standalone script (no dependencies, just plain JS) - 10KB
• a jQuery-dependent version (slightly smaller) - 8KB

Features

• Lets you define an optional "please select" field for each (with whatever language you want).
• Lets you specify a default value for each field.
• Lets you customize the appearance and value of the country field ("Canada" or "CA").
• Lets you have as many country-region fields as you need in your page.
• The standalone version has no dependencies on other any libs (jQuery etc).

Example

Here's an example page that shows a few different ways it can be used.

• Example page

How to Use

It's very easy.

1. Include the `country-region-selector.min.js' file in your webpage.
2. Add two <select> fields in the appropriate locations in your form.
3. Give the country field a class of crs-country.
4. Give the region field a class of crs-country.
5. Now we need to map each country to the region field so the script knows what to update. Add an attribute to the country dropdown: data="crsX" where X is any number (e.g. start with 1). Give the region dropdown a class of "crxX" where X is the same number you just picked.

Default "Please select" Values

If you want to add default "Please select" options to either the country or region fields, just go ahead and add it directly in the markup. The script will append the country and region <option> fields - not overwrite them.

Styling

If you didn't add a default value for the region field, you may notice that it looks pretty pretty crumby. So to style it, just add the following CSS: .yourField { width: 100px; }

Adding default values for each field

If your form is used for people returning to it (e.g. "Edit Contact Info" or whatever), you'll need the country and region fields to be prefilled with the appropriate value on page load. To do that, just add a data-default="" attribute to each element containing the country / region value last saved.

Notes for Developers

If you want to edit the source code, go right ahead (pull requests welcome, of course!). The unminified source code is found in the /source folder. To re-generate the minified version, just run the Grunt task. In case you're not familiar with Grunt, here's how you'd do that.

1. Install node on your computer.
2. Clone this repository to your local computer.
3. In the command line, navigate to
4. Type npm install to download all necessary require
5. Type npm install -g grunt-cli to install the Grunt command line tool to run properly.
6. Type grunt generate.

License

MIT.