74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
## 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`.
|
|
3. 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. |