h1. Metropoli
p. Metropoli is a flexible and unobstrusive city database engine that can relate to your Rails 3 models.
p. It is built using Rails Engines and is inspired on Devise, the authentication solution by Plataforma Tecnologia.
p. The main features of Metropoli are.
h2. Install it
p. Metropoli is built specifically for Rails 3, therefore it doesn't work with previous rails versions. Right now it's not released as a gem yet but you can use it copying the following code in your Gemfile.
bc. gem 'metropoli', :git => 'git://github.com/innku/metropoli.git'
bc. rails generate metropoli:install
p. Metropoli has 2 different installation options
h2. Seed it
p. Metropoli includes a rake task to seed the database based on CSV Files. The files are under the directory "/db/csv" and they are named:
p. By default the installation will create an example database but you will likely edit this files to fit your needs according to your country.
p. The csv files are self-explaining, if you want to add a column to any of the database tables, you can add it in the appropriate migration file, add a column in the csv file with the name of the new field as the first line, and the migration will just work.
p. This rake task will run the migration.
bc. rake metropoli:seed
p. errors?
p. If you should encounter any errors while seeding the database, you can clean the tables up with the following command:
bc. rake metropoli:cleanup
h2. Use it in your models
p. To start using metropoli you need to generate the migration that will relate your model to the engine. You can do this with the following command.
bc. rails generate metropoli model [city | state | country] [options]
p. The option --as is useful when you'd like to explicitly name your relation with the engine.
p. After you run the migration, you need to declare the association in your model.
bc. metropoli_for :city
p. This declaration will generate the attribute city_name in your model, both reader and writer. If you want to assign a city to your model you can simply assign it as a string. For example, if you had a user model, you might do the following.
bc. @user.city_name = 'Houston'
p. After that the user will be automatically related to the City. You can be more specific with the assignation like this:
bc. @user.city_name = 'Houston, Tx'
p. That will also work. This process is also valid for both states and countries.
p. If you want to explicitly name the relation it will be a similar process. For example if you have a trip with an origin and a destination you might declare it in the model like:
bc. metropoli_for :city, :as => 'origin'
bc. metropoli_for :city, :as => 'destination'
p. The generated attributes would be origin_name and destination_name. All of the previously mentioned functionality would work in the same way.
h2. Use it in your interface
p. If you want to use the autocomplete functionality you need to add both jquery and jqueryui to your layout. After that you need to add the script generated in the installation: metropoli.jquery.ui to your layout.
p. To use it just add one of the following classes to your inputs:
bc. f.text_field :city_name, :class => 'city_autocomplete'
bc. f.text_field :state_name, :class => 'state_autocomplete'
bc. f.text_field :country_name, :class => 'country_autocomplete'
p. The process of adding explicitly named relations is the same for the name of the attribute but the css class needs one of the above according to the relation type.
h2. Customize it
p. There are several ways to customize the gem with the configuration options found in the initializer:
metropoli.rb
h2. Extend its behaviour
To install the gem
bc. gem install bundler --version '~> 1.0.0'
bc. bundle install
p. If you want to add any gems, please note that we are using "jewelry":https://github.com/technicalpickles/jeweler. So you need to add it to the Rakefile. And then run rake gemspec
To run the tests
If you want to run the whole suite,
bc. rake test
If you want to run a single test file
bc. ruby -Itest test/file.rb
Please note that you do not need to add run any migrations because we are using a in memory database.
To see it working
There is a test app under test/test_app. Inside this app, you need to follow the instructions described at the top of this document.
h2. What we're doing to it
p. You can check out what we are doing to the project on:
http://www.pivotaltracker.com/projects/95880
h2. Copyright
p. Copyright (c) 2010 Innku. http://innku.com