Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Rails plugin to check (hungarian) zipcodes against cities and vice versa
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

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

Something went wrong with that request. Please try again.