Belongs to city

This gem is discontinued. A newer, better gem on http://github.com/adriancuadros/metropoli

It has extended objectives and a totally different aproach. It was developed for specifically for rails 3 so you should probably check it out.

gem install belongs_to_city

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

states.csv

cities.csv

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

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

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.

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'}

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

Copyright © 2010 Innku. See LICENSE for details.