china_region_fu 0.0.6 → 0.1.0

data/README.md

@@ -1,59 +1,76 @@
+# [English Readme](https://github.com/Xuhao/china_region_fu/blob/master/README.en.md)
+
 # ChinaRegionFu
 
-[![Gem Version](https://badge.fury.io/rb/china_region_fu.png)](http://badge.fury.io/rb/china_region_fu)
-[![Build Status](https://travis-ci.org/Xuhao/china_region_fu.png?branch=master)](https://travis-ci.org/Xuhao/china_region_fu)
+[![Build Status](https://travis-ci.org/Xuhao/china_region_fu.svg?branch=master)](https://travis-ci.org/Xuhao/china_region_fu)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/85643743367e47d6853b94431f4f503f)](https://www.codacy.com/app/xuhao/china_region_fu?utm_source=github.com&utm_medium=referral&utm_content=Xuhao/china_region_fu&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/85643743367e47d6853b94431f4f503f)](https://www.codacy.com/app/xuhao/china_region_fu?utm_source=github.com&utm_medium=referral&utm_content=Xuhao/china_region_fu&utm_campaign=Badge_Coverage)
+[![Gem Version](https://badge.fury.io/rb/china_region_fu.svg)](https://badge.fury.io/rb/china_region_fu)
+
+ChinaRegionFu 是一个提供中国行政区域信息的rails engine(只适用rails)。使用ChinaRegionFu后，你将拥有全面且准确的中国区域数据，而且你还可以使用其提供的表单helper，轻松将具有联动效果的区域选择器放入你的表单中。
+
+![Screenshot](https://cloud.githubusercontent.com/assets/324973/19191241/2c5726a8-8cd4-11e6-960d-6edd1fa69427.gif "Screenshot")
+
+## 运行环境
 
-ChinaRegionFu provide the region data of china.You will got complete China region data after use this gem.
+  * CRuby 2.2 及以上
+  * Rails 4.0 及以上
+  * jQuery 1.8 及以上, 若不需要联动效果可忽略
 
-## Installation
+## 安装
 
-Put 'gem china_region_fu' to your Gemfile:
+将 'gem china_region_fu' 放入项目的 Gemfile中:
 
     gem 'china_region_fu'
 
-Run bundler command to install the gem:
+运行 bundler 命令来安装:
 
     bundle install
 
-After you install the gem, you need run below tasks one by one:
+bundle安装完成后，你需要依次运行以下命令:
 
-  1. Copy migration file to your app.
+  1. 复制数据迁移文件到项目中:
 
-      <pre>rake china_region_fu_engine:install:migrations</pre>
+      <pre>rake china_region_fu:install:migrations</pre>
 
-  2. Run db:migrate to create region tables.
+  2. 运行 db:migrate 来创建数据库表:
 
       <pre>rake db:migrate</pre>
 
-  3. Download the latest regions.yml form [github](https://raw.github.com/Xuhao/china_region_data/master/regions.yml).
+  3. 从[china_region_data](https://raw.github.com/Xuhao/china_region_data)下载最新的<b>[regions.yml](https://raw.github.com/Xuhao/china_region_data/master/regions.yml)</b>:
 
-      <pre>rake region:download</pre>
+      <pre>rake china_region_fu:download</pre>
 
-  4. Import regions to database.
+  4. 将区域信息导入到数据库:
 
-      <pre>rake region:import</pre>
+      <pre>rake china_region_fu:import</pre>
 
-You also can use below task to do the same things as four tasks above:
+以上每条命令运行完成后，你可以根据需要对生成的文件做一些修改，然后再运行下一条。如果你不需要做自定义修改，也可以通过下面这条命令实现和上面4个命令同样的动作:
 
-    rake region:install
+    rake china_region_fu:setup
 
-Region data is from [ChinaRegionData](https://github.com/Xuhao/china_region_data), check it out to see what kind of data you have now.
+区域数据来自[china_region_data](https://github.com/Xuhao/china_region_data), 你可以通过查看这个git库来了解都有哪些区域数据。
 
-If you want to customize the region modules you can run the generator:
+ChinaRegionFu通过`ActiveRecord`将各种区域映射成类:
+ * `Province`: 省、自治区、直辖市、特别行政区
+ * `City`: 地区、盟、自治州、地级市
+ * `District`: 县、自治县、旗、自治旗、县级市、市辖区、林区、特区
+
+如果你想自定义这些类，可以通过以下命令将其复制到你的项目中:
 
     rails g china_region_fu:models
 
-   This will create:
+   将会创建:
 
     create  app/models/province.rb
     create  app/models/city.rb
     create  app/models/district.rb
 
-   So you can do what you want to do in this files.
+   你可以在以上这些类文件中做任何事。
 
-## Usage
+## 使用说明
 
-#### Model
+### Model
 
 ```ruby
 a = Province.last
@@ -80,83 +97,98 @@ d.city.name              # => "阿勒泰地区"
 d.province.name          # => "新疆维吾尔自治区"
 ```
 
-#### View
+### View
 
-##### Form helpers
+#### Form helpers
 
 ```erb
-<%= form_for(@post) do |f| %>
+<%= form_for(@address) do |f| %>
   <div class="field">
     <%= f.label :province, '选择地区：' %><br />
 
     # FormBuilder
     <%= f.region_select :city %>
-    <%= f.region_select [:province, :city, :district], province_prompt: 'Do', city_prompt: 'it', district_prompt: 'like this' %>
-    <%= f.region_select [:province, :city], include_blank: true %>
-    <%= f.region_select [:city, :district] %>
-    <%= f.region_select [:province, :district] %>
+    <%= f.region_select [:province_id, :city_id, :district_id], province_prompt: 'Do', city_prompt: 'it', district_prompt: 'like this' %>
+    <%= f.region_select [:province_id, :city_id], include_blank: true %>
+    <%= f.region_select [:city_id, :district_id] %>
 
     # FormHelper
-    <%= region_select :post, :province %>
-    <%= region_select :post, [:province, :city, :district] %>
+    <%= region_select :address, :province_id %>
+    <%= region_select :address, [:province_id, :city_id, :district_id] %>
     ...
 
     # FormTagHelper
-    <%= region_select_tag :province, class: 'my', include_blank: true %>
-    <%= region_select_tag [:province, :city, :district], province_prompt: 'Do', city_prompt: 'it', district_prompt: 'like this', class: 'my' %>
+    <%= region_select_tag :province_id, class: 'province-select', include_blank: true %>
+    <%= region_select_tag [:province_id, :city_id, :district_id], province_prompt: 'Do', city_prompt: 'it', district_prompt: 'like this', class: 'region-select' %>
     ...
   </div>
 <% end %>
 ```
 
-##### SimpleForm
+#### SimpleForm
 
 ```erb
-<%= simple_form_for(@post) do |f| %>
-  <%= f.input :province, as: :region, collection: Province.select('id, name'), sub_region: :city %>
-  <%= f.input :city, as: :region, sub_region: :district %>
-  <%= f.input :district, as: :region %>
-  <%= js_for_region_ajax %>
+<%= simple_form_for(@address) do |f| %>
+  <%= f.input :province_id, as: :region, collection: Province.select('id, name'), sub_region: :city_id %>
+  <%= f.input :city_id, as: :region, collection: City.where(province_id: f.object.province_id).select('id, name'), sub_region: :district_id %>
+  <%= f.input :district_id, as: :region, collection: District.where(city_id: f.object.city_id).select('id, name') %>
+  <%= china_region_fu_js %>
 <% end %>
 ```
 
-##### Formtastic
+#### Formtastic
 
 ```erb
-<%= semantic_form_for(@post) do |f| %>
-  <%= f.input :province, as: :region, collection: Province.select('id, name'), sub_region: :city %>
-  <%= f.input :city, as: :region, sub_region: :district %>
-  <%= f.input :district, as: :region %>
-  <%= js_for_region_ajax %>
+<%= semantic_form_for(@address) do |f| %>
+  <%= f.input :province_id, as: :region, collection: Province.select('id, name'), sub_region: :city_id) %>
+  <%= f.input :city_id, as: :region, collection: City.where(province_id: f.object.province_id).select('id, name'), sub_region: :district_id %>
+  <%= f.input :district_id, as: :region, collection: District.where(city_id: f.object.city_id).select('id, name') %>
+  <%= china_region_fu_js %>
 <% end %>
 ```
 
-##### Fetch sub regions by Ajax
+#### 通过AJAX实现联动效果
 
-Once select one province, we want fetch cities of the selected province and fill the city select box automatically. If you use `:region_select_tag` and FormBuilder/FormHelper method aka `:region_select`, you need do nothing for this. If you use simple_form or normal form helper like `:select_tag` or `:select`, to implement this, what you need to do is add below helper in your form:
+当选中某个省份时，我们希望城市下拉列表自动显示这个省下属的城市；当选择某个城市时，我们希望区域列表显示该城市下属区域。你需要在你的页面中添加以下helper来实现联动效果:
 
 ```erb
-<%= js_for_region_ajax %>
+<%= china_region_fu_js %>
+# or
+<%= content_for :china_region_fu_js %>
 ```
 
-it will render:
+将会渲染:
 
 ```html
 <script type="text/javascript">
   //<![CDATA[
+    window.chinaRegionFu = window.chinaRegionFu || {};
     $(function(){
-      $('body').on('change', '.region_select', function(event) {
-        var self, $targetDom;
-        self = $(event.currentTarget);
-        $targetDom = $('#' + self.data('region-target'));
-        if ($targetDom.size() > 0) {
-          $.getJSON('/china_region_fu/fetch_options', {klass: self.data('region-target-kalss'), parent_klass: self.data('region-klass'), parent_id: self.val()}, function(data) {
-            var options = [];
-            $('option[value!=""]', $targetDom).remove();
-            $.each(data, function(index, value) {
-              options.push("<option value='" + value.id + "'>" + value.name + "</option>");
-            });
-            $targetDom.append(options.join(''));
+      $('body').off('change', '.china-region-select').on('change', '.china-region-select', function(event) {
+        var $self, $targetDom;
+        $self = $(event.currentTarget);
+        $subRegionDom = $('[data-region-name="' + $self.data('sub-region') + '"]');
+        if ($subRegionDom.size() > 0) {
+          $.getJSON('/china_region_fu/fetch_options', {
+              columns: window.chinaRegionFu.fetchColumns || 'id,name',
+              sub_name: $self.data('sub-region'),
+              parent_name: $self.data('region-name'),
+              parent_id: $self.val()
+            }, function(json) {
+              if (window.chinaRegionFu.ajaxDone) {
+                window.chinaRegionFu.ajaxDone(json);
+              } else {
+                var options = [];
+                $self.parent().nextAll().find('.china-region-select > option[value!=""]').remove()
+                $.each(json.data, function(_, value) {
+                  options.push("<option value='" + value.id + "'>" + value.name + "</option>");
+                });
+                $subRegionDom.append(options.join(''));
+              }
+          }).fail(function(xhr, textStatus, error) {
+            window.chinaRegionFu.ajaxFail && window.chinaRegionFu.ajaxFail(xhr, textStatus, error);
+          }).always(function(event, xhr, settings) {
+            window.chinaRegionFu.ajaxAlways && window.chinaRegionFu.ajaxAlways(event, xhr, settings);
           });
         }
       });
@@ -164,19 +196,22 @@ it will render:
   //]]>
 </script>
 ```
+自定义:
+
+  * `window.chinaRegionFu.fetchColumns`: 设定返回栏位数据，默认: `id,name`
+  * `window.chinaRegionFu.ajaxDone(json)`: 自定义ajax `success`事件，默认：重新填充下级选项
+  * `window.chinaRegionFu.ajaxFail(xhr, textStatus, error)`: 自定义ajax `fail`事件
+  * `window.chinaRegionFu.ajaxAlways(event, xhr, settings)`: 自定义ajax `always`事件
+
+## 在线的例子
 
-## Online example
 [医院之家](http://www.yihub.com/ "医院").
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome on GitHub at https://github.com/xuhao/china_region_fu. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 ## License
 
-ChinaRegionFu is released under the MIT license.
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 

data/Rakefile

@@ -3,4 +3,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task :default => :spec

data/app/controllers/china_region_fu/fetch_options_controller.rb

@@ -1,37 +1,73 @@
-module ChinaRegionFu
-  class FetchOptionsController < ::ActionController::Metal
-
-    def index
-      if params_valid? and klass and parent_klass and (parent_object = parent_klass.find(params[:parent_id]))
-        regions = parent_object.__send__(klass.model_name.plural).select("#{klass.table_name}.id, #{klass.table_name}.name").order("#{klass.table_name}.name ASC")
-        regions.reorder("#{klass.table_name}.level ASC") if has_level_column?
-        self.response_body = regions.to_json
-      else
-        self.response_body = [].to_json
-      end
-    end
+# GET: /china_region_fu/fetch_options
+# Pass parent's id(by `province_id`, `city_id`) to fetch children(cities, districts),
+# If no parent id passed, return all provinces.
+#
+# ==== Paramters
+#
+# * <tt>:columns</tt> - Set the columns to return for each one.
+# * <tt>:parent_name</tt> - Name for parent region
+# * <tt>:parent_id</tt> - ID for parent region
+# * <tt>:sub_name</tt> - Name for sub region
+require 'active_support/core_ext/object/blank'
 
-    private
+class ChinaRegionFu::FetchOptionsController < ::ActionController::Metal
+  def index
+    validate_params!
+    regions = sub_klass.order(name: :asc)
+    regions = regions.where(where_value) if where_value
+    regions = regions.reorder(level: :asc) if has_level_column?
+    regions = regions.select(region_fields)
+    self.response_body = { data: regions.as_json(only: region_fields, methods: region_methods) }.to_json
+  rescue => e
+    self.response_body = { error: e.message }.to_json
+    self.status = 500
+  end
 
-      def has_level_column?
-        klass.column_names.to_a.include?('level')
-      end
+  private
 
-      def klass
-        params[:klass].sub(/_id\Z/, '').classify.safe_constantize
-      end
+    def has_level_column?
+      sub_klass.column_names.include?('level')
+    end
 
-      def parent_klass
-        parent_klass_name.classify.safe_constantize
-      end
+    # Available fields in DB
+    def region_fields
+      sub_klass.column_names & params_columns
+    end
 
-      def parent_klass_name
-        params[:parent_klass].sub(/_id\Z/, '')
+    # Methods can be responded to
+    def region_methods
+      params_columns.select { |column| sub_klass.instance_methods(false).include?(column.to_sym) }
+    end
+
+    def params_columns
+      @params_columns ||= params[:columns].to_s.split(',').presence || %w(id name)
+    end
+
+    def sub_klass
+      @sub_klass ||= begin
+        case params[:sub_name]
+        when 'city', 'city_id' then City
+        when 'district', 'district_id' then District
+        end
       end
+    end
 
-      def params_valid?
-        params[:klass].present? and parent_klass_name=~ /\Aprovince\Z|\Acity\Z/i and params[:parent_id].present?
+    def where_value
+      @where_value ||= begin
+        case params[:parent_name]
+        when 'province', 'province_id' then { province_id: params[:parent_id] }
+        when 'city', 'city_id'         then { city_id: params[:parent_id] }
+        else                                nil
+        end
       end
+    end
 
-  end
-end
+    def validate_params!
+      (params[:parent_name].present? &&
+        params[:parent_id].present? &&
+        params[:sub_name].present? &&
+        %w(city city_id district district_id).include?(params[:sub_name]) &&
+        %w(province province_id city city_id).include?(params[:parent_name])) ||
+        raise('Invalid paramters!')
+    end
+end

data/app/models/city.rb

@@ -1,18 +1,8 @@
-# coding: utf-8
 class City < ActiveRecord::Base
-  if Rails.version < '4.0'
-    attr_accessible :name, :province_id, :level, :zip_code, :pinyin, :pinyin_abbr
-  end
-
   belongs_to :province
   has_many :districts, dependent: :destroy
 
   def short_name
-    @short_name ||= name.gsub(/市|自治州|地区|特别行政区/,'')
+    @short_name ||= name.gsub(/市|(回族|哈萨克|柯尔克孜|彝族|蒙古(族)?|白族|朝鲜族|傣族|景颇族|傈僳族|土家族|壮族|苗族|藏族|哈尼族|羌族|侗族|布依)?自治州|地区|特别行政区$/,'')
   end
-
-  def brothers
-    @brothers ||= City.where("province_id = #{province_id}")
-  end
-
 end

data/app/models/district.rb

@@ -1,18 +1,8 @@
-# coding: utf-8
 class District < ActiveRecord::Base
-  if Rails.version < '4.0'
-    attr_accessible :name, :city_id, :pinyin, :pinyin_abbr
-  end
-
   belongs_to :city
   has_one :province, through: :city
 
   def short_name
-    @short_name ||= name.gsub(/区|县|市|自治县/,'')
+    @short_name ||= name.sub(/区|县|市$/,'')
   end
-
-  def brothers
-    @brothers ||= District.where("city_id = #{city_id}")
-  end
-
 end

data/app/models/province.rb

@@ -1,8 +1,8 @@
 class Province < ActiveRecord::Base
-  if Rails.version < '4.0'
-    attr_accessible :name, :pinyin, :pinyin_abbr
-  end
-
   has_many :cities, dependent: :destroy
   has_many :districts, through: :cities
+
+  def short_name
+    @short_name ||= name.sub(/省|市|(回族|壮族|维吾尔)?自治区|特别行政区&/, '')
+  end
 end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'china_region_fu'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/rspec

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")