May 13, 2008
Help! My setup method is not running!
Much to my annoyance (and seemingly, very few other developers), Rails 2.0.2 introduced a bug in ActionController::TestCase — setup methods for tests are not run. It worked in Rails 2.0.1, and broke in Rails 2.0.2. This was fixed in the very next changeset, Revision 8442, but mysteriously it was never rolled out in a 2.0.3. That was five months ago, and given that this basically breaks all tests it’s pretty mysterious that there is still no released version of Rails with this bug fixed.
(NOTE: This was true when written. Now, Rails 2.1 is out, and it includes the fixes. You can use the workarounds below if your project depends on Rails 2.0.2, otherwise I recommend that you simply upgrade to 2.1!)
I’m pretty sure I’m not the only Rails developer who writes tests! So I’m surprised there hasn’t been more of an outcry about this bug. But the Rails dev process has always been rather mysterious to me. So: we need a workaround. I know of two.
Option one: subclass Test::Unit::TestCase
This is what I’ve been doing till now: just going back and writing my tests Rails 1.x style. It’s annoying and clunky: the whole point of ActionController::TestCase in Rails 2.0 was to eliminate all the redundant and non-DRY junk you had to put in your test setup to establish the instance variables @request, @controller, etc. In any case, it looks like this:
class FooControllerTest < Test::Unit::TestCase
fixtures :tasks, :users, :people
def setup
super
@controller = FooController.new
@request = ActionController::TestRequest.new
@response = ActionController::TestResponse.new
# ... your setup code here ...
end
Option two: use a revision from edge with the bug fixed
Normally, I abhor using unreleased software in a production environment. I definitely don’t use EDGE rails in my released software for clients in general … the hassle is too much to maintain with the constant changesets. I’d rather understand and work with stable software, even if that means I’m not one of the cool Rails edgerati: stable software for my customers is the higher priority.
However, in this case I’m making an exception, and I’ve started using revision 8442 of Rails as if it were a released 2.0.3, because this bug just annoys me too much. Installing it is simple. If you’re using frozen Rails in your application (and you should be!), it’s just this at the command-line, in your application root:
$rake rails:freeze:edge REVISION=8442
That should give you a “2.0.3″ that fixes this irritating bug and lets you write your tests and setup the way God intended:
class FooControllerTest < ActionController::TestCase
fixtures :tasks, :users, :people
def setup
super
#... your setup code here ...
end
Don’t forget the call to super, otherwise you’ll clobber the setup method in ActionController::TestCase and your tests won’t work.
Important note for subversion users!!
If you are maintaining your project in subversion, re-freezing your rails code with the above command will hose all of your .svn/ directories under vendor/rails. This will give you a few minutes of headaches as you get things straightened back out. I recommend deleting your old rails freeze first, committing, and then re-freezing:
$svn rm vendor/rails
$svn commit -m "removed old rails version"
$rake rails:freeze:edge REVISION=8442
$svn add vendor/rails
$svn commit -m "froze rails to revision 8442"
I maintain most of my projects in Git, now, so this wasn’t a problem, but I wasn’t thinking when I converted one of my older projects that’s still in svn. It was definitely a headache when the working repository broke, so avoid that if you can.
So there you go. I never thought I’d recommend using unreleased software in production, but just hold your nose and pretend that Rev 8442 is “Rails 2.0.3″ and you’ll probably be fine. I haven’t found any problems with it, myself.
May 11, 2008
The tabbed panel is one of the most powerful GUI tools: an easy, intuitive way to make more information quickly accessible on a screen. This post is a practical walkthrough of implementing a tabbed panel solution in Rails using a GPL’ed plugin. Part 1 will demonstrate a basic tabbed panel implementation.
I’m developing a custom project management application in Rails for one of my clients. They need to organize large number of tasks for each project, and those tasks are divided into three categories: Action Items, Problem Reports, and Work Orders. The three types are pretty parallel in structure, and in fact I implemented them all in one table called Tasks with Single Table Inheritance.
Here’s an example of tables of the three types of tasks.
The goal is to collapse these three tables into a single tabbed panel, with tabs for Action Items, Work Orders, and Problems reports to quickly switch between the three tables.
Why I’m not using AJAX for this
Many Rails developers would implement this by drawing the tabs and using tab clicks to trigger a reload of the task listing, replacing the old listing with the right kind of tasks using AJAX and link_to_remote. This would work nicely, but would fail to satisfy one of my clients other desires: when a project’s page is printed, they would like all three categories of tasks to display on the page, each in its own table. If we actually render all three tables in a tabbed panel, then we can turn all three on with CSS in a stylesheet set to media=”print”, and solve both problems without having to generate a separate page!
The railstabbedpanel plugin
Several plugins exist that can do tabbed panels in Rails. After glancing at a couple, I picked railstabbedpanel, which is simple and looked like it would suit my needs nicely. The documentation is a bit sparse, but the “simple example” was enough to put together the basic task I needed. Download the archive and drop it in as vendor/plugins/railstabbedpanel.
As it turns out, this plugin needs a little hackery to implement a more advanced feature I want, but we’ll get to that in Part 2.
On to the implementation!
I start by loading the tasks I want to display into three instance variables:
in app/controllers/project.rb:
def show
@project = Project.find(params[:id])
@action_items=@project.action_items
@work_orders=@project.work_orders
@problem_reports=@project.problem_reports
end
To render a set of panels with railstabbedpanel, you pass a block to the tabbed_panel function, which creates a “tab context” object for you to use. The tab context object (which I called “tabctx” as per the example docs for railstabbedpanel) has a function, panel, which itself takes a block - the content you want inside the panel, and a parameter, which is the title you want to appear on your tab. There are plenty of other options you can pass, but we won’t need any of them in part one.
Since I’m going to be making three panels, I’ll put that in a partial called _task_panel, to which I’ll pass the tab context object and the list of tasks to display.
in app/views/project/show.html.erb
<% tabbed_panel do |tabctx| %>
<%= render :partial => "task_panel", :locals => {
:tabctx => tabctx,
:tasks => @action_items,
:title => "Action Items"} %>
<%= render :partial => "task_panel", :locals => {
:tabctx => tabctx,
:tasks => @work_orders,
:title => "Work Orders"} %>
<%= render :partial => "task_panel", :locals => {
:tabctx => tabctx,
:tasks => @problem_reports,
:title => "Problem Reports"} %>
<% end %>
in app/views/project/_task_panel.html.erb:
<% tabctx.panel(title) do %>
<table class='listing'>
<%= render :partial => "task_header_row" %>
<%= render :partial => "task", :collection => tasks %>
</table>
<% end %>
The two partials above render a fairly simple array of
s (_task_header_row.html.erb) or | s (_task.html.erb) to fill out the table of information about the task: creation date, due date, responsible party, summary, etc. I’ll spare you the code for those; they’re pretty straightforward.
We also need a little help from CSS to get the display right, as indicated by the documentation for railstabbedpanel:
in public/stylesheets/application.css:
.panel_selected {
display: block;
}
.panel_unselected {
display: none;
}
.tab_selected {
background-color: gray;
}
.tab_unselected {
background-color: white;
}
This works — sort of — we get our tab names, and clicking on them will activate the appropriate panels. But it certainly doesn’t look too good@ With just the suggested formatting, railstabbedpanel outputs our tabs as a stack of list items:
Obviously we’d like to improve on this. Let’s take a look at the HTML generated by the railstabbedpanel plugin:
<div class='tabbed_panel' id='tabbed_panel_124'>
<ul class='tab_container' id='tabbed_panel_124_tabs'>
<li class='panel_tab tab_selected ' id='tabbed_panel_124_126_tab'>
<a href="#" onclick="tabbed_panel_124_125('tabbed_panel_124_126');
return false;">Action Items</a>
</li>
<li class='panel_tab tab_unselected ' id='tabbed_panel_124_127_tab'>
<a href="#" onclick="tabbed_panel_124_125('tabbed_panel_124_127');
return false;">Work Orders</a>
</li>
<li class='panel_tab tab_unselected ' id='tabbed_panel_124_128_tab'>
<a href="#" onclick="tabbed_panel_124_125('tabbed_panel_124_128');
return false;">Problem Reports</a>
</li>
</ul>
<ul class='panel_panels' id='tabbed_panel_124_panels'>
<li class='panel_panel panel_selected ' id='tabbed_panel_124_126_panel'>
<table class='listing' id='action_items'>
... etc ....
So what we have is a ul with the class tab_container, with one li for each tab, each of which has class panel_tab and an additional class for either selected or unselected. The panels themselves are in a second ul of class panel_panels, with list items of class panel_panel. That’s fairly clean semantic markup, and in fact this is one of the reasons I chose railstabbedpanel in the first place.
So, let’s add a couple of basic rules to li.panel_tab to float the tabs next to each other, and some extra space at the top of ul.panel_panels. These few extra rules get us much closer to what we want:
li.panel_tab {
list-style: none;
float: left;
padding: 1em;
margin-right: .5em;
}
ul.panel_panels {
clear: both;
}
The result looks like this, which is a nice little functional tabbed panel:
We could play this game with CSS all day trying to get the tab styling just right and testing it in all the relevant web browsers. But as with everything else, some other developer has already struggled through this before, and with Google I dug up this lovely little reference at Adobe. I applied those styles to the containers determined previously by inspecting the HTML generated by the tabbed panel plugin, and tweaked the colors and fonts a bit to match my client’s application. The resulting CSS looks like this:
/*------------ TABBED PANELS -------------------*/
/* many styles from http://labs.adobe.com/technologies/spry/articles/tabbed_panel/ */
.tabbed_panel {
padding: 0px;
clear: both;
width: 100%; /* IE Hack (hasLayout Bug)*/
}
.panel_panel {
padding: 0.5em 0;
}
.panel_selected {
display: block;
}
.panel_unselected {
display: none;
}
.tab_container {
margin: 0px;
padding: 0px;
}
ul.panel_panels {
clear: both;
border-left: solid 1px #CCC;
border-bottom: solid 1px #CCC;
border-top: solid 1px #999;
border-right: solid 1px #999;
background-color: white;
padding: 10px;
}
li.panel_tab {
position: relative;
top: 1px;
float: left;
padding: 4px 10px;
margin: 0px 3px 0px 0px;
font: bold 1.2em sans-serif;
list-style: none;
border-left: solid 1px #CCC;
border-bottom: solid 1px #999;
border-top: solid 1px #999;
border-right: solid 1px #999;
-moz-user-select: none;
-khtml-user-select: none;
cursor: pointer;
}
li.tab_selected {
background-color: white;
border-bottom: 1px solid white;
}
li.tab_unselected {
background-color: #aac;
}
li.tab_unselected:hover {
background-color: #A77;
}
li.panel_tab a {
color: black;
text-decoration: none;
}
li.panel_tab a:hover {
color: #009;
}
Which results in this much improved tabbed panel:
Testing It
As I mentioned in a previous post, I think it’s important for tutorials to explain not just how to write the code, but how to test it as well, so let’s take a look at some tests that make this happen.
To start with, I need to add one small bit to the HTML to make it easily testable. If the tables that contain the task information each have an id specifying which group of tasks they contain, it will be easier to target them with assert_tag. So, I added such an ID to each table, using the name of the title, converted to lowercase with underscores for spaces, making them ‘action_items’ and so forth:
In app/views/project/_task_panel.html.erb
<table class='listing' id='<%= title.gsub(/ /,'_').downcase %>'>
Now in the test case for the show action on a project, I created a method that can look for a table whose id matches such a title. Inside the same function, I look for rows with an id constructed to match that task’s ID number (this is generated by the _task.html.erb partial, which I didn’t show above). And I look for a cell in that row whose text matches the “summary” field of the task. That should be sufficient to determine that each task of the appropriate type has a row in that table, though you can of course test for plenty more tags and attributes if you like.
In test/functional/project_controller_test.rb:
private
# Test that the table containing rows for all registered tasks are correctly
# rendered. The task type should be sent in underscore format, like
# "action_item" or "work_order"
def test_tasks_table(title,tasks)
id = title.gsub(/ /,'_').downcase
table_tag = {:tag=>'table', :attributes=>{:id=>id}}
assert_tag table_tag
#li containing the appropriate title for the tab
assert_tag( { :tag => 'li',
:attributes => { :class => /panel_tab/ },
:content => /#{Regexp.escape(title)}/ } )
# check for all the task rows
tasks.each do |task|
row_tag = { :tag => 'tr', :ancestor => table_tag,
:attributes => { :id => "task_row_#{task.id}" } }
assert_tag row_tag
assert_tag( { :tag => 'td', :parent => row_tag,
:content => /#{task.summary}/ } )
#...test any other important aspects of the tasks' TR row here...
end
end
And then I simply call this for all three task types in the method that tests the “show” action for a project. In this case, @proj_one contains an instance of the project model pulled from fixtures:
In test/functional/project_controller_test.rb:
def test_show
get :show, :id => @proj_one.id
assert_response :success
assert_template 'show'
#assert the project object
assert_not_nil assigns(:project)
assert assigns(:project).valid?
#confirm that tasks row summaries are listed correctly
test_tasks_table("Action Items",@proj_one.action_items)
test_tasks_table("Work Orders",@proj_one.work_orders)
test_tasks_table("Problem Reports",@proj_one.problem_reports)
end
Okay, that works great, now we’ve confirmed that the tables are output correctly. Let’s move on and test the tabs themselves. As we saw above when examining the HTML, the tabs are a set of li.panel_tabs inside a ul.tab_container. The whole thing is contained inside a div.tabbed_panel. We want to confirm that each tab contains text matching the appropriate title. So, one quick helper method an three lines added to our test_show method will test these for us:
Added to test/functional/project_controller_test.rb
def test_show
...
#confirm that the three tabs exist
assert_panel_tab "Action Items"
assert_panel_tab "Work Orders"
assert_panel_tab "Problem Reports"
end
def assert_panel_tab title
ancestor = {:tag => 'div', :attributes => {:class => "tabbed_panel" }}
parent = {:tag => 'ul', :attributes => {:class => "tab_container" }}
assert_tag({:tag => 'li',
:attributes => {:class => /panel_tab/},
:parent => parent,
:ancestor => ancestor,
:content => /#{title}/
})
end
Note that I’m not testing :class => "panel_tab" for the tabs, but using match instead of a string. This is because the actual full class is going to be either class="panel_tab selected" or class="panel_tab unselected", and we want to match the tag in either case.
What’s next?
That’s it for this installment. In Part 2, I’ll explain how to endow the tabs with memory, so that if you click on, say, Problem Reports, and then leave the page, that same tab will still be in front when you come back. In Part 3, I’ll look at some more advanced styling, including making all three tables show nicely on the printout.
April 30, 2008
Which book should a beginning rails developer choose?
I want to plug the book I learned Rails from: RailsSpace by Michael Hartl and Aurelius Prochazka. Most people in the rails community recommend Agile Web Development, but I’m going to disagree. Strongly. I think most people who recommend AWD aren’t familiar with RailsSpace, and having studied from both I think RailsSpace is the better book by far.
I tried AWD first, and found that while it’s a decent introduction to Rails, it does a poor job of explaining basic Ruby concepts to programmers who are not used to it. (I was coming to RoR from a background in PHP, Java, and Javascript). As one example, it used the Ruby :symbol syntax consistently, without ever explaining just what the heck that was. I went through a couple of chapters copying down code and making minor modifications trial-and-error style, but I lacked a thorough understanding of what was going on because I was coding in an unknown language. I am used to learning languages very quickly, and AWD just wasn’t delivering.
When it just got too frustrating, I tried RailsSpace. I had both books available but tried AWD first because the title of RS suggested to me that it was for experienced rails developers looking specifically to making social networks. Not so: it starts from the beginning, for new developers who have never touched Ruby before, and is much more thorough in its explanations. Every time a new construct or concept gets used in the course of an example, the authors set up a nicely formatted sidebar explaining that concept with its own examples. This gives you the explanation you need to avoid getting lost, without interrupting the flow of the main narrative. In the first two chapters it answered all the confusions that I had suffered while reading AWD, and I felt like I gained a solid understanding of Ruby fundamentals as well as Rails technique.
Yes, the example they build is a social network, but I felt like that was only as a functional example, analogous to the shopping cart AWD uses. The techniques are expandable to any site you’d want to build, and because you understand them better with RS you’ll be able to apply them to other types of sites more easily.
Though fewer people are aware of it, I think it’s really a better book for the Rails beginner.
A note: the current version of RS uses Rails 1.2.3 instead of the newer Rails 2.x. However, I actually think that’s a good place for a beginner to start: in my opinion, most of the stuff changed or added in Rails 2 is great for a developer who knows rails, but actually harder for a beginner who’s never used Ruby before.
April 30, 2008
My plan is to use this space to post challenges I’ve faced (or am facing) in the course of Ruby on Rails development, and my solutions to them, when found. I have switched mostly to Ruby on Rails for web applications development these days. While I enjoy the power and capability of the system, I find that the documentation and community resources still leave something to be desired, so this is my way of contributing back to the community.
When posting an example or technique, it’s my intention to include both the code and the tests I wrote for it. In my experience many of the otherwise lovely Rails blogs out (e.g. the indispensible RailsCasts by Ryan Bates) there rarely include tests, and often it’s not obvious how to test a feature correctly. The close integration of testing is, in my opinion, one of the most enticing features of Rails as a webdev framework. So I’d love to see testing become a more integral part of community technique examples and tutorials.
Subscribe