Sunday, December 14, 2008

Rails ActionController facelift using ResourceController and named_scope

I am pretty sure that it is not only my Rails controllers which changed appearance more than once during the past 3 or 4 years. Concepts like RESTful controllers, nested resources, ActiveRecord scoping kept on changing the way we build our Rails controller. Nowadays, my Rails controllers are barely similar to what they looked like 4 years ago.

During pre REST days, my controllers were so ugly and fat. with too many actions to count and do a lot more than the controller meant to do in an MVC framework. Then came RESTful controller which was really, really a nice way to help application designer to organize and "design" the application. RESTful controllers concept is revolutionary in that it simplified or abstract away the complexity of the application plumbing and repetitive routines and made my poor little mind focus on the application design instead.

And then came resources scaffold
The scaffold generator now do us all the work to have a nice RESTful controller that can CRUD your model and responds to HTML, XML, JS. But I need to confess that I've never liked generators. Heck, it is the only reason why I don't use IDEs. They pollute my code with lines I didn't write, and that's plain ugly. It is lovely to have your controller speak REST in XML, but it was not a good feeling when I see all those respond_to lines scattered all over my controllers at the time when my application is not yet designed to be used as such.

And what made it really worse is that most of the time the generated controller needed almost 80% editing, to scope my models I use in the controllers, like @site.pages, @user.posts, and to paginate results, set model attributes assignments..etc. So it was obvious that generators wouldn't cut it. We needed some help to abstract all the repetitive codes in our controller and find a solution for problems like relations aware controller that respect scoping, can deal with nested resource and namespaces. I am sure that any rails developer (or any MVC web developer) knows the kind of problem I am talking about.

Resource Controller plugin
More than a year ago I found some Rails plugins to do just that. But I was too skeptical to use them in production. Time passed and there are now a really good, tested and tried solution for the kind of problem I am talking about. It is called "Resource Controller".

It is a fine plugin written by James Golick. Thank you James. The other plugins like resource_this and make_resourceful were steps in the right direction but Resource_Controller is the way to go.
Link
After months of using it I feel pretty confident with resource controller. And as all tools that abstract away repetitive noise it allowed me to focus more on my application design and actually I developed more productive patterns in developing my application. Patterns that changed the face of my rails controllers beyond recognition. Here is a minimal Resource Controller.



1
2
class UsersController < ResourceController::Base
end

Suddenly, I had this ActiveRecord thrill again, but with Resource Controller this time. I bet this is the skinniest controller one could dream about. Come on Rails core team, when will we see Jamis' Resource controller merged!

Well the next thing to do is playing around and try to see how to solve the problems I mentioned above. But only after introducing my newest love, "Named scope". which prove very useful in DRYing my controller even more.

Named Scopes
I always thought that the best feature in ActiveRecord is scoping through associations. Like, '@user.posts.find(:all, :limit => 10)'. This feature alone is enough to use ActiveRecord. The next best ever feature in ActiveRecord is named_scope. I couldn't recommend enough using named_scope. Just use it. It is core since Rails 2.1.

Coupling named_scope with Resource Controllers really open new application design territory. Imagine the following requirement.
  • One pages controller that can be used to list all the pages in a portal
  • It could be used nested under users resource, so it should scope pages to user.
  • It should handle posts pending for approvals.
  • It should fetch the next and previous pages according to the context or the scope it works within, be it portal pages, users pages, or user's pending pages or portal's pending pages.

Let's build the controller
First we do the routes, a simple nested routes and then the controller.



1
2
3
4
5
6
7
8
map.resources :users do |user|
    user.resources :pages
end
map.resources :pages

class PagesController < ResourceController::Base
    belongs_to :user
end
This is the simplest form of controller to make it serve routes like /user/12/pages/new and do all the REST actions, be it scoped to user or not. But certainly life isn't that simple. What if you want to paginate results and get user by user_name instead of user_id like "/user/hany/pages".




1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class PagesController < ResourceController::Base  
  before_filter :set_scope 
  belongs_to :user 

  private 
  
  def parent_object 
    @parent ||= User.find_by_name(params[:user_id]) if params[:user_id] 
  end

  def set_scope 
    @scope = @portal.pages 
    @scope = @scope.by_user(parent_object.id) if parent_object 
  end 

  def collection 
    @pages ||= @scope.paginate(:all, :page => params[:page])
  end
end
Here I added some private methods. The parent_object method to get the parent object by name. I introduced the set_scope method which does set the scope (or context) of the collection set of pages we need to work with. Actually, parent_object and collection are both overridden methods of resource_controller. and set_scope method is mine, and I run it in a before_filter and use it in the controller to find the pages within the set scope. I could have just do scoping inside collection method, but later I will need to have a handle for the scope in different places in the controller other than "collection".

The set_scope method is interesting because I stack up the scope conditionally according to the context within which the controller is running. I mean if the controller is nested in users resource it will find params[:user_id] and the parent_object return a user object and then the @scope of users pages will be added. Which is a named scope in this case "Page.by_user()". I could have use parent_object.pages which is the natural association scoping of ActiveRecord I got with the "has_many :pages" but because my application serves several portals, and @portal got assigned according to subdomains on the application controller, I don't won't to loose the @portal scope '@portal.pages' so it was either make a named_scope for portals or users.

Notice here that @scope.find(:all, :conditions => {:user_id => parent_object.id}) will not do us any good because you will not be able then to narrow down those scopes by stacking them. But sure an inline or anonymous named_scope will suffice instead.

Now I need to make the controller serve pages pending for approvals and fetch the next and previous pages properly according to the scope. Some routes need to be set first. Changing the scope is only a matter of adding a new line to the set_scope method according to the passed params[], so all I need to do is passing non blank params[:pending]. Of course passing it hanged on the url like '/user/hany/pages?pending=1' is not an option. I need it to be clean like '/user/hany/pending_pages' and to say the truth it is not about cleanliness, it is about setting proper url automagically as I will show you later.




1
2
3
4
5
6
7
map.resources :users do |user|
  user.resources :pages, :requirements => {:pending => false }
  user.resources :pending_pages, :controller => 'pages', :requirements => {:pending => true  }
end
map.resources :pages, :requirements => {:pending => false }
map.resources :pending_pages, :controller => 'pages', :requirements => {:pending => true  }


Here I added pending_pages resources and pass explicitly the controller name because I will use my same pages controller. I made the resources properly set the pending parameter to true or false. I don't believe Rails 2.2 shallow routes option will spare me the pages resources repetitions. May be we need another way to make the parent resources optional?! but anyways, now that we have the routes properly set, let's see the controller.




1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class PagesController < ResourceController::Base
        
  before_filter :set_scope
  belongs_to :user

  private

  def parent_object
    @parent ||= User.find_by_name(params[:user_id]) if params[:user_id]
  end

  def set_scope
    @scope = @portal.pages
    @scope = @scope.by_user(parent_object.id) if parent_object
    @scope = @scope.pending(params[:pending])
  end

  def collection
    @pages ||= @scope.paginate(:all, :page => params[:page])
  end

  def route_name
    params[:pending] ? 'pending_post' : 'post'
  end
end

Here I added one line to set_scope to add the pending scope if the params[:pending] was true. But for a change I didn't check for params[:pending], instead I pass it to the named_scope which will check internally if it set or not and do the scope accordingly. Actually I did this in my real application to not be forced to make another not_pending named_scope. Because in real life you will need not to publish unpublished pages. errr.. ok, i mean the pending scope is unlike users scope, which is like, "if parent user is not set just show all the pages anyway", this will not work here, we need it to be, "if pending status is false just list only the published pages". And now it's a good chance to demonstrate how to pass arguments to named_scope.



1
2
3
4
class Page < ActiveRecord::Base
  named_scope :by_user, lambda{|u| {:conditions => {:user_id => u} } }
  named_scope :pending, lambda{|s| {:conditions => {:published => s} } }
end
where is the next and previous links?
It is a very healthy practice to provide a next and previous item links in your show item page. For many obvious reasons, for one is to spare the user going back to pages list which will stress your server as well. Just give her the links or previous and next page. But you have to prepare the links first in the show action. In Resource controller actions are abstracted so you don't have to do the repetitive code each time, just do what is specific to each controller action. In this case I need the show action to fetch the next and previous page according to the scope within which the pages controller works. And do that just before rendering the template or to be precise just before responding.




1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class PagesController < ResourceController::Base
        
  before_filter :set_scope
  belongs_to :user

  show do
    before do
      @next_item = @scope.next_to(object).first
      @previous_item = @scope.previous_to(object).first
    end 
  end

  private
  
  ...

end
This was easy, just assign your next and previous variables to the first item returned by the named scopes "next_to" and "previous_to". To be precise, named_scope are not results set (Array) so we need to do ".find(:first)" or ".first" as of Rails 2.1, to just hit the database and fetch the records. I passed 'object' to the named scopes which is a method refers to @page, you can override this method just to find your page the way you want it, say you want to find_by_premalink, for example. The following are how those named scopes were implemented.




1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class Page < ActiveRecord::Base
  named_scope :by_user, lambda {|u| {:conditions => {:user_id => u} } }
  named_scope :pending, lambda {|s| {:conditions => {:published => s} } }
  named_scope :next_to, lambda {|item|
    {
      :limit => 1, 
      :conditions => [ 'id > ?',item.id] ,
      :order => 'id asc'
    }
  }
  
  named_scope :previous_to, lambda {|item|
    {
      :limit => 1, 
      :conditions => ['id < ?', item.id] ,
      :order => 'id desc'
    }
  }
end
Well, that's all well a good, but pretty DRY controllers are not the end of all our sufferings, are they? the views are always the primary cause of migraine in web development, at least they are for me. This resource controller is doing all what I asked it for. But how the views will handle such complex set of nested and or conditional scoping? When I first asked myself this question and start to figure out what may the solutions be. I found my self saying, Hell, no no, I will not make all those conditions and the ever nested loops of if/else to just decide which url routes I shall use in the new and edit forms. But Alhamdulillah, thanks God, there is this most useful piece of code that ever existed in Rails view helpers, excuse the drama but it is really that good, it is the "Urligence" library which is a url helper that helps you generating urls! It is included in Resource Controller, so no need to download. This url helper is not only useful in views it is already used in the controller in redirect_to statements taken place deep inside resource controller, like after create for example it is by default redirect to show action. In this case which show route will it use? In our case we have at least three show routes:
/pages/:id
/user/:user_id/pages/:id
/user/:user_id/pending_pages/:id
The surprise is that Resource Controller will know exactly which route to use according to the context. Actually it does it using Urligence url helper. The helper themselves are too easy. You will have object_url and collection_url, that's it. In Rails resources native tongue: object_url to refer to any member action, and collection_url to refer to any collection action. And of course the HTTP verb or the request method will decide which action to address, like, post to collection_url to create and put to object_url to upate and such.




1
2
3
4
5
6
7
<% form_for :page, @object, :url => object_url, :html => {:method => :put} do |f| %>
   <%= f.text_field :title %>
   <%= submit_tag "Save" %> or <%= link_to "Cancel", object_url %> and go back to page.
<% end %>

<%= link_to("Next", object_url(@next_item)) if @next_item %>
<%= link_to("Previous", object_url(@previous_item)) if @previous_item %>
These snippets from the edit and show templates are pretty much clear and amazing at the same time.

What about controlling the flow of the application. What if you need to change the default flow of the resource controller and make the "delete" action redirect to the next item show page if it exists and to the pages index if there is no next page.




1
2
3
4
5
6
7
8
9
10
11
12
delete do
  before do
    @next_page = @scope.next_to(object).first
  end
  after do
    if @next_page
      redirect_to object_url(@next_page)
    else
      redirect_to collection_url
    end
  end
end
All we need to do is to explicitly add the delete action. I tried to fetch the next item in the current @scope "before" deleting. And "after" deletion I should redirect properly as required.

There are lot more in ResourceController, it lets you customize flash message for success and failure, add responds to methods, respect namespaces automagically and more.

Anyway, that's it regarding how ResourceController and Named Scopes has changed the way I write Rails ActionControllers. for more information refer to the following links:
Posted by at 2:40 AM 2 comments
Subscribe to: Posts (Atom)