# City Picker

> A simple jQuery plugin for picking provinces, cities and districts of China.

- [Demo](http://tshi0912.github.io/city-picker)

##Release History

###v1.1.0
Add function to get the code：

```javascript
// type: null or undefined(get the full code path, separated with /), province, city, district
$('.city-picker').data('citypicker').getCode(type);
```

## Main

```
dist/
├── city-picker.js          ( 7 KB)
├── city-picker.min.js      ( 4 KB)
├── city-picker.data.js     (98 KB)
└── city-picker.data.min.js (68 KB)
```



## Getting started


### Quick start

Four quick start options are available:

- [Download the latest release](https://github.com/tshi0912/city-picker/archive/master.zip).
- Clone the repository: `git clone https://github.com/tshi0912/city-picker.git`.
- Install with [NPM](http://npmjs.org): `npm install city-picker`.
- Install with [Bower](http://bower.io): `bower install city-picker`.


### Installation

Include files:

```html
<script src="/path/to/jquery.js"></script><!-- jQuery is required -->
<script src="/path/to/city-picker.data.js"></script>
<script src="/path/to/city-picker.js"></script>
```


Create HTML elements:

```html
<div style="position:relative;"><!-- container -->
  <input readonly type="text">
</div>
```



### Usage

#### Initialize with `data-toggle="city-picker"` attribute


Basic

```html
<div style="position:relative;">
  <input readonly type="text" data-toggle="city-picker">
</div>
```


Custom placeholders

```html
<div style="position:relative;">
  <input readonly type="text" data-toggle="city-picker" placeholder="customized placeholder...">
</div>
```

Responsive width

```html
<div style="position:relative;">
  <input readonly type="text" data-toggle="city-picker" data-responsive="true" style="width:50%;">
</div>
```


Custom province/city/district

```html
<div style="position:relative;">
  <input readonly type="text" data-toggle="city-picker" value="江苏省/常州市/溧阳市">
</div>
```


#### Initialize with `$.fn.city-picker` method

Basic

```js
$('#target').citypicker();
```

Custom districts

```js
$('#target').citypicker({
  province: '江苏省',
  city: '常州市',
  district: '溧阳市'
});
```



## Options

- Change the default options with `$().citypicker(options)`.
- Change the global default options with `$.fn.citypicker.setDefaults(options)`.


### simple

- Type: `Boolean`
- Default: `false`

Make the address level more simple, e.g. `内蒙古` instead of `内蒙古自治区`.

### level

- Type: `String`
- Default: `district`

Only province, province + city, or province + city + district.

### responsive

- Type: `Boolean`
- Default: `false`

make the drop down and mask span responsive on width.

### placeholder

- Type: `Boolean`
- Default: `请输入省/市/区`

Show placeholder (with an `<option>` element).


### province

- Type: `String`
- Default: `null`

Defines the initial value of province. If it is a existing province in `city-picker.data.js`, it will be selected. If not, it will be used as a placeholder.


### city

- Type: `String`
- Default: `null`

Defines the initial value of city. If it is a existing city under the selected province, it will be selected. If not, it will be used as a placeholder.


### district

- Type: `String`
- Default: `null`

Defines the initial value of district. If it is a existing district under the selected city, it will be selected. If not, it will be used as a placeholder.



## Methods

### reset()

Reset the selects to the initial states (Undo changed).

**Examples:**

```js
$().citypicker('reset');
```

### destroy()

Destroy the city-picker instance, but keep the selected districts.

If you want to remove the selected districts, you can call `reset` method first and then call this method.



## No conflict

If you have to use other plugin with the same namespace, just call the `$.fn.city-picker.noConflict` method to revert to it.

```html
<script src="other-plugin.js"></script>
<script src="city-picker.js"></script>
<script>
  $.fn.citypicker.noConflict();
  // Code that uses other plugin's "$().citypicker" can follow here.
</script>
```



## Browser support

- Chrome (latest 2)
- Firefox (latest 2)
- Internet Explorer 8+
- Opera (latest 2)
- Safari (latest 2)

As a jQuery plugin, you also need to see the [jQuery Browser Support](http://jquery.com/browser-support/).



## License

[MIT](http://opensource.org/licenses/MIT) © [Tao Shi](http://shitao.me)