== Rails 3 Tutorial
-- Josh Adams, Isotope11

---

Rails3 is the latest, greatest version of Rails.  It's about to be released, and it came about from a merging of the Merb and Rails teams.

We're going to build an app using rails3.  It'll be the start of an open source project we're working on here at Isotope11.  We call it the asset tracker, and it's basically a ticketing system to keep track of work around here.  We've been using a version built in rails1, and upgraded to rails2, for about four years now for everything we do as a company.

---

1) Build base rails project

First, we tell rvm to switch to a ruby1.9.2/rails3 environment (I've already set this env up, and assume you've done the same.  We're using rails 3.0.0.rc in this tutorial)

  $ rvm use ruby-1.9.2-head@rails3-rc

Then, we generate a new starter rails app

  $ rails new asset_tracker_tutorial

We verify that everything worked by starting the server and hitting localhost:3000

  $ rails server

I also set up a .rvmrc in the project so I can be sure I'm always using the right version when I drop in there.  Put the rvm use line in the file.

Finally, push this sucker up to github (you guys can check it out at this url later, it's public): http://github.com/knewter/asset_tracker_tutorial_pre

---

2) Prepare for TDD/BDD

Now, we all do Test-or-Behavior-Driven Development in the rails world, so the very next step is to define some tests using rspec and cucumber.  This requires some setup to get everything ready.

To do this, we need to get rspec into the app.  In rails3, this means Bundler and editing a Gemfile.

Then, edit the Gemfile and add the following:

  group :test, :development do
    gem 'rspec-rails', '>= 2.0.0.beta.19'
  end

  $ bundle install # This will install the bundle for the app

Now, run the rspec install script to get your app ready for rspec

  $ script/rails generate rspec:install

Now, tell rails to use rspec instead of Test::Unit when using its generators.  Open config/application.rb and add:

  config.generators do |g|
    g.test_framework :rspec
  end

(Thanks, http://blog.notahat.com/posts/43, for the rails3/rspec/cucumber setup notes)

---

3) Generate your first model and start testing - Client

Now we're ready to start building the application.  Our asset tracker's general model layout looks something like this:

    * Client (Attachments, Notes, Watches) - [status {current, default, shitty, etc}]
          o Project (Attachments, Notes, Watches) - [manager]
                + Ticket (Attachments, Notes, Watches) - [priority, assigned_to, status]
                      # WorkUnit (Attachments, Notes) - [description, time, overtime {bool}, unbilled {bool}, payment_record, billed_record]
    * User
    * Note
    * Attachment
    * Watch
    * Role
    * PaymentRecord
    * BillRecord

That is, Clients are the base model from which the more important stuff descends.  We'll go ahead and start generating a Client model.  We'll move on from there.

  $ rails generate model Client name:string status:string

That generates the model and an rspec test for us.  Let's go ahead and run that test.

  $ rake db:migrate # Have to get the db table created
  $ rake spec

It tells us that the spec is pending, and nicely asks us to generate some specs.  Let's do that.  We'll test that the client model validates the presence of the name and status fields.

  $ rake spec

It should've failed because we didn't add the validations to the model yet.  Do that.  Then try again.

  $ rake spec

Now it succeeds.  Awesome.  We're great at stuff.  Finally, a client's name should be unique.  Let's test for that.

  $ rake spec

It fails.  Now add the uniqueness constraint to the model.

  $ rake spec

OK, moving on.

---

4) Cucumber and controllers/views.

Set up cucumber by adding the following to your Gemfile (This is actually including our view-related stuff for adam's talk later as well):

# For cucumber-rails
gem 'rspec', ">=2.0.0.beta.19", :group => :test

gem 'haml-edge', '3.1.66', :require => 'haml'
gem 'compass', '>= 0.10.4'
gem 'lemonade', '>= 0.3.4'
gem 'sqlite3-ruby', :require => 'sqlite3'
gem 'thin'

group :test do
  gem "webrat"
  gem 'rspec-rails', ">=2.0.0.beta.19"
  gem 'cucumber'
  gem 'capybara'
  gem 'database_cleaner'
  gem 'cucumber-rails'
  gem 'spork'
  gem 'launchy'    # So you can do Then show me the page
end

Use bundler to install everything:

  $ bundle install

Finally, set up your Rails app.

  $ script/rails generate cucumber:skeleton --rspec --capybara

Now we can generate features using cucumber and start to define the project.

---

5) Define a feature for Clients#index

  $ vim features/clients.feature

(See the feature I've already got in the code at this point, because it'll take a while to build it up)

Then run it with:
  $ script/cucumber features

There's a 'Then show me the page' feature that will let you easily pull up a page with sample data when running your tests, and that's kind of cool.  I added that to the end of the clients index feature so you always get a web browser popping up with the index each time you run the clients feature.

That covers our first feature - managing clients.  Now let's move on.

---

6) Define a feature for Projects#index

  $ vim features/projects.feature

We'll be re-using a lot of the same stuff we used in clients here.  Copy-pasta for the fail.

---

NOTES:

To get ruby-debug working in ruby1.9, do this:
http://dirk.net/2010/04/17/ruby-debug-with-ruby-19x-and-rails-3-on-rvm/

-------------------------------------------------------------------------------
Making the Views not suck
-------------------------------------------------------------------------------
first i add the compass-susy pro into the gem file then install it

  gem 'compass-susy-plugin'
  $ bundle install
  
then i generate compass inside the project, with susy

 $ compass init rails . -r susy --using susy/project

it asks questions:

  Compass recommends that you keep your stylesheets in app/stylesheets
    instead of the Sass default location of public/stylesheets/sass.
    Is this OK? (Y/n) Y

  Compass recommends that you keep your compiled css in public/stylesheets/compiled/
    instead the Sass default of public/stylesheets/.
    However, if you're exclusively using Sass, then public/stylesheets/ is recommended.
    Emit compiled stylesheets to public/stylesheets/compiled/? (Y/n) Y

answer yes.

now we create/import the layout, and a couple of shared partials

  (see code)

and make sure we add in the required parts of compass:

%head
  = stylesheet_link_tag 'compiled/screen.scss', :media => 'screen, projection'
  = stylesheet_link_tag 'compiled/print.scss', :media => 'print'
  = stylesheet_link_tag 'compiled/ie.scss', :media => 'screen, projection'