Plugin Overview

The jQuery CitySelect plugin provides an efficient solution for creating cascading dropdown menus to province, city, and district selections. This plugin reads JSON data to create dynamic联动 (cascading) effects with out requiring page refreshes, making it ideal for registration forms, e-commerce platforms, and location-based applications.

Core Features

The plugin enables developers to implement three-level cascading selection functionality using jQuery and JSON data. It handles the complex logic of dependent dropdowns automatically, providing users with relevant options based on their previous selections.

Configuration Options

Parameter	Default Value	Type	Description
dataUrl	js/city.min.js	string	Path to JSON data file containing location hierarchy
defaultProvince	null	string	Pre-selected province value
defaultCity	null	string	Pre-selected city value
defaultDistrict	null	string	Pre-selected district value
noDataMessage	null	string	Text displayed when no options are available
isRequired	true	boolean	Determines if selection is mandatory

Implemantation Example

HTML Structure

<div id="locationContainer">
    <select class="provinceSelector"></select>
    <select class="citySelector" disabled="disabled"></select>
    <select class="districtSelector" disabled="disabled"></select>
</div>

JavaScript Implementation

$(document).ready(function() {
    $("#locationContainer").citySelect({
        noDataMessage: "unavailable",
        isRequired: false
    });
});

Required Dependencies

<script src="js/jquery.min.js"></script>
<script src="js/jquery.cityselect.js"></script>
<!-- Ensure city.min.js is accessible from the same directory -->

For direct CDN access:

<script src="https://example.com/js/jquery.min.js"></script>
<script src="https://example.com/js/jquery.cityselect.js"></script>
<script>
$(document).ready(function() {
    $("#locationContainer").citySelect({
        noDataMessage: "unavailable",
        isRequired: false
    });
});
</script>

Data Structure Requirements

The plugin expects a properly formatted JSON file containing the hierarchical relationship between provinces, cities, and districts. The default implementation looks for city.min.js in the same directory as the plugin file.