Let’s write a Reusable Sidebar Component in Rails 3!

{{{
This is a real world example *how to use “Rails Cells”:https://github.com/apotonick/cells, the popular gem for creating reusable view components*. The following post is clean and all-ages. Let’s just all be friends, no bashing, no f-words today, just a brief HOWTO.

It is *different from what you might have learned from Rails so far*. This doesn’t mean it is _wrong_. Just think about it. If you feel it’s shit, let me know. If you like this approach, I wanna know as well.

h3. What are sidebar elements?

Usually reoccurring components like a “Recent posts” box in a blog application are what we refer to as _sidebar element_.

The exemplary blog application “used in this post(s) can be found on github”:https://github.com/apotonick/cells-blog-example and runs with Rails 3.

So what we do today is a sidebar box. It contains

* links to a certain subset of *recent posts*
* tags to click, *which will filter the post list*

h3. No partials and helpers today

As we’re learning a new paradigm today, we’re not gonna do the traditional approach to implement the box. *Using partials and helpers might do it as well*, but, let’s look forward.

The first step is to generate a cell, which *exposes the same properties as a real controller*.

blog$ rails g cells:cell Posts recent --haml
      create  app/cells/posts_cell.rb
      create  app/cells/posts/recent.html.haml
      create  test/cells/posts_cell_test.rb

Ok, a cell class, a view, a test. Great.

In the second step, I want to render a list of recents posts. My file @app/cells/posts_cell.rb@ looks like this.

class PostsCell < Cell::Base
  def recent
    @posts  = Post.recent
    render
  end

Like a controller.

h3. Cells are controllers.

So what do we do here?

* We *aggregate the items* to display by delegating to the model.
* A call to @#render@ *instructs the cell state to render its view* in @app/cells/posts/recent.html.haml@.

The view is simple as well.

%h3 Recent Posts
    
%ul
  - for p in @posts
    %li #{link_to p.title, p}

* We simply iterate over the posts and *link to the real article*.
* Note that we can *use helpers, logic, everything in cells views*.

As a last step, we *render the cell in the application layout*.

%body
  %h1 The Incredible Cells Blog
      
  #sidebar
    = render_cell :posts, :recent

That’s all for creating a render-only sidebar component. You could have done this with your traditional tools. However, we already got a couple of benefits.

* The cell is *reusable throughout your project* and even between different projects. Just plug the @app/cells/posts@ directory into another app and you’re done. I will post separately about that.
* No controller pollution as the cell computes and renders in its own separate instance.
* We have *better testability* – another post on that one, promised!

h3. Have a tag-cloud widget

One of Cells strength is when it comes to *writing composed widgets*. The tag cloud sitting above the recent posts list *should be a separate cell _state_* – meaning a separate method and a view.

class PostsCell < Cell::Base
  def recent
  # ...
  
  def tag_cloud
    @tags = Post.tag_counts_on(:tags)
    render
  end
end

Not hard to see that we might need another view in @app/cells/posts/tag_cloud.html.haml@.

- tag_cloud(@tags, %w(css1 css2)) do |tag, css_class|
  = link_to tag.name, "?tag=#{tag.name}", :class => css_class

Yeah, we can even use *helpers from other gems*, like the “acts_as_taggable_on”:https://github.com/mbleigh/acts-as-taggable-on helpers. We’re not limited in any way, dude.

To actually _show_ the tag cloud _inside_ our box, let’s *plug the tags into the @recent.haml@ view* for now.

%h3 Recent Posts

= render :state => :tag_cloud

%ul
  - for p in @posts
    %li #{link_to p.title, p}

Wow, we basically can *embed actions within actions* – this is fuc… simply great.

h3. Interaction, babe!

When clicking a tag the “Recent posts” list should update, showing only posts matching that tag. This is something called _interactivity_ – the *cell in your controller view processes user gestures*!

Not a big deal. And, if you think this is breaking MVC: “it is not.”:http://nicksda.apotomo.de/2010/11/rails-misapprehensions-cells-dont-break-mvc/ *This _is_ MVC*.

Let’s see how the cell controller handles that.

class PostsCell < Cell::Base
  def recent
    tag     = params[:tag]
    @posts  = tag ? Post.tagged_with(tag) : Post.recent
    render
  end
  
  def tag_cloud
  # ...
end

The cell controller is exactly *the place where this VC-gluecode should live*. We don’t need work-arounds like presenters or helpers here, we prefer true MVC.

h3. Discussion

We just learned the basic usage of Cells, including
* Generating and *writing simple render-only cells*.
* Composing *nested cells* by calling @render :state@ in cell views.
* Processing user input by using @#params@ in the cell state.

And we got plenty of stuff to check out, like

* Caching cells to *boost your application performance* and simultaneously improving your architecture.
* Writing *functional tests _and_ unit tests for cells* to create reliable components that can be plugged into _any_ controller and just work!
* putting cells into Rails engines to *maximize your modularity*. Imagine real widgets for a blog application shipped as gems and running seamless in your views.

Now, comment! And, hey parents: Writing posts without using swearwords _SUCKS_!
}}}

Advertisement