A Post Entitled Moving in
After talking with Chris, I decided to move my blog posts from the Upstate Ruby Brigade site to a home of my own (on tumblr). No offense intended to anyone in the Greenville ruby community… just certain factors make it much more worth my while to have my thoughts associated with, well, me.
I think I’ve got all the posts rebuilt with the appropriate dates so (re)enjoy!
Edit — a note on styles
Just in case you’re interested, I’ve stolen a page from the guys at thoughtbot for styling code blocks. After looking under the hood of their blog with cdmwebs I rooted out the javascript-based syntax highlighting they used from softwaremaniacs. The exceptionally nice things about softwaremaniac’s highlight.js are
- You only need pre and code tags (no classes) so you can use it with something like Markdown.
- You can select the languages you use and they’ll custom build you a packed js.
- Since you picked the languages you like, you don’t have to do anything with the markup to tell the js which language to highlight.
- There is a suite of css files shipped with your packed js so you don’t have to pick your own color themes. You can use, modify, or imitate theirs.
For my part I’ve gone with the Sunburst theme because it’s fairly close to the coloring scheme that Ryan Bates uses with Railscast. I personally find the color scheme easy on the eyes and there’s something to be said for breeding familiarity.
On the whole the site is a stock theme from tumblr. To get the syntax highlighting I
- Stuck the unzipped highlight package into my github account
- Customized the tumblr layout by adding a script tag reference to the raw highlight.pack.js file from my github source.
- Added a stylesheet reference to the sunburst.css
- Added a two-line script to activate the syntax highlighting on page load
A Post Entitled Time to clean your filters
The Problem
What do you do when your end user needs to filter? In some cases the answer is easy: provide a custom method for the sort criteria. For example, when you know that your end user wants to know “my jobs” as distinct from “all jobs” a custom ‘mine’ method might work just fine. Don’t worry that the custom routes are not RESTful; they are, they are just not the default Rails notion of REST. That’s okay; Rails is not necessarily right.
The filtering that I run into is rarely that simple. Right or wrong end users tend to think more options is better. In the context of filtering that means they often want to filter by a combination of ad-hoc attribute values. Clearly a single custom method won’t work there because you can’t out guess the combination and permutations that a given user might want to use.
Sorting and paging further complicate the issue. Even when you can pick the ‘right’ values the user may want them back in the ‘right’ order. Paging is just a small wrinkle on top of that but yet another piece to layer in.
The Context
The most frequent context for the type of filtering/sorting/paging that I’m talking about is when the user is presented with a list of things that needs to be pared down and organized before the user can make any sense out of it. Maybe they’re looking at a list of members in a club or a set of subscriptions or a bunch of invoices. Whatever the case, you’ve given them a set of things to review in the order you thought best but it doesn’t make sense to them. Rather than haggle over who’s right (you… of course!), you decide to give them a filtering pane and some click-to-sort headers in the grid. Great. The UI is done. But where does it all go? Where do you send the values?
More often than not, this context leads me right back to where it started. You began presenting the user a list that naturally flowed through the #index action of your controller. Why should the filtered or sorted or paged list be any different? It’s still just a list, isn’t it?
The Solution
In my mind the answer to that question is yes. A filtered list is still just a list so if the original list came from the index action of my controller then the filtered version of it should come that way, too.
The way that I’ve settled on implementing most of these scenarios lately is through a combination of named scopes, anonymous scopes, and some recommendations from Uncle Bob’s Clean Code.
Scopes
Named scopes and anonymous scopes are hardly new territory. Named scopes came into Rails at version 2.1 courtesy of a very popular plugin. The idea behind named scopes, if you’re not familiar with them, is that you create a method that ‘scopes’ a query against your ActiveRecord-based model. This is really handy if you have a scope like ‘current’ or ‘active’ that you can use over and over in your application; you just declare it once on the class and use it wherever you need it.
class Order < ActiveRecord::Base
named_scope :recent, {:limit=>10, :order=>'id DESC'}
named_scope :since, lambda{|date| {:conditions=>['created_at > ?', date]}}
end
Order.recent
#=> [...up to 10 orders]
Order.since(1.month.ago)
#=> [... all orders created in the last month ...]Just as a quick refresher in case you’re not using named scopes (as you should be!), you create a named scope on a class by calling the named_scope method in the class definition. The first parameter to the method is the name of the ‘scope’ and the second argument is either a hash of find options or a lambda that returns a hash of find options.
Anonymous scopes are pretty much the same thing. Really, the only difference is that named scopes are not saved against the model. You create them only where you need them and let the Garbage Collector have them when you are done with them.
Order.scoped( {:limit=>10, :order=>'id DESC'} )
#=> same results as Order.recentWhat makes named and anonymous scopes so useful for the type of ad hoc filtering and sorting that we’re considering is that you can chain them. By chaining named and anonymous scope calls you build up the query conditions. Thus you do not have to worry too much about the what combination of filering, sorting, and paging the user might want, you simply accumulate them. The query is not actually run against the database until you first try to use the data.
Order.recent.since(1.week.ago)
#=> Up to ten orders from the last weekClean code
So what does clean code have to do with this? In the third chapter of his 2009 book by the same name, Bob Martin makes an excellent case for code that’s organized into a series of very tiny, top-down methods. This, again, is not really new territory for most developers. Martin just pushes it to an end that I’d not really considered before and the discussion of the top-down organization somehow clicked with me in a way that it had not before.
The clean code approach to the filtering/sorting/paging problem would look at the demonstration in Ryan Bates’ Railscast* and say it’s too big. The filtering should be refactored into it’s own method, so that the index can focus solely on getting the right type of view to render out the values. That filtering method should be broken down into a series of smaller methods, each of which performs one specific type of filtering/sorting/paging.
class ProductsController < ApplicationController
def index
filter_products
sort_products
respond_to do |format|
format.html # render index.html.erb
format.xml { render :xml=>@products.to_xml }
end
end
private
def filter_products
initialize_scope
filter_by_name
filter_by_category
filter_by_price
end
def initialize_scope
@products = Product.scoped {}
end
def filter_by_name
return if params[:name].blank?
@products = @products.scoped :conditions=>[ 'name LIKE ?', "#{params[:name]}%" ]
end
def filter_by_price
filter_by_minimum_price unless params[:minimum_price].blank?
filter_by_maximum_price unless params[:maximum_price].blank?
end
def filter_by_minimum_price
return if params[:minimum_price].blank?
@products = @products.scoped :conditions=>['price < ?', params[:minimum_price]]
end
def filter_by_maximum_price
return if params[:maximum_price].blank?
@products = @products.scoped :conditions=>['price < ?', params[:maxiumum_price]]
end
def filter_by_category
return if params[:category_id].blank?
@products = @products.scoped, :conditions=>{:category_id=>params[:category_id]}
end
endConclusion
Okay, so nothing too earth-shattering if you’ve been deep into Rails for a while but hopefully a help if you’re a relative novice. Have we gained anything? Sure, we’ve gained a few things. The use of named and anonymous scopes has greatly simplified our ability to respond to the user who desires to do ad hoc filtering against our data. They also make sorting and paging relatively simple — just add an appropriate scope that users :order, :limit, and :offset appropriately and you can sort or page any of the target result sets the user could dream up. Just as importantly the top-down organization of very tiny (generally private) methods makes the top-most levels of the program (the index and initial filter method) read somewhat like a newspaper article: the headline (index) describes the main event, the first paragraph (#filter) provides the most important details, and the subsequent ‘paragraphs’ (lower methods in the chain) progressively reveal the implementation details. We have a simple solution to a problem with many combinations that should be easy to read and maintain in the future.
A side benefit
This approach saved me a lot of work earlier today. I had a rather inelegant solution to a particular problem in which I needed to filter and sort a list of members. The twist was that I needed the exact same sorting and filtering for two completely different contexts with very different views representing the results. The initial approach was to send the filtering request to the #index method of the MembersController; it seemed like a natural place to organize the member-specific logic. The method chose the view for rendering the results based on the ‘commit’ value (the name of the submit button). Unfortunately, a certain “non-modern browser” was not supplying the commit value. Ugh!
How did we keep it DRY? Simple. Since the code was organized with this top-down approach I simply extracted the methods from the controller class into a module and included the module in the two controllers that needed the search logic. The big benefit was that I only needed to move the lower-level functions; the higher functions (e.g., #index) remained in place. Actually the #index method was simplified since it could now focus on rendering the list of Members in only one way; the other controller picked up the single call to filter and rendered the results as it needed to. Simple code, simple refactoring, DRY solution.
Anyone have a glass of water?
* No offense intended to Ryan or his Railscast, which was focused on the mechanics of using anonymous scopes and immensely helpful in helping me get a handle on how to use them.
A Post Entitled Globbing up javascript
The Motivation
When you first started with Ruby on Rails you were probably intrigued by the simplicity of adding AJAX to your applications by simply including a line like this:
<%= javascript_include_tag :defaults %>It was short, concise, and invisible. All the Rails “magic” took over and you didn’t need to worry much about which files were included because everything just worked.
Then you ran into jquery. Either because you did not want to be outdone by the “cool kids” or you really were motivated by the clean separation between view and code even in the browser you bought in. Then you discovered a few nifty plugins for paging and ajax forms. And there was a nifty auto-complete that you just had to have. Before you knew it, there was more javascript_include_tag logic in your application layout than anything else.
Compounding the Issue
For me it really started with the ExtJs library. Once we bought into it at work we quickly realized that we were now developing a client-server app over http and that our javascript views needed to be just as neatly organized as our html views would have otherwise been. We developed a scheme for organize our javascript views that looked remarkably like the Rails organization:
public
javascripts
my_company
components
...files...
views
area1
...files...
area2
...files...
The good news for us was that the code was pretty well organized. We know where to find a file that needs some love when things go awry. The bad news is that means we also need to write a lot of includes. Too many includes to keep up with really. There was also the not-so-minor inconvenience of working hard on a new view, refreshing the browser, and throwing javascript errors (or worse, silently failing) because the new file had not been included. Argh!
Glob to the rescue
This is where ‘globbing’ came in very handy. If you are not familiar with it, glob is a class method of Dir that searches your directory tree for files that match a pattern that you supply. The pattern for the file names is similar to but not quite the same as regex. As the documentation explains, it’s closer to the shell’s glob.
For this problem, though, that’s all we need. The pattern matching matches literals as you might expect and it includes a pattern for recursing subdirectories (‘**’). That fits perfectly well with our problem since what we want to do is find all the javascript files in subfolders of /public/javascripts.
Of course, there’s a catch. glob begins it’s work in the current directory and it returns file names relative to that directory. The javascript_include_tag, however, expects file references to be relative to /public/javascripts. That leaves you with two options: change working directories or alter the file paths. We chose the former path. The results looked like this:
<% javascript_include_tag
*(Dir.chdir( File.join(Rails.root, 'public', 'javascripts') {
Dir.glob("my_company/**/*.js").sort
}
) %>Okay, so what’s going on there??? Simple. First, we change directory (Dir.chdir) to start our directory globbing relative to the javascripts folder. By using the block-form of chdir we allow Ruby to reset the working directory for us when the block exits. Within the block we simply invoke Dir.glob asking for all the javascript files (“*.js”) in subdirectories of the “my_company” directory. The great thing here is that glob really does recurse the subdirectories so we can add as many organizational layers as is necessary.
Don’t miss the splat (‘*’) and parentheses around all that. It’s pretty important. Dir.glob is going to return an array of strings describing file paths. javascript_include_tag, however, is still looking for a list of arguments. The splat comes in handy here, expanding the array.
The Net Result
The net result of all that is a single javascript_include_tag statement that includes all of the nested javascript files we’ve created. Even better, since they are included together in a single line when we can turn on javascript caching they will be compressed into one js bundle before being delivered to the client. Even better than that, we can drop in new files, reorganize existing files, and drop out that crummy javascript file we always hated without ever having to re-build the list of includes.
A Post Entitled Fixing the Broken Pipes
Why do we need the plumber?
If you’re like me you might slip into a comfort zone and not keep up with all the updates to gems and plugins, especially since github has taken plugin/gem development and forking viral. Usually that’s not much of a problem. Unless, of course, the change is to the gem package manager itself.
I’m not sure exactly what changed. What I know is that any time I tried to do a ‘(sudo) gem install my-cool-gem’ it failed with an error that looked like this
Bulk updating Gem source index for: http://gems.rubyforge.org/
Bulk updating Gem source index for: http://gems.github.org/
ERROR: While executing gem ... (Gem::RemoteFetcher::FetchError)
Errno::EPIPE: Broken pipe reading http://gems.rubyforge.org/gems/...some-poor-gem.gem
As best as google has been able to help me find the problem lay in the the increasingly large number of gems available. The large, uncompressed source of gems times out the connection. Fortunately that appears to be fixed in the latest version of rubygems. Version 1.3.0 was released yesterday. But now you’ve got a chicken-and-egg problem if you have relied on gems to update itself — the Broken Pipe problem prevents you from getting the version that doesn’t have the Broken Pipe problem.
Installing the gem locally
The simple answer to the question is to install the gem from a local source rather than a remote source. It works the same as the tried and true “gem install my-cool-gem” with just one extra step. Here’s what I did specifically to fix the issue with the gem package manager.
- Navigate over to the rubygems download page at rubyforge.
- Download the latest rubygems-update gem (currently rubygems-update-1.3.0.gem)
- Move the gem somewhere handy in case you want to install it again.
Personally I created a Gems subfolder and moved the gem from ~/Desktop to ~/Gems. - Install the gem locally using a locally named source:
sudo gem install rubygems-update -n ~/Gems - Once the gem update is installed you still have one more step! (Emphasis for my own needs — I keep forgetting this). From the command line:
update_rubygems
Once I updated to rubygems v 1.3.0 the Broken Pipe Problem disappeared on my Ubuntu box. Hope the same is true for you!
A Post Entitled STI Factory revisited
Single Table Inheritance (STI) Revisited
I wrote about Single Table Inheritance (STI) in Rails several months ago. STI is a simple design pattern in which multiple subclasses are stored in a single database table and distinguished by a discriminator column. Rails makes this easy to implement by automatically mapping a column named ‘type’ as the discriminator column (aka, inheritance_column). Of course you can override the name of the discriminator column and I often must do so in practice; most of the applications of STI that I use allow the end-user to select the value for the subclass and trying to render the list of subclasses for the :type column leads to rendering issues.
Allowing the end user to select the subclass has one other problem — your controller must somehow be aware of the use of STI. Why? Well, ActiveRecord::Base simply does not allow you to assign a value to the inheritance column. It keeps things “type safe” by setting the value of the inheritance column itself. As a result your controller needs to have some sort of STI-awareness built in so that the user can send back a value for the inheritance_column and the controller can use that value for building or creating an instance of that type.
Instant STI Awareness
This need for STI-awareness is prevalent enough that I offered an attempt at creating it in a lib/plugin in the earlier post. The solution focuses on the model, rather than the controller, so that the controller can remain blissfully unaware (some would say decoupled from) the implementation of the model. Unfortunately that earlier code stunk and I’ve been revisiting it as a part of getting ready for my talk at the South Carolina Ruby Conference.
One of the weak points of the earlier code was the shaky way it tried to work around infinite loops. That was what brought me back to the code. I was looking for a good example of alias_method_chain and realized that it was the solution to the recursion problem.
The basic logic behind the plugin/lib is simple. We need to override the #new method to:
- Check for the presence of the inheritance column in the attributes supplied to the new method.
- If the inheritance column is found, check to see if the its value is the name of a valid subclass.
- If a valid subclass has been requested then call new on the subclass and pass the original args less the inheritance_column.
- If a valid subclass was not requested then call new on the superclass.
alias_method_chain
Phrasing the problem in the right way is often the key to unlocking the problem. As steps 3 and 4 above suggest we really want to have a way to hide the inherited #new function, override its functionality, and then invoke that original method. That’s what alias_method_chain is all about.
alias_method_chain is an extension of Module added by Rails. The intention of the method is to allow you to wrap an existing method with your new functionality. For example, assume that you have a method called foo that you want to extend by some functionality known as bar. You can think of the original method as “foo without bar” and the new functionality as “foo with bar”. For the sake of the other developers with whom you work (think: the world!) you would want to use some aliasing so that others could make use of your fabulous new bar-ology without having to change their code. It would probably look something like this:
alias_method :foo_without_bar, :foo
alias_method :foo, :foo_with_barAnd that is exactly what alias_method_chain does, only with a much simpler syntax:
alias_method_chain :foo, :barPlacement of alias_method_chain calls is very important. The call must be made after both your new “foo with bar” concept has been added to the class and the original “foo” has been realized. This can get tricky when you are trying to wrap class-level functionality.
Improved STI Factory
Here’s a revised version of the STI factory code. The recursion problem is gone thanks to alias_method_chain and, as a side benefit, STI tables get a new subclass_names method that can be used for building select options.
module Koinonia
module StiFactory
def self.included(base)
base.extend Koinonia::StiFactory::ClassMethods
end
module ClassMethods
def has_sti_factory
extend Koinonia::StiFactory::StiClassMethods
class << self
alias_method_chain :new, :factory unless method_defined?(:new_without_factor)
end
end
end
module StiClassMethods
def subclass_names
subclasses.map(&:name).push(self.name)
end
def new_with_factory(*args)
options = args.last.is_a?(Hash) ? args.pop : {}
klass_name = options.delete(self.inheritance_column.to_sym) || self.name
klass = self.subclass_names.include?(klass_name) ? klass_name.constantize : self
klass.new_without_factory(*args.push(options))
end
end
end
endJust to explain what’s going on a little bit… when Koinonia::StiFactory is included into ARec::Base by init.rb it adds a class-level method to ARec::Base called ‘has_sti_factory’. That method is the one that you’d add to an STI class to hook in the factory. When invoked, that method extends the class by adding two methods: new_with_factory that is responsible for checking the supplied attributes and invoking the appropriate new_without_factory, and subclass_names that supplies the names of the known subclasses. With that in place you can now do this:
class Vehicle < ActiveRecord::Base
self.inheritance_column = 'vehicle_type'
has_sti_factory
end
class Car < Vehicle; end
class Truck < Vehicle; end
class MonsterTruck < Truck; end
Vehicle.new
=> #<Vehicle id: nil, vehicle_type: nil, ...>
Vehicle.new :vehicle_type => 'Truck'
=> <Truck id: nil, vehicle_type: 'Truck', ...>
Vehicle.new :vehicle_type => 'MonsterTruck'
=> #<MonsterTruck id: nil, vehicle_type: 'MonsterTruck', ...>Oh, yeah, I’ve tried to play nice with all the cool kids and wrapped this up as a plugin that you can download from github.
A Post
Recently I’ve been using the great Rails 2.1 addition called named_scope to help simplify the process of building queries with meaningful names. Certainly you could do something similar by creating a custom method, but as I wrote earlier, the advantage of named_scope is that the scopes are composable: you can chain them together to build ever more powerful queries.
That’s why I’ve been really frustrated trying to get named scopes to work with the :include option. In one scenario I have been trying to sort a collection by a field that exists in an included table. If I were doing freight-forwarding the models involved look something like this.
class Customer < ActiveRecord::Base
has_many :product_offerings
has_many :products, :through=>:product_offerings
end
class Product
has_many :product_offerings
end
class ProductOffering
belongs_to :customer
belongs_to :product
named_scope :by_name, :include=>:product, :order=>:name
named_scope :for_customers, lambda{|customer_ids| {:conditions=>{:customer_id=>customer_ids}}}
end
The objective I have in mind is to build a named_scope that allows me to list all the products for a particular customer alphabetically by the name of the product so each customer can check their inventory. In the day and age where holding companies are involved an individual user may be authorized for several companies and thus want to be able to get a unified inventory list for all the companies for whom he works. That’s where the second named_scope comes into play. I’d like to be able to do this:
# all the product offerings listed by product name
ProductOffering.by_name
# all the product offerings for a set of customers
ProductOffering.for_customers([1, 2, 3])
# all the product offerings by name for a user's companies
ProductOffering.by_name.for_customers(@current_user.customer_ids)
But it doesn’t work. For some reason the :include option seems to get dropped and I end up getting SQL errors reporting an unknown column name. I’ve found one stray comment that suggests that you may be able to fix the issue by adding the conditions necessary to make the SQL join work. That is we could expand the named_scope to something like
named_scope :by_name, :include=>:product, :order=>:name, :conditions=>["products.id = product_offerings.product_id"]
That’s ugly. Really ugly. It also pushes perilously close to letting ProductOffering peek into Product too much. If you begin to go that route be careful because you’ll be on the slippery slope of a brittle solution that won’t survive refactoring.
The simple solution is to bypass :include in favor of :join. I don’t understand why :join works more reliably but I’m sure the answer is down there in the source code if you want to dig around. I suspect that the answer lies in the way that Rails 2.1 breaks joins into two distinct fetches now in order to reduce the cost of spinning up redundant ActiveRecord instances (see the Relationship Optimised Eager Loading discussion.). Whatever the case, the workable, concise solution looks like this:
named_scope :by_name, :joins=>:product, :order=>:name
If you already need to include conditions on the join table you can probably continue along as you normally would. In this situation the only requirement on the join table is that the IDs match so I prefer the concise solution.
A Post Entitled New in Rails 2.1: Timestamped migrations
What was wrong with migrations?
If you’ve been part of any development team that was larger than the “Army of One” you’ve probably run into an issue with migrations. It’s happened to me a few times: one member of the teams goes head-down on some problem and it takes longer than expected. Not wanting to check in ‘broken” code the patch builds up for a while… and so do the migrations to fix db issues. Finally ready, the change gets checked in and … poof… What worked no longer works. Why?
While Mr. Fix-It was head down the trunk was updated with other migrations. But these migrations had overlapping numbers so when they merged into the code base it was unpredictable which ones would be run on any given system. To be clear, the migrations will be run in a very definitie order. They’re run in alphanumeric order, but only one migration of a specific ‘version’ will be executed. As a result, which migrations are run on your system depends on how many you’d already checked out and run and the alphabetical naming of each script. Now it’s up to you and your team to rename all the migrations, backing them out one by one and adding them back to make sure all the database changes are applied appropriately. Yikes!
Enter Sandman
Disclaimer: I’ve only heard ‘Sandman’ when certain closers enter baseball games but I thought someone would appreciate the reference
The new timestamped migrations may put all these issues to rest. Instead of prefixing the migrations with 001, 002, 003, etc the prefix will now be a timestamp. So, the result of running a ‘script/generate scaffod MyObject attribute1:string attribute2:integer’ will be a file with a name like 20080601214508_create_my_object. The likelihood that you and a teammate create a migration at the exact same time is pretty small so the ‘level collisions’ are almost surely a thing of the past.
Tracking revisions, not the version
Even better, though, is that the schema_info table will now track revisions, not only the latest version. That is, every migration that is run via rake db:migrate will be recorded in the database. As a result, whenever Mr. Fix-It decides to enlighten the rest of the team with his update, a rake db:migrate will be able to identify the individual migrations that have not been run whether they were on Mr. Fix-It’s machine (when he finally updates from trunk/master) or on a teammates’ machine (when the patch is loaded).
Even better, there are new rake db:migrate:up and rake db:migrate:down commands. These commands accept an individual migration ‘version’ (the time stamp) and either run it (up) or back it out (down). Remember that table that you created and decided you’d overengineered? Now it’s a lot easier to back that one out.
Could it get even better?
Yes, it could get better. Those of you who’ve read The Rails Way (Obie Fernandez, Addison-Wesley Professional Series, 2007) may have come across a recommendation to accumulate migration changes until they are pushed to production. That is, rather than create three migrations for a table and some additional fields while the table is in development, there is a recommendation to have one create script that gets updated until it’s pushed to production. I’ve tried this on a couple of apps and really liked the approach because it cuts down on the ‘noise’ in the migration collections. I’m willing to accept the argument that migrations are not really necessary for tracking database changes until they change something beyond development.
What could be even better that the current implementation of the timestamped migration would be if it could detect these changes in the migration files. It should be possible to check the creation and update times of the files to see if they’ve been updated and then validate the updated time in the migrations db. This particular idea has some drawbacks, particularly if a production migration were ever touched accidentally.
A Post Entitled New in Rails 2.1: named_scope
Rails 2.1 Released
If you haven’t heard, the release of Rails 2.1 was announced during core member Jeremy Kemper’s keynote Saturday morning (but it didn’t actually get released until around 2am the next morning).
named_scope
One of my favorite additions to the framework is the absorption of the has_finder plugin into the framework. If you’ve used has_finder in the past the only thing you’ll need to do in order to ‘go native’ with it in your application is replace the ‘has_finder’ invocations with ‘named_scope’. If you are not familiar with has_finder, it gives you the ability to declare custom finders in a concise, semantically meaningful way. For example:
class Task < ActiveRecord::Base
named_scope :incomplete, :conditions=>{:completed_at=>nil}
endIn the Grade class above, we’ve used named scope to add a class-level finder called ‘incomplete’ that will perform the equivalent of this:
Task.find(:all, :conditions=>{:completed_at=>nil})Great, so now I can write Task.incomplete and get a list of the incomplete tasks. But so what? I could have written a class-level method myself. Is this anything more than syntactic sugar? Yes!
named_scopes can combine
The real beauty of named scopes is that they chain together. Well crafted named_scopes are fine-grained pieces of find parameters that have clear purposes and meaninful names. Consider these:
class Task < ActiveRecord::Base
named_scope :incomplete, :conditions=>{:completed_at=>nil}
named_scope :past_due, lambda{ {:conditions=>['due_on < ?', Date.today]}}
named_scope :due_today, lambda{ {:conditions=>['due_on = ?', Date.today]}}
endTask.incomplete.past_due is the same as Task.find(:all, :conditions=>[‘completed_at is NULL and due_on < ?’, Date.today]
Sweet. The chaining of the named_scopes means that you can create really nice ‘sentences’ in your Rails code that is clear and easy to read.
named_scopes play nicely with association proxies
Even better, the named_scopes work through association proxies as well. Without getting into the details too much, assume that your User class has_many Tasks. Now, your boss wants you to help him through a commons scenario. “Ryan, how can I figure out how many tasks that slacker Chris has let slide. Easy.
@chris = User.find_by_name('chris')
@chris.tasks.incomplete.past_dueIn the first place I used this, the code became a lot easier to read. I added a named_scope that at first did not make a lot of sense: it added a model-related scope to the find. In this case it helped the code because I was normally accessing the data through another ‘owner’ and this named_scope helped me chain in finer focus.
@grades ||= @student.unreported_grades.find(:all, :conditions=>{:subject_id=>params[:subject_id]})
@grades ||= @student.grades.unreported.for_subject(params[:subject_id])The commented code is the original version that used a (now deprecated) class-level method. Passing the find conditions there worked but it was a little ugly. The named_scope version is both clearer and easier to maintian.
A Post Entitled 5 Tips for ActiveResource
The first couple of tips have an indrect impact on ActiveResource. Still, they are worth keeping in mind because they simplify the data with which ActiveResource deals.
Tip 1: Use delegate and :method for encapsulation
If your crash course in Ruby involved reading the Agile book, then the delegate method may be new to you. Delegate is a class-level command that allows you to pass certain method calls on to an associated model. For example, if you have a highly-factored address book you might have a pair of models like this:
class Address < ActiveRecord::Base
belongs_to :zip_code
end
class ZipCode < ActiveRecord::Base
has_many :addresses
endThat’s a model with some theoretical purity… but in practice it’s cumbersome. You really want to deal with an address that has all the information you’d like to render (street, city, state, zip) in on model. Atleast it should feel that way. That’s precisely where the delegate command comes into play.
class Address < ActiveRecord::Base
belongs_to :zip_code
delegate :city, :state, :zip, :to=>:zip_code
delegate 'city=', 'state=', 'zip=', :to=>:zip_code
endModeled as shown above you can ask an address for it’s city and the address will pass the request on to the zip_code object to which it belongs, retrieve the answer, and return it to you. (It’s taking advantage of the fact that Rails is doing some method_missing magic to provide getters and setters for your attributes). That level of encapsulation will become increasingly important when you begin to use ActiveResource heavily. In many cases you may want to return only a few fields from an associated model and, as in the example above, you do not want or need to reveal how you’ve organized your data to the outside world.
The final piece to the puzzle with respect to ActiveResource will be making sure you use the :method parameter when you serialize the delegating object to xml.
addresses_controler.rb
...
def show
@address = Address.find(params[:id], :include=>:zip_code)
respond_to do |format|
format.html # show.html.erb
format.xml { render :xml => @address.to_xml(:methods=>[:city, :state, :zip])
end
end
...As shown, the call to @address.to_xml tries to include the results of calling the city, state, and zip getter methods on address. The delegate command causes the Address object to pass that request on to the association ZipCode object and the results are returned and placed into the xml envelope as if they were attributes of the address (which they are, indirectly). The application that’s consuming all this through ActiveResource remains blissfully unaware of your modeling nirvana. It simply receives some nicely formatted xml along the lines of this:
<home-address>
<id type="integer">1</id>
<street>123 Main St.</street>
<city>Anytown</city>
<state>XX</state>
<zip>12345</zip>
</home-address>Tip 2: Clean up the delgation you just learned to keep the code clean and clear
If you start maximizing your use of delegate your code can get untidy especially since delegate introduces some duplication when you’re dealing with attribute accessors. If we keep in mind that class declarations are still Ruby scripts then we can clean the attribute accessor delegation pretty easily while making the intent very clear.
class Address < ActiveRecord::Base
belongs_to :zip_code
[:city, :state, :zip].each do |delegated_accessor|
delegate "#{delegated_accessor}", "#{delegated_accessor}=", :to=>:zip_code
end
endOn to some tips with more direct bearing on ActiveResource itself.
Tip 3: Use AppConfig to get your site information out of the class file!
The Core did a great job modeling ActiceResource along the lines of ActiveRecord so that using ActiveResource feels very natural to any Rails programmer. But it’s also left me stumped as to why there is no equivalent to /config/databases.yml. I suppose that in some cases you will be using a well-known, established, public REST interface but I’m finding ActiveResource to be a very natural way to develop ‘sub-applications’ that can be shared to create a larger application. Because of that I need to be able to have different site information for development, test, and production. Clearly some configuration is needed.
Even though I shudder at the thoughts that a name like ‘AppConfig’ brings to mind, it’s a great part of the solution to this problem. If you’re not familiar with it, AppConfig allows you to provide a yaml config files for global (/config/app_config.yml) and environment-specific (e.g., /config/environments/development.yml) configuration. The plugin reads these config files, merges inforamtion as necessary, and provides all the options as class-level attributes of the AppConfig class.
sites:
addressbook: http://localhost:3001
financials:
url: http://localhost:3002
username: money
password: talksThe yaml above shows two different types of configuration that would be useful for ActiveResource, organized together under a ‘sites’ attribute. The first one (addressbook) is the way I started before I ran into an application that needed http basic authentication. The site info consists only of the url. The second one (financials) came out of the latter need. A quick extension of ActiveResource causes these to spring into action.
class ActiveResource::Base
protected
def self.establish_site_connection(site_id)
raise(ArgumentError, "#{site_id} is not defined for #{RAILS_ENV}") unless AppConfig.sites.respond_to?(site_id)
site_info = AppConfig.sites.send(site_id)
return site_info.respond_to?(:url) ? site_with_basic_auth_info(site_info) : site_info
end
def self.site_with_basic_auth_info(site_info)
site = URI.parse(site_info.url)
site.userinfo = "#{site_info.username}:#{site_info.password}"
return site.to_s
end
endI’ve been dropping the code above into /lib/core_ext/active_resource_extension.rb. The first method (establish_site_connection) is meant to emulate ActiveRecord::Base#establish_database_connection. It accepts a site id in the form of a symbol or string and retrieves the site configuration matching that id. If that site info is already a simple string, that string is returned unmodified. If the site_info is further broken down into the url, user name and password for http basic authentication then that is handed off to the site_with_basic_auth_info method to build up a simple string.
It’s true that the http basic authentication credentials could be written into the url. In fact, that’s exactly what the site_with_basic_auth_info does. If that’s the case, then why add the username and password to the config file?
Tip 4: Share your site AppConfig settings between your applications
When you have the fortunate advantage of controlling both your ActiveResource-based application and your ActiveRecord-based application you can share the configuration information between the applications. Specifically, you can share the username and password information used for http basic authentication so that both sides can be externally configured… and reconfigured. By sharing the configuration files and including the use of AppConfig in the source application for the ActiveResource your http basic authentication will be as simple as
def basically_authenticated(user, password)
user==AppConfig.sites.financials.username && password==AppConfig.sites.financials.password
endWhat makes this even more compelling is that AppConfig (as anything leaning on yaml) allows you to use ERb in your configuration files. Why is that significant?
Tip 5: Use Embedded Ruby in your configuration files to automatically change your user/password
Clearly with http basic authentication you will want to go the extra step of passing through a secure connection, but if you’re too tired to add an ‘s’ to your http, then you’ll want to change your clear-text password. Often. Embedding Ruby might be just the trick because you could share a single algorithm between your applications that would change the password for you.
sites:
addressbook: http://localhost:3001
financials:
url: http://localhost:3002
username: <%= %w{money cash penny moulah dineiros pennywise poundfoolish}[Date.today.wday] %>
password: <%= Digest::SHA1.hexdigest("#{Date.today.to_s}---financials") %>There is a potential pitfall here. With this type of approach — shifting the user/password each day — the application servers will have to be kept in step. A reboot on one machine will require a reboot or restart on the other to make sure the applications share the same username/password since the AppConfig object will be re-loaded when the webserver starts. Pick the scheme that works best for you.
A Post Entitled Why assign site in ActiveResource?
ActiveResource is a great tool for helping your business keep not only its business logic DRY, but even keep its business applications dry. If you’re not familiar with ActiveResource, think of ActiveRecord using an internet-based datastore. It’s a bit more complicated than that but you can do all the basic CRUD methods, custom methods, etc
The advantage that ActiveResource brings, though, is that you only need to create the object once. Ever. Used effectively, you don’t need to create an object in one project that you import or somehow reuse in another. You create a small, targetted application and share the application with other applications. For example, you could create an accounting engine that deals with ledgers and accounts and journals and expose the RESTful HTTP interface to higher level apps that simply consume the Journals and Ledgers and Accounts using ActiveResource. Within a single company it might be the ultimate in DRY.
For Rails developers, ActiveResource is very clearly modeled on ActiveRecord. If you’ve gotten used to one set of methods you should almost seamlessly be used to the other. With one painful exception: setting the site in the class. I honestly cannot understand why there is no configuration yaml equivalent to database.yml for ActiveResource. Maybe it was unnecessary since the creators already had some RESTful applications with which to work. Whatever the case, it’s a real pain in the neck.
In an attempt to keep the ActiveRecord-like API going, I’ve come up with the following code that I’ve been dropping in /lib/core_ext/active_resource.rb
require 'yaml'
class ActiveResource::Base
protected
def self.establish_site_connection(site_id)
site_yaml = File.new(File.join(RAILS_ROOT, 'config', 'sites.yml'))
environment_configurations = YAML.load site_yaml
site_configurations = environment_configurations[RAILS_ENV]
return site_configurations[site_id.to_s]
end
endThe code is supposed to emulate ActiveRecord.establish_database_connection. As implemented above it will add an establish_site_connection method to your ActiveResource class that will read a sites.yml file in your /config folder. sites.yml is structured similarly to database.yml — you have entries for each environment (development, test, production, etc) along with site names and urls for each site.
development:
activity_center: http://localhost:3002/
church_member: http://localhost:3001/
test:
activity_center: http://testy:3002/
church_member: http://testy:3001/With such a configuration file, of course, you have a few luxuries. First, you can use different sites while running in different environments. This might make it easier, for example, to create mocks for testing ActiveResource objects. Second, you can more quickly adapt to external changes (e.g., remote resource down or relocated) since it’s just a yaml change and not a source code change.
I’ve typically gone one step further with the ActiveResource hack. As alluded to above, I have sites split into separate sub-applications each responsible for part of the end solution. As a result I have a whole family of ActiveResources that use one source application. For this reason I have emulated the multiple database solution for Rails with the following for ActiveResource.
require File.join(RAILS_ROOT, 'lib', 'core_ext', 'active_resource_extension')
class ActivityCenterResource < ActiveResource::Base
# see /lib/core_ext/active_resource_extensison.rb
self.site = self.establish_site_connection(:activity_center)
end
class ActivityCenter < ActivityCenterResource
...
end
