= JpAddress: A Rails plugin for Japan Zipcode API.

== JpAddressとは
日本郵便の「郵便番号データ」を Rails 4.0 で使用するためのプラグインです。
以下の機能を提供します。

* 郵便局提供の郵便番号データをダウンロードしてＤＢにロードするメソッド。
* 郵便番号をキーに住所情報を返却するＡＰＩ（コントローラ）。

要するに、「郵便番号検索 ruby gem」でググった人向けの gem です。
お使いのRailsアプリケーションにマウントして使えますので、後必要なのは戻ってくるJSONを加工する手順だけです。

== インストール
  % gem install jp_address

GemFileに追記
  gem 'jp_address'

テーブルの作成
  % rake jp_address:install:migrations
  % rake db:migrate

== マスターデータのＤＢへのロード
開発環境
  % rails runner -e development 'JpAddress::Zipcode.load_master_data'
本番環境
  % rails runner -e production 'JpAddress::Zipcode.load_master_data'

環境にもよりますが、１～３分ぐらいかかると思います。

※ APP_ROOT/tmp/ を作業ディレクトリに使用しています。
※ 最初にテーブルをトランケートしますので、毎回「全件insert」になります。

== ＡＰＩのマウント
マウントしたいRailsアプリの config/routes.rb に追記。
  mount JpAddress::Engine, at: "/jp_address"

== ＡＰＩの利用
/jp_address にマウントした場合、下記URLへGETリクエストをすることで、JSONを取得できます。
後はこれを好きに加工してテキストボックスなどにセットして使ってください。

  http://localhost:3000/jp_address/zipcodes/search?zip=5330033
  
  {"id":84280,"zip":"5330033","prefecture":"大阪府","city":"大阪市東淀川区","town":"東中島"}

== サンプルとなる coffee script
フォームには
* zipcode（テキストボックス）
* prefecture_id（セレクトボックス。いわゆる都道府県プルダウン）
* address（テキストボックス）
の３要素があり、zipcodeに入れられた値を元にＡＰＩを叩き、prefecture_id と address に
値をセットするサンプルです。

prefecture_id の選択は、都道府県名で行っています。
なので、お使いの都道府県マスターのＩＤ値に影響を受けることなく選択できるはずです。

  class AddressSearch
    constructor: (zip_elem_id, prefecture_elem_id, address_elem_id) ->
      @$zip               = $(zip_elem_id)
      @$prefecture        = $(prefecture_elem_id)
      @$address           = $(address_elem_id)
      @prefecture_elem_id = prefecture_elem_id

    _remove_hyphen: ->
      @$zip.val(@$zip.val().replace(/-/, ''))

    _clear_current_value: ->
      $(@prefecture_elem_id + ' >option:eq(0)').prop 'selected', true
      @$address.val ''

    _set_prefecture: (json) ->
      $(@prefecture_elem_id + ' > option').each ->
        if $(@).text() == json['prefecture']
          $(@).prop 'selected', true

    _set_address: (json) ->
      @$address.val json['city'] + json['town']

    _call_api: ->
      $.getJSON '/jp_address/zipcodes/search', {zip: @$zip.val()}, (json) =>
        if json['id'] == null
          @._clear_current_value()
        else
          @._set_prefecture json
          @._set_address json

    execute: ->
      @._remove_hyphen()
      if @$zip.val().length == 7
        @._call_api()

  $ ->
    address_search = new AddressSearch('#zipcode', '#prefecture_id', '#address')
    $('#zipcode').keyup ->
      address_search.execute()

== 作者

Copyright 2016 (c) Tadashi K, under MIT License.

Tadashi K <densya203@skult.jp>