Belongs to city

Rails gem that eases the relation between your existing models and a City → State → Country type of database.

It is thought primarily to be used in a city autocomplete feature and includes the functionality to get started with the jquery autocomplete plugin.

Install

gem install belongs_to_city

Generate the city Structure

First of all you need to generate the structure that includes the City, State and Country in your application.

You can do this with the following command

script/generate belongs_to_city

This will generate 3 basic things. A migration file that creates the previously mentioned tables, the 3 models and the cities controller (Since you will be accesing this for the autocomplete functionality). Also it will generate the routes to access this last controller.

Also You can optionally give the arguments of the things you need for your application. with the following options

* tables – Generates the migration * models – Generates the models * controller – Generates the controller and the resource route

So the previous line of code is equivalent to:

script/generate belongs_to_city tables models controller

OPTIONS

Optionally you can provide the following options that will further help you to generate the database and start on the autocomplete feature

—include-seed will create a rake task to seed your City based database using .csv files. For this to work you need to have your csv files stored in db/csv folder and the files should have the following format.

countries.csv

name

Mexico

USA

states.csv

country_id	name	abbr	short	short2
1	Nuevo Leon	N.L.	NL	NLE
1	Jalisco	Jal.	JA	JAL
2	Texal	TX
2	Florida	FL

cities.csv

state_id	name	city_name
1	Monterey	Monterrey
2	Guadalajara	Guadalajara
3	Houston
4	Miami

All that matters is that the header is present in the csv files, the order can change if you wish.

—jq-autocomplete This will generate the view ready to be used in the jq-autocomplete plugin and print out the code to be pasted in the application.js file.

The following command generates everything including the jq view file:

script/generate belongs_to_city --include-seed --jq-autocomplete

Use the City structure in your models

Important

For the time being, if youd like to use other association methods including the city in your models. It is required that you include the following line of code

belongs_to   :city, :class_name => 'City'

To use the city structure in your models, include an integer city_id column in the model you want to use it and paste the following code into the model.

belongs_to_city

This gives you the attribute city_name. Each time you assign a value to this attribute, the gem will look for a city that matches the string in a ‘city, state’ format.

For example, with the given data on the csv example tables, the city monterrey would be assigned to a model given the following strings:

Monterrey, Nuevo Leon
Monterrey, NL
Monterrey
Monte

After the assignation, you would get a city model instance when you called model.city

Use the City in many attributes

If you have a model that needs more than one relation to a city, you could also pull it off like the following example.

Say you have a Travel model that has an origin and a destination, both related to a city. First of all you need to add an origin_id and a destination_id to the Model and then use this code into the model.

belongs_to_city 		:as => :origin

belongs_to_city 		:as => :destination

The code works the same way as previously stated, but instead of a city_name attribute you would have the origin_name and destination_name attributes.

Validate the presence of the City

If your using the autocomplete to find the city, you can validate that you have a city in the following way:

belongs_to_city			:as => :origin, :required => true

This gives you the ability to handle errors more appropriately like in the following way.

belongs_to_city			:as => :origin, :required => true, :messages => {:on_many_matches => 'We found many cities with your request, please be more specific!, :on_no_matches => 'We didnt find any city with the data you provided'}

TODO

Generators for relation migration in the database
Puts Jquery code to paste in application.js
Tests