Rails plugin to check (hungarian) zipcodes against cities and vice versa
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
generators/zipcodes
lib
tasks
test
MIT-LICENSE
README.md
Rakefile
init.rb
install.rb
uninstall.rb
zipcodematch.gemspec

README.md

Mire használható ez a plugin?

A ZipcodeMatch egy, a magyarországi irányítószámok és települések egyezőségét ellenőrző plugin. Valójában ennél többre is képes, mivel adatbázisa tartalmazza minden magyarországi település és a hozzá tartozó irányítószámot vagy irányítószámokat így kiválóan felhasználható űrlapok adatbevitelének az ellenőrzésére vagy segítésére.

A kiegészítő egy Rails szakdolgozat melléktermékeként jött létre.

Telepítés

Plugin telepítése

Egyszerűen parancssorból kiadva az alkalmazás könyvtárában:

script/plugin install git://github.com/csiszarattila/zipcodematch.git

Adatok importálása

Az egyszerűbb használat érdekében a kiterjesztés az adatokat adatbázisban tárolja, az adatbázist pedig egy Zipcode nevű ActiveRecord típusú modellen keresztül éri el. A modell használatához így egy migrációval előbb létre kell hozni a szükséges zipcodes elnevezésű táblát, ezt a plugin generátorával könnyen megteheted:

script/generate zipcodes table

Majd töltsük fel a létrehozott sémát:

rake db:migrate

Majd az adatok beimportálásához az adatbázis táblába futtasd:

rake db:zipcodes:load

(Légy türelemmel, ez a művelet eltarthat egy ideig.)

Példák

Az ellenőrzésre a ZipcodeMatch.match?(település,irányítószám) használhatjuk, amely eldönti, hogy a megadott település és irányítószám összetartozik-e (figyelembe veszi, hogy egyes városok több irányítószámmal is rendelkezhetnek).

Érdemes alacsony szintű ellenőrzésként alkalmazni egy modellben:

  def validate
    unless ZipcodeMatch::match?(self.city, self.zipcode)
        errors.add_to_base ...
    end
  end

vagy használd a magasabb szintű validációk egyikét:

  class Address < ActiveRecord::Base
    ...
    validates_zipcode_and_city_match
    ...
  end

API

A ZipcodeMatch modul metódusai

ZipcodeMatch osztálymetódus Mire használható?
match?(település,irányítószám) Annak eldöntése, hogy a település és irányítószám egyezik-e
city_exist?(település) Annak eldöntésére, hogy a megadott település létezik-e
zipcode_exist?(irányítószám) Mint az előző csak irányítószám esetében
city_with_zipcode(irányítószám) Visszaadja az adott irányítószámhoz tartozó települést
zipcodes_for_city(település) Megkeresi az adott településhez tartozó irányítószámo(ka)t

Rake taszkok

A db és zipcode névtéren belül a load (db:zipcodes:load) betölti, a delete (db:zipcodes:delete) pedig kitörli az adatokat az adatbázis táblából.

ActiveRecordos magasabb szintű validációk

Az ellenőrzések egyszerűsítéshez az ActiveRecord modellek esetében a plugin definiál néhány magasabb szintű ellenőrzést is.

A validates_zipcode_and_city_match két mező viszonylatában ellenőrzi a település és hozzá tartozó irányítószám egyezését:

  class Address < ActiveRecord::Base
    ...
    validates_zipcode_and_city_match
    ...
  end

A hibaüzeneteket mindig a modellhez és nem az attribútumokhoz társítja! Alapértelmezettként a :city és :zipcode attributumokat használja fel. Ez megváltoztatható az opciókkal, többek között itt adhatjuk azt is meg, hogy mikor alkalmazza az ellenőrzést - alapértelmezettként a mentés során futtatja a validációt.

validates_zipcode_and_city_match :zipcode_attr_is=>:ir, :city_attr_is=>:varos, :on => :create

A validates_existence_on segítségével vagy a modellhez tartozó települést vagy az irányítószámot vizsgálhatjuk meg, hogy érvényes-e. Használatához jellezzük a metódusnak első attribútumként, hogy melyiket szeretnénk vizsgálni:

Települések esetében a :city szimbólummal

validates_existence_on :city, :message => "Ilyen nevű település nem létezik!"

Irányítószámok esetében a :zipcode szimbólummal

validates_existence_on :zipcode, :message => "Ilyen irányítószám nem létezik!"

Az alapértelmezett attribútum ezúttal is a city vagy a zipcode elnevezésű lesz, ezt felülbírálni az :attr_is opcióval lehetséges:

validates_existence_on :city, :attr_is => :varos

Milyen adatokkal dolgozik?

A Magyar Posta weboldaláról letölhető az összes Magyarországi irányítószám és a hozzá tartozó cím XLS formátumban. Az adatok adatbázisban való tárolásához ezt előbb CSV formátumba konvertáltam, majd az adatbázisba töltéskor csak az irányítószám és a hozzá tartozó település került mentésre (az adatforrás több, számunkra szükségtelen adatot is tartalmaz).

Ez egyben azt is jelenti, hogy egyes településekhez több irányítószám is tartozhat. A budapesti irányítószámok esetében pedig minden irányítószám mellett Budapest szerepel mint város, a kerületeket pedig nem veszi figyelembe. Ha ezen változtatni szeretnél a ZipcodeMatch.import_from_csv metódust tekintsd meg, ez végzi el az irányítószámok adatbázisba töltését - a db:zipcodes:load rake taszk pedig ezt hívja meg.

Hogyan futtassuk a modellek unit tesztjeit

Problémát jelenthet, hogy a modellek egység-tesztjeinél bizonyos esetekben lefuthatnak a validációk megbolondítva ezzel a tesztek kimeneteit.

A gondot az okozza, hogy a tesztek futtatásakor a Rails kitöröl minden táblát és az fixtureszekkel(alapadatokkal) tölti fel azokat a teszt adatbázisban, így az alapadatokon kívül nem lehet saját, előre definiált adatokkal feltölteni. Viszont így a ZipcodeMatch modul sem találja az adatbázisban a szükséges adatokat.

Ennek feloldására próbálkozhatunk az irányítószámok fixtures-ként való megadásával - elfogadja a CSV formátumot is - ez azonban jelentősen lelassíthatja a tesztek futtatását, mivel minden teszt futtatása előtt a tesztkörnyezet újratölti az alapadatokat.

Ezért inkább érdemes létrehozni egy, a ZipcodeMatch modult imitáló úgynevezett mock osztályt, ami tulajdonképpen csak felülírja a modul eredeti metódusait, hogy mindig igaz értékkel térjenek vissza.

Egy ilyen mock objektumot megtalálsz a plugin mellett, mindössze includold be annak modellnek a unit test fájljában, amelyik használja a plugin metódusait:

require 'zipcodematch/lib/mocks/zipcode_match.rb'

class AddressTest < ActiveSupport::TestCase
...
end

Ezzel a teszteket függetleníthetjük a ZipcodeMatch modultól, amelynek működése külön tesztekkel van biztosítva - lásd plugin/ok/konyvtara/zipcodematch/test/ könyvtárt.

Ötletek, kérés, sóhaj, óhaj...

email: csiszar pont ati kukac gmail pont com

www: csiszarattila.com

Copyright (c) 2008 Csiszár Attila, released under the MIT license