The Mechanical Turk

As of last night, Ian became a father! At around 11pm, his son was born. Let me be the first in a public forum to congratulate him :)

Hopefully, he’ll soon post pictures—and a name!

Many of our plugins are now available on github: github.com/ianwhite

And OSS projects such as these can now be hosted free on lighthouse: ianwhite.lighthouseapp.com

The ones that you see on lighthouse have all had a good dusting off to make sure they're compliant with the very latest edge, and BC to 2.0.2. response_for is now branched to support edge and 2.0.2, but the other plugins haven't yet required this.

If you don't see one you use there, it means that I haven't deemed it being used by many people - so leave a comment to say otherwise

RC's got a github home now

The subversion repo will still continue to be maintained for the foreseeable future.

RC's also reported as being one of the things under the hood at naked.

Lastly, I've been cooking my CI with garlic.

So I've been curled up in a ball, riding the git avalanche, trying to sort out my rails plugins - making sure they're getting tested against the latest and greatest.

Inspired by this ticket for rspec, git's coolness, some menthol snuff, and a lot of coffee, I came up with garlic.

It's an extremely lightweight set of rake tasks that let you test your plugins or app against various version of rails, and other dependencies.

If you want to see it in action (on one of my plugins), do this:

  git clone git://github.com/ianwhite/inherit_views
  cd inherit_views
  rake cruise

Sit back, watch it download all the dependencies, then create rails apps for each set, and run the rcov task for the plugin in each one... (the download only happens the first time you do it).

You configure it using a little dsl, like this:

garlic do
  # default paths are 'garlic/work', and 'garlic/repos'
  work_path "tmp/work"
  repo_path "tmp/repos"
  
  # repo, give a url, specify :local to use a local repo (faster
  # and will still update from the origin url)
  repo 'rails', :url => 'git://github.com/rails/rails' #, :local => "~/dev/vendor/rails"
  repo 'rspec', :url => 'git://github.com/dchelimsky/rspec'
  repo 'rspec-rails', :url => 'git://github.com/ianwhite/rspec-rails'
  repo 'inherit_views', :url => '.'
  
  # for target, default repo is 'rails', default branch is 'master'
  target 'edge'
  target '2.0-stable', :branch => 'origin/2-0-stable'
  target '2.0.2', :tag => 'v2.0.2'
  
  all_targets do
    prepare do
      plugin 'rspec'
      plugin 'rspec-rails', :branch => 'origin/aliased-render-partial' do
        sh "script/generate rspec -f"
      end
      plugin 'inherit_views'
    end
    
    run do
      cd "vendor/plugins/inherit_views" do
        sh "rake spec:rcov:verify"
      end
    end
  end
end

Notice that I'm using my fork of rpsec-rails, and the plugin specifies that it should use a particular branch 'aliased-render-partial'. The reason for this is that I have some outstanding tickets on rspec, which haven't been resolved. In the meantime, I can just use my patched version. If the patch gets accepted, I can just change the url, and garlic will inform me that I need to remove and run rake garlic:install_repos to get the new one. This is just making use of the awesomely cool coolness of git.

Also notice the block passed to the 'rspec-rails' plugin. This will be executed inside the rails target after the plugin has been installed. Finally the run block says what should happen for the actual CI. In this case cding into the plugin and running an rcov task.

It's new stuff

So it probably has bugs and stuff.

You may have heard of the Dynamic CSS resolution switcher from Particletree, it's a neat bit of js that allows you to specify different css files depending on the browser resolution.

We love this script, but we had problems running it with Safari, and we are using prototype, so we wanted to make use of its goodness for the browser independent stuff.

So, if you're already using prototype, the following script achieves the same effect as the original particletree script. It also uses the dom:ready event, which fires after the dom is loaded, but before the screen is drawn, so you shouldn't see any 'twitch'.

Example

In the following example, we have three stylesheets that correspond to browser widths as follows:

  thin      up to 1020
  wide     1021...1400
  widest    above 1400

For non js users we want to default to 'wide' (the middle one). In order for this to work properly, we disable all of the non-default stylesheet links.

In your html

In your html you need to link to the three stylesheets, give them each a title attribute, and disable the ones you don't want non-js users to see.

  <link title="wide" href="/stylesheets/wide.css" rel="stylesheet" type="text/css" />
  <link title="thin" disabled="true" href="/stylesheets/thin.css" rel="stylesheet"  type="text/css" />
  <link title="widest" disabled="true" href="/stylesheets/widest.css" rel="stylesheet" type="text/css" />

And link to the script, we'll call it dynamic_css.js

  <script src="/javascripts/dynamic_css.js" type="text/javascript"></script>

The script

This is the script, it uses the title attribute of the stylesheets to disable or enable them. It is run when the dom is ready, and when the browser width changes.

// DYNAMIC RESOLUTION SWITCHER
// Originally from ParticleTree
// Simplified with Prototype by Ian White of Argument from Design 2008
// include prototype.js (>=1.6) before this file

// you need to edit this function as per your situation
function applyDynamicLayout() {
  var width = document.viewport.getWidth();
  if (width <= 1020 )                 { applyStylesheet("thin") }
  if (width > 1020 && width <= 1400)  { applyStylesheet("wide") }
  if (width > 1400)                   { applyStylesheet("widest") }
}

// you shouldn't need to edit past here
function applyStylesheet(title) {
  var i, stylesheet;
  for(i=0; (stylesheet = document.getElementsByTagName("link")[i]); i++) {
    // is it a stylesheet with a title attribute?
    if(stylesheet.getAttribute("rel").indexOf("style") != -1 && stylesheet.getAttribute("title")) {
      stylesheet.disabled = true;
      if (stylesheet.getAttribute("title") == title) {
        stylesheet.disabled = false;
      }
    }
  }
}

//Run applyDynamicLayout function when window is ready and when it resizes.
Event.observe(document, 'dom:ready', applyDynamicLayout);
Event.observe(window, 'resize', applyDynamicLayout);

That's it!

That's it, it works for us in Safari, Opera, FF and IE 6 or greater.

Also, you can have as many stylesheet links as you like with the same title. For example, let's say you have some IE6 specific kludges for the 'thin' layout. You would do this:

<!--[if lt IE 7]>
  <link title="thin" disabled="true" href="/stylesheets/thinie6.css" rel="stylesheet" type="text/css" />
<![endif]-->

There's going to be some new features coming in resources_controller. Stay tuned...

Meanwhile, rc has got a new repository location (the old one will still work for a while, but will remain at the current version):

trunk: http://svn.ardes.com/resources_controller/trunk/resources_controller

tag 0.5: http://svn.ardes.com/resources_controller/tags/0.5/resources_controller

For those interested in providing patches, you should checkout http://svn.ardes.com/resources_controller/trunk and run rake pre_commit in that directory to check your changes. Then send a diff along, or post it on the google group.

So I was writing a Rakefile and found myself doing stuff like this:

  cmd = "svn co #{src} #{dest}"
  puts cmd
  system cmd

Everytime I wrote lines like this, a little corner of my heart died.

I dreamt of something like this:

  "svn co #{src} #{dest}".to :puts, :system

But it's hard to do this properly, because you need to get hold of the receiver (in the above case main, or some Rake task) or binding, so that the methods can be sent where they ought. With crippled Kernel#caller, the the demise of Binding.of_caller (Ruby-debug solved the problem but there's significant overhead) it was looking like I should just wait for the next ruby release.

But I frowned like Hiro and came up with this:

  pass("svn co #{src} #{dest}").to :puts, :system

Briefly, Object gets #pass which creates a PassProxy (basic object). It keeps hold of the receiver, but acts like the object (in this case the string). When you send #to(:method) to this PassProxy, it calls the original receiver with the object.

This is just sugar, but its nice sugar in some cases. Compare:

   # plain ruby
   msg = "oooh!"
   MyObj.foo msg
   MyObj.far msg
   MyObj.faz msg
   msg
   # => 'oooh!'
   

   # returning (ActiveSupport)
   returning "oooh!" do |s|
     MyObj.foo s
     MyObj.far s
     MyObj.faz s
   end
   # => 'oooh!'

   # (pass) (this code)
   MyObj.pass("oooh!").to :foo, :far, :faz
   # => 'oooh!'

But eat too much sugar and your teeth will fall out: I realised that this probably has limited usefulness (how often do you need to send the same object to a bunch of different methods?). But at least I learned some things in that last couple of hours of coding.

Go get the code from pastie if you're interested.

Thanks for reading

If you're using response_for, then you might want to grab response_for_resources_controller

It simply replaces the default action modules with ones that use the response_for idiom.

This means that you can override what an action does without overriding how it responds. For example, I want a standard REST controller, that sets a protected attribute, user, on create.

class PostsController < ApplicationController
  resources_controller_for :posts

  def create
    self.resource = new_resource
    resource.user = current_user
    save_resource
  end # the standard response_for :create is used
end

If you don't know what response_for does, it lets you declaratively set the respond_to of an action. For example: if you want to override some aspect of the response, here I just want to change the flash message on successful create:

class LoginsController < ApplicationController
  resources_controller_for :logins

  response_for :create do |format|
    format.html { flash[:notice = "You have logged in" } if resource_saved?
  end
end

miscellany

I added save_resource and resource_saved? to rc, as a way of sharing the result of the save outside the scope of the action. Previously I've done this with valid?, but realised that this might hit the database unnecessarily in some circumstances. You can use either idiom.

If you've ever subclassed a controller to deal with a particular MIME type, say FBML, you will have had the painful experience of having to copy and paste all of your contoller's actions, adding, or replacing the fbml blocks into the code.

This doesn't feel right - and it isn't. If you have to change some controller logic - you have to remember to change it in all these subclassed controllers.

Enter response_for (rdoc here).

response_for lets you declaratively specify how your actions should respond to particular Mime types. This helps particularly when your action's logic is not simple (like a CRUD action - but it still helps there). Here's an example I just made up:

class ReportController < ApplicationController
  # this puppy gets some models to collaborate to form a report
  def report
    @report = {}
    @report[:invoiced] = Customer.find_invoiced
    @report[:outstanding] = @report[:invoiced].select {|c| c.latest_invoice.outstanding? }
      
    respond_to do |format|
      format.html 
      format.xml { # some funky xml stuff here }
    end
  end
end

Let's say I wanted to make FBML responding version of this controller, normally, I'd have to copy/paste this action and add the fbml responses. With response_for, I do this:

  class FacebookReportController < ReportController
  response_for :report do |format|
    format.fbml { # my funky fbml stuff here, accessing @report}
  end
end

So, down the line, if I change the way my @report object is generated, I don't have to change my subclassed controllers.

Another example: create

You can choose to replace the respond_to block of the action as well. This means that common actions can be written, and the response can be adjusted according to your needs (resources_controller comes to mind).

Here's a standard create action:

class ForumsController < ApplicationController
  def create
    @forum = Forum.new(params[:forum])
    @forum.save
      
    respond_to do |format|
      if @forum.valid?
        flash[:notice] = 'Forum was successfully created.'
        format.html { redirect_to(@forum) }
        format.xml  { render :xml => @forum, :status => :created, :location => @forum }
      else
        format.html { render :action => "new" }
        format.xml  { render :xml => @forum.errors, :status => :unprocessable_entity }
      end
    end
  end
end

Let's say you want to create an FBML only version of this:

class FacebookForumsController < ForumsController
  response_for :create, :replace => true do |format|
    if @forum.valid?
      format.fbml { # funky fbml stuff for valid record }
    else
      format.fbml { # and for an invalid record}
    end
  end
end

One last example

For many actions, you just want to tell your action to respond to particular MIME type and a template does the rest:

class FacebookUsersController < UsersController
  response_for :index, :show, :types => [:fbml]
  end

You don't need to have a respond_to block defined in your actions - the parent controller could look like:

class UsersController < ApplicationController
  def index
    @users = User.find :all
  end
  
  def show
    @user = User.find params[:id]
  end
end

resources_controller + response_for

For those users of resources_controller, response_for gives you an easy way of adding responses on an ad-hoc basis (like if only one or two of your actions need to be RSS feeds or summat)

This is the first release...

and I welcome any bug reports

Jason Lee of Big First Name just posted his experiences of using resources_controller on the google group.

He writes:

I've just converted one my existing apps ( http://big.first.name ) to using the resources_controller plugin and thought I'd share some results with the group...
before RC, the output of "rake stats"...

+---------------+-------+-------+---------+---------
| Name          | Lines | LOC   | Classes | Methods 
| Controllers   |  1785 |  1324 |      20 |     112 

after RC conversion (with only minor refactoring)...

+---------------+-------+-------+---------+---------
| Name          | Lines | LOC   | Classes | Methods 
| Controllers   |   877 |   655 |      20 |      45

That's 50% less code and 60% less methods. I've still got some chunky controller code lying around but overall I'm very happy with the result.

That's cool!

I gave a talk about resources_controller at LRUG which was great fun.

Thanks to everyone for listening and for the feedback. Skills Matter are apparently going to post a video of the presentation at some point. In the meantime, the slides are here.

I've been chatting to a few people at RailsConfEuropoe about resources_controller, so I thought I'd say a few words about waht it's key features are, and about RC at RailsConfEuropoe in general.

Key features

There's a few plugins out there that try and solve the same sort of problem - DRY up RESTful controllers. I believe that RC's standout features can be seen when considering how to write controller for a polymorhpic has_many relationship.

Polymorphic Tags

So you want to tag a bunch of models, and so you sure the :polymorphic has_many assoc, and make a Tag model with belongs_to :taggable, :polymorphic => true.

You want tags to be nested under a bunch of different resources like this:

  map.resources :users do |user|
   user.resources :tags, :controller => 'user_tags'
  end

  map.resources :posts do |post|
   post.resources :tags, :controller => 'post_tags'
  end

Standardly, you'd then have to write two controllers: UserTagsController, and PostTagsController, and map the above two nested routes to those different controllers. These would be essentially the same functionality except:

• they would load different models in before filters: @user in one and @post in the other,
• they get the post from different collections (@tag = @user.tags.find(params[:tags_id]) vs @tag = @post.tags.find(params[:tags_id])),
• they redirect to different routes on completion of certain actions user_tags_path and post_tags_path in the other.

To do this, even with plugins to dry everything up, you still need to create two (or three, or four) controllers for tags - all doing essentially the same thing.

it gets worse. You'll need a bunch of different views - because they all need to link to urls relative to the enclosing resource. Suddenly you've got a lot of really similar code - or some really ungly hacks in your views.

(and all of this gets much worse if you have deeply nested routes)

Polymorphic tags with resources_controller

resources_controller (used in the default way) inspects the route that was used to invoke the controller. From this, it:

• loads all of the enclosing resources,
• uses the immediately enclosing resource as the resource service (the object that we send find and new to to - in the case of /posts it would be the Post class, in the case of /post/1/tags it would be the @post.tags association),
• does some method missing magic so that you can refer to all named routes relative to the current resource

All this means you just need to write one controller, and one set of views for Tags

Here's some sample code

  class TagsController < ApplicationCntroller
    resources_controller_for :tags
  end

in show.html.erb:

  <%= link_to 'tags', resources_path %>

The above will be user_tags_path(@user) in one case and post_tags_path(@post) in another.

It gets better, you can refer to the enclosing resource as well:

  <%= link_to "back to #{enclosing_resource_name.humanize}", enclosing_resource_path %>

And if you have routes like /users/1/posts/2/tags, and /posts/1/tags, the you can use the same view for posts:

  <%= link_to 'tags', resource_tags_path %> # in /users/1/posts/2/tags will be:
                                            # user_post_tags_path(@user, @post)
                                            
  <%= link_to 'tags', resource_tags_path %> # in /posts/2/tags will be:
                                            # post_tags_path(@post)

That's just some of the features, I'd love to get feedback, patches, bug reports, etc. There are links to RC via svn, and rdoc on our plugins page

BoF and RejectConf

Man, I've got a lot to learn about presentations...

I gave a BoF at RailsConfEurope07 session on resources_controller - I was expecting about 10 people and a round table discussion on taking the pain out of RESTful controllers. About 50 or 60 people turned up so we ended up all crowded round a couple of laptops. But everyone was friendly and there was no heckling. Paolo, who gave the incredibly entertaining talk on widgets, took some photos

There was, however, plenty of heckling at the RejectConf talk. The format was 5 minutes of slides, 20 seconds automatic countdown for each one. I wrote the presentation during the day, and ran through it with my wife before hand. It sucked - way too much info. So I cut it down.

However, I was first up, and gave the audience the choice of the insane, or sane, talk, and they chose insane. I tried to get across about 1/2 an hour's worth of stuff in 5 minutes, and the audience looked as though they were in a wind tunnel. It was a great icebreaker for the other speakers though. I'll post the slides here in due course.

RejectConf was simply awesome by the way. The berlin ruby user group rocks.

Tracking our time spent on projects has been a major pain for us. We've tried a few of the OS X solutions out there, and they all have some of the following problems:

• B L O A T E D - so many useless features
• You have to either turn the tracker on and off manually, which we invariably forget to do, or
• You can associate one application with turning the tracker on - which is not fine grained enough

So we rolled our own. matewatch simply checks what TextMate documents you're editing and records the intervals of time that those documents are frontmost in TextMate.

Howto

It's written in ruby (of course), and you need to grab rubygems, and install rubyosa and activesupport. (See the bottom of this post for instructions on this.)

Then install matewatch into a directory in your $PATH:

  svn export http://svn.ardes.com/ardes/matewatch/matewatch

Fire it up (in verbose mode to see what its doing)

  matewatch start -v

in another terminal, add a project, then do some work

  matewatch add rails_plugins ~/Development/rails_plugins

This is what the output looks like

  +++ Textmate active at Fri Sep 14 14:45:17 +0100 2007
  [#] plugins started at Fri Sep 14 14:45:27 +0100 2007
  --- Textmate inactive at Fri Sep 14 14:45:37 +0100 2007
  [ ] plugins stopped at Fri Sep 14 14:45:37 +0100 2007

Then, when you want to see how much time you've been hacking away

  matewatch report rails_plugins
  
  ======================================
  rails_plugins: report => Fri 14/Sep/07
  ======================================
   - 11/Sep/07:   0:00:35
   - 12/Sep/07:   4:40:01
   - 13/Sep/07:   2:35:16
   - 14/Sep/07:   0:00:10
   ----- TOTAL:   7:16:03 [7 hours, 30 minutes (15 min chunks)]

You can get a variety of reports. just do matewatch help to see what's available.

Sleepwatcher

If you install sleepwatcher (just the daemon, you don't need to install the startup item) then matewatch will interrupt sessions when the computer goes to sleep.

Happy tracking

We've just completed a small project that we estimated would take 14 hours - with matewatch we learnt that it took us closer to double that. It's turning out to be be a very useful little script.

If you find a bug, or have a feature request, let us know.

Installing dependencies

Ruby

See this guide for getting a suitable ruby on OS X

Rubygems

Get rubygems extract it, and set it up with

  sudo ruby setup.rb

gems

Now install the required gems

  sudo gem install activesupport
  sudo gem install rubyosa

All the options

This is the output of matewatch help

matewatch watches textmate and logs how long you are working on files in spec-
ified directories

USAGE

  matewatch COMMAND [OPTIONS]
  
  matewatch start
    Starts the project watcher
    
    --verbose               -v            show output
    --poll=<n>              -p <n>        poll every (n) seconds
    --require-frontmost     -r            require that textmate be frontmost
                                          application to log time data
  
  matewatch report [<name>]
    Show brief report of hours/minutes per day

    --hourly  OR  --session               show hourly/session report
    --from=<date>           -f <date>     from specified date
    --to=<date>             -t <date>     to specified date
    --day=<date>            -d <date>     for specified date

  matewatch list
    List projects being watched
    
  matewatch add <name> <path> [<position>]
    Add a project to the watch list
    
  matewatch remove <name>
    Remove a project from the watch list.  Copies the project data to
    a timestamped backup in /Users/ian/.matewatch
    
  matewatch move <name> <position>
    Move a project up or down the list

  matewatch pause
    Will pause the current matewatcher, 'matewatch start' will restart it

DATA

  If you want to get at the session data for your projects, you'll find them
  in /Users/ian/.matewatch.
  
  The files are YAML format, and so are easily editable/exportable.

    by Argument from Design (c) 2007 <http://www.ardes.com> (MIT License)

It's been a while, but some major improvements to resources_controller have just been checked in.

The test coverage has slipped just a bit - that's my next task. However, it's still pretty good. Thanks to the RC group (in particluar Chris Hapgood) and the Guys at Greenvoice for nudging me towards singular resources, and away from lots of inherited controllers.

Major headlines

• Singular resources are fully supported
• RC loads enclosing resources by default, which means you pretty much just have to write one line to have all your routes taken care of (more on this below).
• Cleaner code

Go get get it from the ArDes plugins page.

What follows is from the rdoc

With resources_controller (http://svn.ardes.com/rails_plugins/resources_controller) you can quickly add an ActiveResource compliant controller for your your RESTful models.

Examples

Here are some examples - for more on how to use RC go to the Usage section at the bottom, for syntax head to resources_controller_for

Example 1: Super simple usage

Here's a simple example of how it works with a Forums has many Posts model:

  class ForumsController < ApplicationController
    resources_controller_for :forums
  end

Your controller will get the standard CRUD actions, @forum will be set in member actions, @forums in index.

Example 2: Specifying enclosing resources

  class PostsController < ApplicationController
    resources_controller_for :posts, :in => :forum
  end

As above, but the controller will load @forum on every action, and use @forum to find and create @posts

Wildcard enclosing resources

All of the above examples will work for any routes that match what it specified

  
              PATH                     RESOURCES CONTROLLER WILL DO:

  Example 1  /forums                   @forums = Forum.find(:all)

             /users/2/forums           @user = User.find(2)
                                       @forums = @user.forums.find(:all)

  Example 2  /posts                    @posts = Post.find(:all)

             /forums/2/posts           @forum = Forum.find(2)
                                       @posts = @forum.posts.find(:all)

             /sites/4/forums/3/posts   @site = Site.find(4)
                                       @forum = @site.forums.find(3)
                                       @posts = @forum.posts.find(:all)

             /users/2/posts/1          This won't work as the controller specified
                                       that :posts are :in => :forum

It is up to you which routes to open to the controller (in config/routes.rb). When you do, RC will use the route segments to drill down to the specified resource. This means that if User 3 does not have Post 5, then /users/3/posts/5 will raise a RecordNotFound Error. You dont' have to write any extra code to do this oft repeated controller pattern.

With RC, your route specification flows through to the controller - no need to repeat yourself.

If you don't want to have RC match wildcard resources just pass :load_enclosing => false

  resources_controller_for :posts, :in => :forum, :load_enclosing => 'false'

Example 3: Singleton resource

Here's an example of a singleton, the account pattern that is so common.

  class AccountController < ApplicationController
    resources_controller_for :account, :class => User, :singleton => true do
      @current_user
    end
  end

Your controller will use the block to find the resource. The @account will be assigned to @current_user

Example 4: Allowing PostsController to be used all over

First thing to do is remove :in => :forum

  class PostsController < ApplicationController
    resources_controller_for :posts
  end

This will now work for /users/2/posts.

Example 4 and a bit: Mapping non standard resources

How about /account/posts? The account is found in a non standard way - RC won't be able to figure out how tofind it if it appears in the route. So we give it some help.

(in PostsController)

  map_resource :account, :singleton => true, :class => User, :find => :current_user

Now, if :account apears in any part of a route (for PostsController) it will be mapped to (in this case) the current_user method of teh PostsController.

To make the :account mapping available to all, just chuck it in ApplicationController

This will work for any resource which can't be inferred from its route segment name

  map_resource :peeps, :source => :users
  map_resource :posts, :class => BadlyNamedPostClass

Example 5: Singleton association

Here's another singleton example - one where it corresponds to a has_one or belongs_to association

  class ImageController < ApplicationController
    resources_controller_for :image, :singleton => true
  end

When invoked with /users/3/image RC will find @user, and use @user.image to find the resource, and @user.build_image, to create a new resource.

Putting it all together

An exmaple app

config/routes.rb:

 map.resource :account do |account|
   account.resource :image
   account.resources :posts
 end

 map.resources :users do |user|
   user.resource :image
   user.resources :posts
 end

 map.resources :forums do |forum|
   forum.resources :posts
   forum.resource :image
 end

app/controllers:

 class ApplicationController < ActionController::Base
   map_resource :account, :singleton => true, :find => :current_user

   def current_user # get it from session or whatnot
 end

 class ForumsController < AplicationController
   resources_controller_for :forums
 end
   
 class PostsController < AplicationController
   resources_controller_for :posts
 end

 class UsersController < AplicationController
   resources_controller_for :users
 end

 class ImageController < AplicationController
   resources_controller_for :image, :singleton => true
 end

 class AccountController < ApplicationController
   resources_controller_for :account, :singleton => true, :find => :current_user
 end

This is how the app will handle the following routes:

 PATH                   CONTROLLER    WHICH WILL DO:
 
 /forums                forums        @forums = Forum.find(:all)
 
 /forums/2/posts        posts         @forum = Forum.find(2)
                                      @posts = @forum.forums.find(:all)

 /forums/2/image        image         @forum = Forum.find(2)
                                      @image = @forum.image   
 
 /image                       no route

 /posts                       no route

 /users/2/posts/3       posts         @user = User.find(2)
                                      @post = @user.posts.find(3)
 
 /users/2/image POST    image         @user = User.find(2)
                                      @image = @user.build_image(params[:image])

 /account               account       @account = self.current_user

 /account/image         image         @account = self.current_user
                                      @image = @account.image

 /account/posts/3 PUT   posts         @account = self.current_user
                                      @post = @account.posts.find(3)
                                      @post.update_attributes(params[:post])

Views

Ok - so how do I write the views?

For most cases, just in exactly the way you would expect to. RC sets the instance variables to what they should be.

But, in some cases, you are going to have different variables set - for example

  /users/1/posts    =>  @user, @posts
  /forums/2/posts   =>  @forum, @posts

Here are some options (all are appropriate for different circumstances):

• test for the existence of @user or @forum in the view, and display it differently
• have two different controllers UserPostsController and ForumPostsController, with different views (and direct the routes to them in routes.rb)
• use enclosing_resource - which always refers to the... immediately enclosing resource.

Using the last technique, you might write your posts index as follows (here assuming that both Forum and User have .name)

  <h1>Posts for <%= link_to enclosing_resource_path, "#{enclosing_resource_name.humanize}: #{enclosing_resource.name}" %></h1>

  <%= render :partial => 'post', :collection => @posts %>

Notice enclosing_resource_name - this will be something like 'user', or 'post'. Also enclosing_resource_path - in RC you get all of the named route helpers relativised to the current resource and enclosing_resource. See NamedRouteHelper for more details.

This can useful when writing the _post partial:

  <p>
    <%= post.name %>
    <%= link_to 'edit', edit_resource_path(tag) %>
    <%= link_to 'destroy', resource_path(tag), :method => :delete %>
  </p>

when viewed at /users/1/posts it will show

 <p>
   Cool post
   <a href="/users/1/posts/1/edit">edit</a>
   <a href="js nightmare with /users/1/posts/1">delete</a>
 </p>
 ...

when viewd at /forums/1/posts it will show

 <p>
   Cool post
   <a href="/forums/1/posts/3/edit">edit</a>
   <a href="js nightmare with /forums/1/posts/3">delete</a>
 </p>
 ...

This is like polymorphic urls, except that RC will just use whatever enclosing resources are currently loaded to generate the urls/paths.

General Usage

To use RC, there are just three class methods on controller to learn.

  resources_controller_for name, options, &block
 
  nested_in name, options, &block

  map_resource name, options, &block

Customising finding and creating

If you want to implement something like query params you can override find_resources. If you want to change the way your new resources are created you can override new_resource.

  class PostsController < ApplicationController
    resources_controller_for :posts

    def find_resources
      resource_service.find :all, :order => params[:sort_by]
    end

    def new_resource
      returning resource_service.new(params[resource_name]) do |post|
        post.ip_address = request.remote_ip
      end
    end
  end

In the same way, you can override find_resource.

Writing controller actions

You can make use of RC internals to simplify your actions.

Here's an example where you want to re-order an acts_as_list model. You define a class method on the model (say *order_by_ids* which takes and array of ids). You can then make use of *resource_service* (which makes use of awesome rails magic) to send correctly scoped messages to your models.

Here's how to write an order action

  def order
    resource_service.order_by_ids["things_order"]
  end

the route

  map.resources :things, :collection => {:order => :put}

and the view can conatin a scriptaculous drag and drop with param name 'things_order'

When this controller is invoked of /things the :order_by_ids message will be sent to the Thing class, when it's invoked by /foos/1/things, then :order_by_ids message will be send to Foo.find(1).things association

Check out our rails plugins page, which contains links to rdoc, svn and other plugin related stuff.

You may also be interested in the latest build report which shows what plugins are tested against what versions of rails.