Mister Bleigh

TweetStream: Ruby Access to the Twitter Streaming API

2009-09-22T00:00:00-07:00

Twitter’s Streaming API is one of the most exciting developments in the Twitter API in some time. It gives you the ability to create a long-standing connection to Twitter that receives “push” updates when new tweets matching certain criteria arrive, obviating the need to constantly poll for updates. TweetStream is a Ruby library to access the new API.

Installation

Installation of TweetStream is simple, it’s available as a gem on GitHub and Gemcutter.org. To install it from GitHub:

gem sources -a http://gems.github.com
gem install intridea-tweetstream

To install it from Gemcutter:

gem sources -a http://gemcutter.org
gem install tweetstream

Usage

TweetStream creates a long-standing HTTP connection to Twitter, so unlike other Twitter libraries you don’t simply run it once and deal with the results. Instead, you provide a block that will be yielded to with each new status that arrives. The most basic example is:

require 'rubygems'
require 'tweetstream'

TweetStream::Client.new('user','pass').sample do |status|
  puts "[#{status.user.screen_name}] #{status.text}"
end

This will provide you with a small sample snapshot of all of the updates being posted to Twitter at this moment and print them to the screen. There are also methods available to track single-word keywords as well as the updates of a specified list of user ids (integers, not screen names). You can do that like so:

# Track the terms 'keyword1' and 'keyword2'
TweetStream::Client.new('user','pass').track('keyword1', 'keyword2') do |status|
  puts "[#{status.user.screen_name}] #{status.text}"
end

# Track users with IDs 123 and 456
TweetStream::Client.new('user','pass').follow(123, 456) do |status|
  puts "[#{status.user.screen_name}] #{status.text}"
end

Daemonization

One of the most useful features of TweetStream is its built-in daemonization functionality. This allows you to create scripts that run in the background of your machine rather than taking up an active process. To create a daemon script, you simply use TweetStream::Daemon instead of TweetStream::Client. Here’s an example:

require 'rubygems'
require 'tweetstream'

# The third argument is an optional process name.
TweetStream::Daemon.new('user','pass','tracker').track('keyword1','keyword2') do |status|
  # Do something like dump the status to ActiveRecord
  # or anything else you want.
end

If you were to place the above code in a file called tracker.rb you could then run ruby tracker.rb to see a list of daemonization commands such as start, stop, or run.

TweetStream is a simple wrapper on the Streaming API, but with built-in daemonization provides powerfully flexible means of accessing the Twitter Streaming API using familiar Ruby tools. More complete code documentation is available at rdoc.info.

CouchDB-Lucene, CouchDBX, and CouchRest

2009-09-21T00:00:00-07:00

I’ve been playing a lot with CouchDB lately and if you’re on OS X there’s really no easier way to do so than by using CouchDBX, a self-contained application that includes CouchDB, Erlang, and all of the dependencies you need to run Couch.

However, recently I wanted to try the power and functionality of couchdb-lucene for full-text indexing of a CouchDB application on which I was working. It wasn’t immediately obvious to me how to make that happen, so I thought I’d share how I got it working for those who might want to do the same. For the record, I am using the following versions of things:

Mac OS X 10.6 (Snow Leopard)
CouchDBX 0.9.1 R13B pl2
CouchDB Lucene v0.4

Unpacking CouchDB Lucene

You will need to place CouchDB Lucene in a convenient location, but first you’ll need to unpack the gZip file. Note that, at least for me, the default Mac unarchiver did not provide a suitable .jar file. Instead, follow the README instructions and extract it using the following command:

unpack200 couchdb-lucene-0.4-jar-with-dependencies.jar.gz couchdb-lucene-0.4-jar-with-dependencies.jar

It doesn’t particularly matter where you put it (I put mine in /usr/local/etc) so long as you remember the location.

Editing the CouchDBX .ini File

Next you will need to edit the CouchDBX local.ini file to add the external for full-text indexing. To access the file, right-click CouchDBX and select “Show Package Contents” then navigate to Contents/Resources/couchdbx-core/couchdb/etc/couchdb/local.ini and open it up in your favorite text editor. You will need to add the following lines to this file, taking note to change the directory to match where you stored your Lucene .jar file.

[couchdb]
os_process_timeout=60000 ; increase the timeout from 5 seconds.

[external]
fti=/usr/bin/java -server -Xmx1g -jar /path/to/couchdb-lucene-0.4-jar-with-dependencies.jar -search

[update_notification]
indexer=/usr/bin/java -server -Xmx1g -jar  /path/to/couchdb-lucene-0.4-jar-with-dependencies.jar -index

[httpd_db_handlers]
_fti = {couch_httpd_external, handle_external_req, <<"fti">>}

All right, that’s all the setup you need to be running CouchDB Lucene! Now you can start up CouchDBX and set up your first search indexes.

Creating a Full-Text Index View

To create a full-text index view, you simply need to add a “fulltext” field to one of your design documents. The URL structure for accessing CouchDB Lucene searches is as follows:

http://localhost:5984/database_name/_fti/design_doc_name/index_name?q=your+query+here

Where database_name is any database you have on your system, design_doc_name is any design document in your database, and index_name is a fulltext index you defined. For instance, if I had a CouchRest generated design doc for a bunch of music, I might have a design document that looks something like this:

{
  "_id":"_design/Song",
  "_rev":"af12a4b12af1b24afbf244f1",
  "fulltext":{
    "my_search":{
      "index":"function(doc) { if (!doc['couchrest-type'] == 'Song') return null; var ret = new Document(); ret.add(doc.title); ret.add(doc.artist); return ret; }"
    }
  }
}

I would then be able to access the search results with this URL:

http://localhost:5984/myapp/_fti/Song/my_search?q=Ben+Folds

Awesome! We now have full-text indexing up and running on CouchDBX!

Bonus: CouchRest Lucene

I use CouchRest extensively in my Ruby CouchDB projects, and I wanted to be able to integrate the new Lucene searches easily. I found this post that added a bit of functionality, but I wanted to be able to integrate with ExtendedDocument (and the snippet was also slightly outdated), so I’ve updated it. Just add this sometime after you include CouchRest:

class CouchRest::Database
  def search(design, index, query, options={})
    CouchRest.get CouchRest.paramify_url("#{@root}/_fti/#{design}/#{index}", options.merge(:q => query))
  end
end

class CouchRest::ExtendedDocument
  def self.search(index, query, options={})
    options[:include_docs] = true
    ret = self.database.search(self.to_s, index, query, options)
    ret['rows'].collect!{|r| self.new(r['doc'])}
    ret
  end
end

What this snippet does is allows you to perform searches on a database directly or by calling a search method on an extended document. Let’s look at a couple examples to see how it would work:

@db = CouchRest.database!("http://localhost:5984/myapp")

@db.search('Song','my_search', 'Ben Folds', :include_docs => true)

# The following is equivalent to the above, but will automatically
# include the docs and cast the result rows into ExtendedDocuments
Song.search('my_search', 'Ben Folds')

Now that we have this set up, we’re ready to go forth and build full-text search into our CouchDB apps. I hope this is helpful to some who have become somewhat familiar with CouchDB but are looking to push it a little further and try out some of the more advanced usages of CouchDB in their applications.

A Fresh Coat of Paint

2009-09-20T00:00:00-07:00

It’s been about six months since I moved this blog over to GitHub Pages and Jekyll, and that means that it’s about time for another site redesign. This time I decided to have a little bit of fun with some CSS3 features such as box shadow but I kept it simple.

Of course, as with the last page design (that I’ve been very happy to see many people adopt) you’re welcome to use this design in part or in whole for your own GitHub pages (the source is still available here), but it might be a little more difficult due to the iconography and actual use of graphics.

Thanks, and I hope you keep reading!

Good Idea, Bad Idea: Rails Rumble Post-Mortem

2009-08-24T00:00:00-07:00

The time has come and gone: the 2009 Rails Rumble is over (from a code perspective, anyway). This year myself and the other members of my team (Brent Collier, Dave Naffis, and Ping Yu) put together Thingivore, a place to show off your collection of movies, games, and books online. As one might expect from a 48-hour marathon application development experience, it was a mixed bag of elation, frustration, fist-pumping and head-hanging as the hours drew to a close. I wanted to take some time to document some of my “lessons learned” so to speak for future Rumblers and app developers in general.

Good Idea: Have a Server Configuration Guru

While the Rumble is primarily a coding contest, it’s important to note that someone on your team needs to be able to get that Linode server up and running. By having someone who can configure centos servers in their sleep on your team, you don’t have to sweat bullets at the prospect of “just getting it running.” In fact, Dave Naffis (Intridea co-founder and Rails deployment genius) came in and 45 minutes later said “OK, just hit cap deploy deploy:migrate” whenever you want to update the server. This is including setting up DNS for thingivore.com, getting Ruby, Rails, Apache, Passenger, MySQL, and CouchDB all running and probably all other manner of dark magic I can’t comprehend.

Maybe it’s because I’m not a server configuration guy, but that’s exactly the point: I didn’t have to worry about it and could focus on the design and development instead of worrying about whether or not we were going to get it running on the competition machines.

Bad Idea: “Let’s Try Something New!”

For some crazy reason, I decided that I wanted to use the Rumble as a way to experiment with new technologies (primarily CouchDB). Do not do this. The Rumble is a time to take the skills you know like the back of your hand and apply them with laser-beam focus to build something awesome and complete in 48 hours. While I’m happy with our product, there are reams of features that were cut while I scrambled to understand some of the complexities of complex sorts and other issues with CouchRest and CouchDB.

Of course, it was also fun to learn a new technology and use it in a “trial by fire” circumstance, but ultimately if you want to build something that can win the competition it’s probably better to stick to your guns.

Good Idea: As Many Plugins As You Can Actually Use

Ruby and Rails provide some of the most powerful collections of reliable code that you could hope for. We were originally planning to go 100% with CouchDB for the project, but when it became apparent that we would have to roll our own OpenID authentication we decided to slap MySQL in as well (only for user models) so that we could make use of AuthLogic and its OpenID extension. This saved us who-knows-how-many hours of work.

We also used some powerful Javascript libraries to achieve some impressive visual effects quickly and without too much pain. When planning your app, think about what technologies you’re using and make sure that there is sufficient library support to get you where you need to be in 48 hours.

Bad Idea: Plans Are For Sissies

This one is somewhat obvious, but it’s a good idea to have a strong game plan heading into something as time-limited as the Rumble. It was unavoidable in our case as I was on my honeymoon in Paris until (literally) the day before the competition, but planning in advance would have meant that every team member was utilized every moment they were available instead of spending time figuring out who should be doing what.

That being said, I think there is also value in not planning too much. During the competition there will be times when you see things that work and you need to let the application grow organically instead of mechanistically sticking to your original gameplan.

Good Idea: Hang Out In IRC

The #railsrumble IRC channel was a good place to be throughout the competition. You get direct access to a couple hundred other competitors as well as the organizers of the competition. If GitHub goes down, if there’s confusion about the rules, you’ll get your answers in a couple minutes.

It’s also just fun to feel the energy of the competition and everything from “Got it deployed!” to “so much left to do and so little time zomg”. I wasn’t able to physically be in the same area as any Rumblers, but I still had a great time and lots of comraderie on the IRC channel.

Bad Idea: Last-Minute Anything

You will have things to do until the last minute. Do not do them. You will have features you want to implement in the last 2 hours. Do not implement them. You will want to tweak the style, tweak a view, tweak something that seems important (but isn’t app-crashing) in the last 20 minutes. Do not do it. Last-minute changes that aren’t to address specific, serious bugs are a terrible idea when you won’t have a chance to fix new problems you introduce.

Next year I am going to try to force myself to spend the last 2-3 hours of the competition doing nothing but finding showstoppers on the production site and fixing only those things. Our OpenID flow was damaged in the last hour of the competition (for registration, not login) and we didn’t catch it until after pencils down. Never again!

Best Idea: Compete in the Rumble!

All in all, you can’t go wrong joining in the Rails Rumble. While your family and non-developer friends probably won’t quite understand what’s wrong with you (“You work 40 hours, over a weekend, and don’t get paid?”) you will have a blast and will learn a lot about how to build things inside a pressure cooker. I know that I plan to be back for next year’s Rumble, and my thanks go out to my team and everyone who made it possible!

Quick Tip: Railsy Array Checks in jQuery

2009-06-19T00:00:00-07:00

I love the any? and empty? convenience methods that Rails and Ruby provide, they make conditional statements much easier to read. I also really dislike the default method of checking this behavior in jQuery:

if ($('some.element').length > 0) {
  // ...do something
}

Well, luckily jQuery is ridiculously easy to extend, so why not just mix that functionality in with a couple of quick shot plugin methods? Just add this javascript sometime after you include jQuery:

jQuery.fn.any = function() {
  return (this.length > 0);
}

jQuery.fn.none = function() {
  return (this.length == 0);
}

That’s all you have to do! Now we can make the same call as before, but it looks a little cleaner:

if ($('some.element').any()) {
  // do something more readably...
}

UPDATE: Apologies, I added in the empty bit as a last-second update to the post and forgot to check and realize that empty() is part of jQuery core. Updated the name to none instead.

Make it so with RSpec Macros

2009-05-15T00:00:00-07:00

So I had heard a number of times about writing RSpec macros (like those in the fantastic Remarkable library) to ease spec writing for repetitive tasks, but the whole process seemed like more effort than it was worth. Not the case! It’s actually quite easy to write and include macros for your specs to do some of the standard heavy lifting.

First of all, this is a great resource to get started with how to write the actual macros (or custom matchers) themselves. What tripped me up was how to actually include them in my examples; monkeypatching is never a clean process and even though I knew from the comments on that post that there was a public API for doing it, as with many things about RSpec how to do it didn’t seem immediately obvious.

In my case, I was looking to define a quick login! macro that would allow me to easily create a before block to log in as a specified user or just as a FactoryGirl generated one in a TwitterAuth based app. Here’s the module I wrote and stuck in my spec_helper.rb:

module LoginMacro
  def login!(user=Factory(:user))
    before do
      @current_user = user
      controller.stub!(:current_user).and_return(@current_user)
      session[:user_id] = @current_user.id
    end
  end
end

So that was relatively straightforward and now what I wanted to be able to do was call it in my controller specs like this:

describe UsersController do
  describe "#create" do
    login!
    
    it 'should etc. etc.'
  end
end

As it turns out, RSpec offers the ability to add macros and matchers via the config.extend and config.include methods on the RSpec configuration object (extend is for class-level macros like the one I wrote here, include is for instance-level matchers). You just have to add this to your spec helper’s configuration portion:

config.extend(LoginMacro)

Voila! Now your specs will be able to use the login! macro to set up a user in no time. This really wasn’t any kind of grand discovery or new trick that people experienced with RSpec don’t already know, but I find that certain things can be hard to come across if you don’t already know how to use them so I thought I’d blog for the benefit of others like me.

TwitterAuth Supports 'Sign in with Twitter'

2009-04-17T00:00:00-07:00

Twitter recently implemented Sign in with Twitter, a convenience layer on top of their OAuth solution that provides a better user experience for those making use of OAuth as a sign-in strategy for their applications. I have just added support for this new feature to TwitterAuth. This is available immediately to new applications made with TwitterAuth as the default implementation.

If you already have a TwitterAuth application that you would like to utilize the new sign in method all you need to do is add one line to each of your twitter_auth.yml environments:

authorize_path: "/oauth/authenticate"

You don’t need to reset any user data or make any other changes, and when you restart your server people should be able to take advantage of the new experience. Enjoy!

Present.ly Nominated for the WebWare 100

2009-03-31T00:00:00-07:00

Intridea’s Present.ly has been nominated as a finalist in the WebWare 100 Communication Category. We’re honored to be chosen from a pool of more than 5,000 applicants to be one of the 300 finalists to compete for the title.

The WebWare 100 is a yearly contest held by CNET that allows the public to pick what the 100 best web applications of the year are. Past winners included such products as GMail and Amazon MP3, so we’re very excited to be included as a finalist for this year’s selection.

Voting is open right now, so please vote for us! Intridea and Present.ly are the reason that I get to make cool open-source stuff for the community, so please help me out and show your support!

Using Git Submodules for Shared Application Components

2009-03-25T00:00:00-07:00

In some cases you may have the need to run multiple Rails applications with shared functionality. While Rails 3 promises to bring “mounting apps in apps” and the ability to make the whole process simple, for now we’re stuck in the real world. However, it is possible to share components. This post will walk you through how to set up shared components that live in multiple Rails applications at once and even run specs properly.

A few notes before we begin:

This post focuses on models but the same could be applied to controllers, views, and more.
I use RSpec so the testing solutions come from that perspective.
My applications share a database, so I keep all of the migrations in one app and load from a duplicated schema.rb in the other.

Setting Up Your Application

First, you’ll need to create your shared directory. I’m mounting all shared components to my RAILS_ROOT/shared directory. So if I have app1 and app2 then I’ll do this in app1:

mkdir shared
cd shared
touch README
git init
git add .
git commit -m "Initial import of shared repository."
git remote add origin git@some.git:repository/online.git
git push

At this point all we’ve actually done is create a git repository inside our app1 application in the shared directory and pushed it (with an empty README file) to a remote git repository.

What we need to do now is actually delete this git repository and re-add it as a submodule from the remote source (this is from the root of app1 again):

git submodule add git@some.git:repository/online.git shared
git submodule init
git add .
git commit -m "Added shared directory as submodule"

What we did here is add the repository as a submodule using the git submodule command. We then ran git submodule init to update our .git/config to reflect the new submodule.
Finally we committed our changes.

So now we have a submodule living in our application directory, but right now it’s empty and Rails doesn’t know or care about it! Next we’ll set up Rails to make use of the components in the shared directory.

Setting Up Rails To Use Shared Components

Lets say that we’re going to create a shared model, SharedModel. We need to put it in the shared directory but still have it picked up by Rails’s lazy class loader. So in config/environment.rb you
will need to add the following:

config.load_paths += %W( #{RAILS_ROOT}/shared/models )

This tells Rails to look for classes in the shared models path. Now we create our model by creating shared/models/shared_model.rb:

class SharedModel < ActiveRecord::Base

end

When creating shared components I tend not to use Rails’s model generator, preferring instead to create the class by hand and generate a migration separately in my migration-having app.

This is actually all you need to do to get your shared components running in Rails. Next we’ll set up app2 to use the same code!

Setting Up The Second Application

To set up the second application, you basically need to simply repeat the same steps you did for the first application starting with git submodule add. So that would be:

Add the submodule and initialize it.
Add the shared directory to the load paths in config/environment.rb

As a note, if you are doing this to an existing application with multiple developers, other developers will simply need to pull from your main application once you’ve pushed it to a remote and run:

git submodule init
git submodule update

To get the latest revision of the submodule locally for themselves.

Changing Shared Components

To modify shared components, just change them like you would normal files in your repository. The only difference is that when you want to commit changes you will need to do so from the shared directory, push and then make a new commit from the root directory. This way you are telling the root repository to track a new revision of the
submodule.

Testing Shared Components

So just because we’re sharing components doesn’t mean that we want to abandon TDD, does it? In fact, it brings up a somewhat interesting problem. I want to have specs that I can run for the shared components that can run in both applications, in fact I want these specs to run in both applications to make sure that the shared components aren’t
having any compatibility issues. While this isn’t extremely difficult to set up, it’s not easy, either.

The first step is to create a spec directory inside your shared submodule, and create a spec_helper.rb that simply points back out to the root application’s.

In shared/spec/spec_helper.rb:

require File.dirname(__FILE__) + '/../../spec/spec_helper'

We also need to create a pending spec for our SharedModel to make sure that these are running. In shared/spec/models/shared_model_spec.rb:

require File.dirname(__FILE__) + '/../spec_helper'

describe SharedModel do
  it 'should have a pending spec'
end

The good news is that if you run autospec from your shared directory, you should be able to see your pending spec run (you will need to create a second spec.opts file in the shared/spec directory for this to use your preferred options). You should push out the changes in your shared directory and get all of your applications up to date. The bad news is that this is the only place your specs will run at the moment. Let’s change that for the better.

Note: You will need to perform the following steps in each of your Rails apps that use the shared components.

First to get your specs running with rake spec we will need to modify the task found in lib/tasks/rspec.rake by performing the following substitution:

# When you see this...
FileList['spec/**/*/*_spec.rb']

# Change it to this...
FileList['spec/**/*/*_spec.rb', 'shared/spec/**/*/*_spec.rb']

That takes care of the spec rake tasks, but there’s still the matter of autotesting from your application root. This requires a custom .autotest file in your application root that looks like this:

Autotest.add_hook :initialize do |autotest|
  autotest.add_mapping(%r%^shared/models/.*\.rb$%) { |_, m|
    autotest.files_matching %r%^shared/spec/.*_spec.rb$%
  }
end

This will automatically pick up changes to your shared models and re-run the specs for all of your shared models when they change. You could get more granular than this, but that’s a topic for another day.

Wrapping Up

Now that all of this is done you should be able to freely develop models in the shared directory and have them completely integerated into your normal development workflow. It’s quite a bit of work, but once you iron out the kinks it runs beautifully!

TwitterAuth: For Near-Instant Twitter Apps

2009-03-23T00:00:00-07:00

The public beta of Twitter OAuth support has been released and I’m excited to introduce a new library that I’ve been working on called TwitterAuth. TwitterAuth is a Rails plugin that provides a full external authentication stack for Rails applications utilizing Twitter. Think of it as “Twitter Connect” for Rails, letting you create an application that may be logged into using only Twitter credentials.

TwitterAuth supports both OAuth and HTTP Basic (though OAuth is certainly the recommended strategy) giving you maximum flexibility for building the application. Without further ado, let’s get into the installation and usage of TwitterAuth!

Installation

TwitterAuth is available as a GemPlugin, so the preferred way to install it is simply to add it as a dependency in your config/environment.rb:

config.gem 'twitter-auth', :lib => 'twitter_auth'

You can also choose to install it as a traditional Rails plugin:

script/plugin install git://github.com/mbleigh/twitter-auth.git

Once you’ve installed it, you’re ready to create a new application using TwitterAuth!

The Low-Down

TwitterAuth uses Rails 2.3 Engine support to completely encapsulate the login process within itself. All you need to do is run a generator to make all of the support files necessary in your application. Run it with the --basic option if you want to use HTTP Basic, otherwise it will default to OAuth.

script/generate twitter_auth

This generates a User class, a migration, and twitter_auth.yml. You will need to edit twitter_auth.yml to match the settings of your application, such as providing the OAuth client token and secret.

Once you’ve migrated, that’s it! You are up and running with Twitter authentication; just point users at /login to start the process (login and registration are handled in a single step). For more detailed usage information including how to access the Twitter API through TwitterAuth, take a look at the README file.

The source for TwitterAuth is available on GitHub. I have also created a Lighthouse Project for the reporting of any bugs you may come across. There is also a basic homepage that will be listing who’s using TwitterAuth.

If you’re pretty familiar with Rails authentication systems (particularly Restful Authentication), this is probably all you need to know to get started. Go forth and make awesome apps! If not, I’ve written a quick run-through of the whole process to make it easy for anyone to get started with Twitter apps.

A Quick Run-Through

I think the best way to show what TwitterAuth is capable of is just to show how quickly you can build a simple Twitter application with it. To that end, let’s build a simple way to look at your friends’ timeline in an old-school text-based way (note, this is a totally useless application but works well for a quick demo). First we need to generate the app:

rails texty-twitter

Next we want to install TwitterAuth on the application, so we’ll add this to our config/environment.rb:

config.gem 'twitter-auth', :lib => 'twitter_auth'

Once we have hooked TwitterAuth into the application, we will want to run the generator to build the support files we need:

script/generate twitter_auth --oauth

Before I start on application logic I always lay out a basic HTML layout. Here it is for this application (in app/views/layouts/master.html.erb):

<html>
  <head>
    <style type='text/css'>
      ul.tweets {
        list-style: none;
        margin: 0;
        padding: 0;
      }

      ul.tweets li {
        font-family: monospace;
        font-size: 14px;
        padding: 4px 8px;
      }

      ul.tweets li a {
        color: #fa0;
        font-weight: bold;
        text-decoration: none;
      }
    </style>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

The next step is to edit config/twitter_auth.yml to reflect our OAuth client key and secret (to register your application log in to Twitter and visit http://twitter.com/oauth_clients). Other than the client key and secret, the defaults are fine for our purposes. We’ve now set up a basic TwitterAuth application; that’s really all there is to it. So now let’s make it a working Twitter application. First let’s generate a controller:

script/generate controller timeline

This will just be a one-action controller that will render out the main timeline for the logged in user in an text-based manner. Here’s the contents of the controller:

class TimelineController < ApplicationController
  # this requires us to log in through Twitter before accessing any actions here
  before_filter :login_required

  def index  
    @tweets = current_user.twitter.get('/statuses/friends_timeline')
  end
end

In this action, current_user is the logged in user, and the twitter method provides a simple wrapper around the Twitter REST API that will automatically parse JSON API requests into Ruby hashes for you to use in your application. So current_user.twitter.get('/statuses/friends_timeline') will grab the latest statuses from your friends’ timeline (the main timeline you see when you’re logged in to Twitter) as an array of hashes. Now let’s display the tweets by creating app/views/timeline/index.html.erb:

<ul class='tweets'>
  <% for tweet in @tweets %>
    <li><%= link_to tweet['user']['screen_name'] + ':', 'http://twitter.com/' + tweet['user']['screen_name'], :target => '_blank' %> <%= tweet['text'] %></li>
  <% end %>
</ul>

This simply goes through each of the tweets we pulled down and adds a list item with a link to the author of the tweet and the content of the tweet. The structure of the hashes are identical to their description in the Return Elements section of the Twitter API wiki.

Finally, we need to add some routing to tie everything together. Make the config/routes.rb look like this:

ActionController::Routing::Routes.draw do |map|
  map.root :controller => 'stream', :action => 'index'
end

And we’re done! Fire up your server with script/server and go to http://localhost:3000/. If everything is working properly, it should redirect you to Twitter with a screen like this:

Once you click through and hit allow, it should then take you back and display your tweet stream in an old-school text interface, something like this:

It’s a simple and useless application, but in about 10-15 minutes you’ve created a fully-functioning Rails application that accesses the Twitter API and stores user information. Not bad!

See You At RailsConf!

TwitterAuth is a big part of what I will be talking about at RailsConf in my session ‘Twitter on Rails’. if you’re interested in the plugin and attending RailsConf in May I hope you’ll stop by; I’ll be building an entire Twitter application from scratch during the 45 minute presentation. Also, feel free to follow me on Twitter if you’re so inclined.

Yet Another Twitter Monetization Strategy: 'Claimed' Hashtags

2009-03-18T00:00:00-07:00

So everyone and their cat have made predictions about how Twitter will and could monetize (what, you haven’t heard of Sprinkles the economic forecasting cat?). I have one more idea, but it’s not because I think that this necessarily will happen so much as because I think it would be a fantastic feature to have for businesses on Twitter. The concept is ‘claiming’ a hash tag.

Now the main Twitter interface pretty much ignores hash tags, but Twitter Search does not and I see it as a given that hash tags are here to stay. So for hash tags that have to do with an event, a company, or other kinds of definable entities there should be a special text advertising block that can be purchased at the top of the tag search that will allow the entity that the tag is about to explain and maybe provide a few links.

For example, with all of the endless tweets about SXSW I think it would be useful both for the SXSW organizers and for the people looking at the tag to have a block at the top that says something along the lines of “SXSW is a conference held yearly in Austin, TX that encompasses video, audio, and interactive media” with a couple of links to pertinent information. This provides a context to people clicking through to the Twitter Trends #SXSW tag who wouldn’t otherwise know much about the conference and gives SXSW another way to promote themselves.

This system would have to have some pretty stringent acceptance requirements, you wouldn’t want competitors to be able to claim their opponent’s tags etc. but I also think it has a lot of promise for providing a revenue stream for Twitter and actually useful information for users. I’m not a market prognosticator, and I think it’s actually pretty unlikely that this would come to pass, but I do think that it would be an interesting new way to advertise on the web.

The Case For GitHub Canonization

2009-03-03T00:00:00-08:00

I was going through the fork queue of one of my projects on GitHub today when it really struck me how useful it would be to have canonical projects in GitHub. Now, I know that to some extent canonization (by which I mean an ‘official’ version of a given project that would be accessible at, say, http://github.com/project-name instead of http://github.com/user-name/project-name) goes against the ‘free forking spirit’ of Git and GitHub, but I believe that the benefits would outweigh the potential risks.

If GitHub provided a canonization process, I would imagine it would work (something) like this:

A user creates a project. Until otherwise noted, it lives at http://github.com/user-name/project-name
A user chooses a button somewhere in admin that says “canonize.” Click!
GitHub examines the project and checks to see if the canonical name already exists and also if the project is the ‘root’ of the most forks.
If there is no canonical conflict (no project exists and the specified project is the root of most forks), canonical status is granted.
If there is a canonical conflict (a non-root fork, for instance), the canonization is marked as ‘pending’ and a message is sent to the root fork asking if the fork can canonize.

Now this isn’t dead simple and it could be abused (‘canon’ squatting for projects etc.) which I imagine is most of the reason GitHub is hesitant to implement it. It might require some kind of administrative approval process to prevent such abuse, which is both more work and can cause conflict. The benefits of such a system, however, are many.

Canon allows for the GitHub gem server to provide the ‘official’ gem for a project without all of the messy remembering of user names. This would obviate the need for RubyForge entirely, something that I suspect may get Magnus Holm to argue with me (again). GitHub is where open-source development in Ruby is happening now, it may as well be where we get our gems. If I can bump my gemspec and that’s all I have to do to distribute the latest official version of my gem, that saves me time and effort.

Canon also allows for projects such as Jamis Buck’s Capistrano and FuzzyFinderTextMate to live on after their creators have officially given up on them. If I have a project that I don’t have time to maintain, I can ‘pass the torch’ to another fork of the project which would then become canon.

Finally, canon makes it easier for people to figure out which fork of a project to contribute pull requests. This is a rarer case, but there are some times when it can be difficult to tell who the real maintainer of a project might be. Canonization makes this easy.

None of this has to conflict with GitHub’s existing system: you should still be able to pull projects and install gems from the user-name/project-name nomenclature as before. Canonization would simply add a new layer of usefulness to the already crazy-useful site. So how about it, GitHubbers?

Quick Tip: Rails URL Validation

2009-02-18T00:00:00-08:00

After doing a quick Google Search I realized that everyone might not know about a great way to do URL validation in Rails. The secret is a little-known method of the URI class, regexp. It lets you generate a regular expression for matching URLs based on an array of accepted protocols. What’s even better, it can be plugged directly into Rails’s validates_format_of. It’s this easy:

class User
  validates_format_of :website, :with => URI::regexp(%w(http https))
end

This will match anything that URI.parse will recognize, meaning that it’s a pretty accurate and powerful URL matcher. URL validation was one of those little annoyances in writing Rails models because it really seemed like there should be an easier way. I found mine, so I thought I’d share it!

Utilize Canonical URLs in Your Rails Apps

2009-02-13T00:00:00-08:00

Today came the announcement that all of the major search engines are going to support a ‘canonical’ URL hint that will allow site owners to specify a single URL for content that may be replicated across many URLs (such as for categories etc.).

To make use of this in Rails applications, I’ve written a plugin that allows you to easily specify canonical URLs for your content. To install it as a gem, just add this to your environment.rb:

config.gem 'mbleigh-canonical-url', :source => 'http://gems.github.com', :lib => 'canonical_url'

Using it is extremely simple; just add this to the <head> section of your layout:

<%= canonical_link_tag %>

And in your controllers, any time you want to specify a canonical URL you can do so like this:

class BlogController < ApplicationController
  def show
    @post = find_post # assume this is a standard blog post type record
    canonical_url blog_post_path(post.year, post.month, post.day, post.slug)
  end
end

Now any time the show action is run, no matter how the routing came to be there, a single canonical URL will be shown in the header. If no canonical URL is specified in the controller (or through the canonical_link_tag helper directly) the helper will not output anything, making it completely harmless to add to any application.

The source for the plugin is available on GitHub. So go forth and canonize your applications!

Outsource Your Blog

2009-02-11T00:00:00-08:00

Blogs are simple pieces of software. It’s the penultimate “sample application” that you build when learning frameworks like Rails. But what I’ve found is, the more familiar I am with writing and managing blogging applications, the less I have any interest in doing it. Everything is too heavyweight, with themes and databases and complex administrative interfaces. I found myself yearning for something simple, uncluttered, and under my control.

When GitHub announced support for user pages I knew in the back of my mind that this was going to be a big deal. At the time I didn’t really know how it could be used for a blog since it seemed to just serve up static pages, but I definitely liked what I was hearing. After a couple of months went by, I finally decided to take the plunge and see what I could accomplish. Surprisingly, everything I wanted in a blog!

Dead Simple Publishing

GitHub Pages are as simple as:

Create a GitHub repository called yourname.github.com
Push a ‘master’ branch to that repository
GitHub will automatically build your page using Jekyll

You may not have heard of Jekyll before (at least outside of the context of GitHub pages), but it is essentially an HTML generator that allows you to generate static HTML sites based on some very simple rules. Once you learn those rules, it’s extremely simple to build sites that can be deployed anywhere that can serve up HTML (no server-side required).

You can also use a CNAME to redirect your own domain to GitHub.

What About Comments? Images?

New tools have appeared that not only take care of all of the functionality I need for handling blog comments and image uploads, but do them better than any blog engine I have ever used.

Disqus completely offloads blog post comments, and does a ridiculously good job of it. You get message threading, a great e-mail notification system, spam protection, and best of all it’s as simple as a Javascript include in your blog post template.

Images are easy enough to add to a directory structure, but I find it even easier to use Skitch, drag an image to it, webpost it, and then use the direct image URL to embed it in the post.

Why Do It?

I like using Ruby. I like writing my posts in Textile. I hate managing comments and complicated blog systems. If that sounds like you, you may want to look into outsourcing your own blog.

Open Source Is Amazing

2009-02-11T00:00:00-08:00

Yesterday, I pushed by new, Jekyll-powered blog out to GitHub. That was 24 hours ago. Today, I get a note from Scott Chacon (GitHub guy and overall git guru) saying he liked my template and decided to use it for his site.

That’s what’s so great about GitHub’s open source community: I shared it with no publicity or fanfare on my GitHub account and someone else found it useful and implemented it for their own site. I guess maybe some people don’t like others copying their site, I think it’s pretty great!

So if you like this little blog and open-source project display page, fork away! All that I would like in return is for you to let me know that you’re using it so I can check out your site.

Moving to Jekyll

2009-02-10T00:00:00-08:00

As of today, my blog and site are hosted on GitHub and served through Jekyll. I switched to WordPress not too long ago but felt slightly disingenuous not using a Ruby-based solution. I had been using Jekyll for a couple of other projects (Intridea University and my wedding website) and decided to go ahead and go all out.

The look is mostly the same but I love that I can just pop into TextMate, work on a Textile file, push to GitHub and bam! I’m deployed. If you haven’t used the GitHub Pages feature of GitHub I suggest you give it a try. It’s great!

The only downside is that the RSS feed will be resetting all of the unique IDs so you may get your feed reader spammed if you’re a subscriber. Also the comments are vanished once again (oops!) but I’m now explicitly setting Disqus permalinks so the next time I change my mind about how I want to run the site hopefully it will be better.

It's No Joke - Real-Time Search is a Big Deal

2009-02-09T00:00:00-08:00

I saw the article ’Google’s First Real Threat: Twitter’ pop up in my RSS readers today from a couple sources and didn’t click through and read; I had already learned the power of Twitter Search on multiple occasions (see my previous discussion here). But then something funny happened: I got an e-mail from O’Reilly saying that all three of my RailsConf proposals were accepted. Then I heard from a colleague here at Intridea that his talk was accepted.

This seemed, frankly, too good to be true. So I hit up Twitter Search for RailsConf, and sure enough, everyone seemed to be elated about getting their proposal(s) accepted. This confirmed my suspicion, and I contacted O’Reilly immediately. In fact, I contacted O’Reilly and they weren’t even aware of the problem yet. I may have been the one who alerted them to the issue in the first place. Confirmation came a few minutes later via the RailsConf Twitter account. While I’m a bit disheartened that I’m not necessarily speaking at RailsConf, it was an object lesson in just how powerful Twitter search has become.

Is Twitter a replacement for Google? No. But Twitter provides an instantaneous connection to what is happening to people right now, and in some (many) circumstances it can give you answers that Google never would, even after they re-index the web. This also to me serves as a lesson in how to truly compete with Google. Don’t try to ‘out-Google Google’ like Cuil did. Instead find a way to provide a search that Google can’t touch, that can’t be created simply by crawling the web endlessly looking for new content.

Pay attention to where Twitter search goes in the coming months and years, because it’s no joke: real time search is a big deal.

SASS: The Better, More Powerful CSS

2009-02-04T00:00:00-08:00

I am a huge fan of SASS (Syntactically Awesome Stylesheets) for styling Rails applications. I have been using it on all of my projects for quite a while now and have developed some great techniques that make it much easier to organize, write, and read stylesheets in an application.

Unlike HAML, SASS retains most of the same “feel” when writing the code as vanilla CSS. It simply adds more power and better organizational tools, making it an easy choice as a go-to replacement. You can teach someone the basics of SASS in about 30 seconds: use two spaces to indent everything, put the colon before the declaration and no semicolon afterwards. In fact, I’ve even written regular expressions to convert CSS to SASS mechanically in some cases. It’s easy to pick up and once you do you will start reaping real benefits.

The 20-Second “Get Up And Running”

To use SASS, you must have the HAML gem installed on your Rails app. Add it to your environment.rb:

config.gem 'haml', :version => '>= 2.0.6'

Now you can create SASS stylesheets simply by making .sass files in a public/stylesheets/sass directory.

Basic Example: Building a Menu the SASS Way

The best way to start explaining the power of SASS may be through one of the more common styling tasks one encounters: styling a menu. Here we’ll assume a menu structure like this:

<ul id='menu'>
  <li><a href='/'>Home</a></li>
  <li><a href='/about'>About</a></li>
  <li><a href='/services'>Services</a></li>
  <li><a href='/contact'>Contact</a></li>
</ul>

To style this menu in CSS, we might do something like this:

#menu {
  margin: 0;
  list-style: none;
}

#menu li {
  float: left;
}

#menu li a {
  display: block;
  float: left;
  padding: 4px 8px;
  text-decoration: none;
  background: #2277aa;
  color: white;
}

SASS allows you to use indentation to indicate hierarchy, saving much repetition and space. The same code in SASS looks like this:

!menu_bg = #2277aa
  
#menu
  :margin 0
  :list-style none
  li
    :float left
    a
      :display block
      :float left
      :padding 4px 8px
      :text-decoration none
      :color white
      :background = !menu_bg

Hierarchical selectors mean that if you indent something, the selector it falls under will automatically be prepended to it, so the two examples above generate the same output. You’ll also notice !menu_bg in the SASS code. SASS allows you to declare constants that can be reused throughout the code, a very useful feature when dealing with colors.

Now we have our basic setup for the menu, but let’s handle some better cases. I want the color to change when I hover over the menu options and I want to highlight the current menu option (we’ll assume that the <li> encapsulating the current menu item will have class ‘current’ when it is selected). Let’s add these features first using CSS, then SASS. With CSS:

#menu {
  margin: 0;
  list-style: none;
}

#menu li {
  float: left;
}

#menu li a {
  display: block;
  float: left;
  padding: 4px 8px;
  text-decoration: none;
  background: #2277aa;
  color: white;
}

#menu li a:hover {
  background: #116699;
}

/* Make sure the color doesn't change when the current option is hovered. */
#menu li.current a, #menu li.current a:hover {
  background: white;
  color: black;
}

This isn’t too bad, but our selectors keep getting longer and longer. Let’s look at the same thing in SASS.

#menu
  :margin 0
  :list-style none
  li
    :float left
    a
      :display block
      :float left
      :padding 4px 8px
      :text-decoration none
      :color white
      :background = !menu_bg
      &:hover
        :background = !menu_bg - #111111
    &.current
      a, a:hover
        :background white
        :color black

The ampersand (&) in SASS is a shortcut to insert the entire parent selector at that point. By using &.current I am saying “the parent selector with a class of current.” &:hover means “the parent selector when hovered.” This makes it easy to write complex selectors in a compact, easy-to-read manner.

Another great thing about SASS is it has built in CSS color math. Note where I declared :background = !menu_bg - #111111. That is equivalent to subtracting 1 from each of the values of the constant’s color, which in this case yields #116699. This is great, because now I can change the color of the menu and the hover state will automatically change without me having to manually find it and recalculate it for a new color. Note that whenever you are using constants or performing calculations you need to add the equals sign to your declaration.

Getting organized with a master.sass

Another way you can use SASS is to organize all of your CSS into a single file without having to worry about it in your view. I have recently started using this approach for a number of reasons:

It allows me to control stylesheet inclusion from within the stylesheets themselves, making the structure more readable.
I can define global colors that can then be used in any of the child stylesheets.
It’s really easy!

In a new project, I always create a master.sass that will look something like this:

// Define app-specific colors first
!green = #191
!gray = #555

// Now define globally applicable, general styles

body
  :font-family Arial, sans-serif
  
a
  :color = !green
  :text-decoration none
  :font-weight bold

// Now import all of your other SASS files, they will be
// automatically included in the same generated CSS file
// at compile time.

@import menu.sass
@import content.sass
@import admin.sass
@import users.sass

Using this structure I have a modular, easily expandable collection of stylesheets with global color constants and basic styles. In addition, I can add this to my Rails application with the simplest of calls:

<%= stylesheet_link_tag 'master' %>

Wrapping Up

Hopefully this gives you a taste of the easy awesomeness that is possible with SASS. The greatest thing about the library is you don’t lose touch with writing CSS because SASS is CSS, just with a few extras and shortcuts to make power-styling easier.

Update: A commenter pointed out that I forgot the @ before my import statements in the master.sass example, this has been fixed.

Use MacFUSE to Make a Boxee Torrent Dropbox

2009-02-02T00:00:00-08:00

I recently set up Boxee on my Apple TV and have started using it for all of my media needs. While it’s great at using RSS feeds for torrents, having to SSH in to my Apple TV every time I wanted to start some random video downloading was growing to be a bit of a pain. So I decided to utilize MacFUSE and sshfs to mount a torrent dropbox so that I could just save torrents directly to the dropbox without manually SCP-ing them over to the Apple TV.

First you’ll need to install MacFUSE version 2.0 or greater. Once the installation is complete, you will need to get sshfs to actually mount the remote folder to your local box. The easiest way is just to grab it off of SVN by typing the following in the Terminal:

$ cd ~/Desktop
$ svn co http://macfuse.googlecode.com/svn/trunk/filesystems/sshfs/binary sshfs-binaries

Once you’ve done that, you should copy over the correct binary (either tiger or leopard) to your $PATH somewhere, (I chose /opt/local/bin:

$ cp sshfs-binaries/sshfs-static-leopard /opt/local/bin/sshfs

Now you’re ready to actually do the mounting. You will need a point on the filesystem to put the mount, I chose /mnt. We simply need to perform the actual mounting now. Enter this command (assuming that your Apple TV can be SSH-ed into via appletv.local:

$ mkdir -p /mnt/boxee-torrent-drop
$ sshfs frontrow@appletv.local:/Users/frontrow/Library/Application\ Support/BOXEE/UserData/Torrents /mnt/boxee-torrent-drop

When prompted for a password enter frontrow (or whatever your SSH password for your Apple TV is) and it should execute without error. If you now browse in the Finder to /mnt you should see a MacFUSE drive icon alias pointing to your Boxee torrents folder. You can drag this mount to your Finder sidebar and whenever you save a torrent just save it to that directory. Boxee will now automatically pick it up and start downloading it!

For bonus points, you could take this and:

Run it as a LoginItem so that you’re always mounted.
Set up remote SSH access to your Apple TV so that you can start torrents from anywhere in the world (please change your SSH password first).

Enjoy!

The Case For Web Applications

2009-02-02T00:00:00-08:00

Neil McAllister recently wrote a piece on InfoWorld entitled The Case Against Web Apps. In it, he outlines “Five reasons why Web-based development might not be the best choice for your enterprise.” Obviously, as an employee of a web application services and products company, I disagree strongly with that opinion.

Web applications are not a “trend” in enterprise software development. They represent a fundamental shift in how software is developed, implemented and used in today’s technological climate. But to be specific, let’s go point-by-point through the “case against web apps.”

“It’s client-server all over again”

It certainly is. The difference is, we’re not living in a mainframe, dumb-terminal world anymore. Server infrastructure is cheap and scalable, and as more enterprises push their IT infrastructure to the cloud (see another article from InfoWorld: IT needs to get over its cloud denial, or management will get over IT) the need for on-site datacenters will shrink and, for many companies, eventually disappear.

Web applications require no client deployment, no versioning, no installation and no machine-by-machine support. There’s no massive rollout procedure for a new version and no back-breaking process if there’s a small but important glitch in a major release.

“Web UIs are a mess”

When each project has specific and individual user experience needs, isn’t it good to reinvent the wheel a little bit? Having a blank canvas means having the chance to build exactly what is right for this application, not shoehorning an application into pre-defined constraints.

Bad web sites and bad desktop application interfaces are equally impenetrable to the average user. The success of the user experience lies not in the hands of the chosen deployment platform but in the hands of a developer with an eye for user experience. I don’t think it’s a stretch to posit that the majority of such developers work either on web applications or for Apple. When was the last time you saw a beautiful Visual Basic application interface?

“Browser technologies are too limiting.”

“User interface code written in such languages as C++, Objective C, or Python can often be both more efficient and more maintainable than code written for the Web paradigm.” This statement rings false to me; when was the last time you saw a graphic designer who could pop open his trusty Visual Studio 2008 and recompile a project to tweak the user interface? The fundamental advantage of HTML/CSS/Javascript based interface development is that is accessible to a wholly different set of people, people who understand how users think and want to behave but don’t necessarily have the programming chops to implement the actual code.

The proliferation of Flash, Quicktime, and Silverlight can pretty much all be explained by one fact: HTML doesn’t support embedded video. Few web developers turn to Flash or other technologies for much outside of rich multimedia playing. You also can’t consider such a tool a liability when it is available for more than 99% of all web users.

This also brings up a fundamental flaw in “the case against web apps”: if this is an article talking about using web applications for enterprise business applications, how are any of the concerns about browser compatibility valid? Don’t most enterprises have control over what browsers get used by their employees? The refusal of Internet Explorer 6 to kick the bucket certainly seems to indicate that companies have a great deal of control over how employees access the internet.

“The big vendors call the shots.”

Is this untrue of any development platform short of Linux? Companies are at the whim of Microsoft when they released an in-many-cases incompatible, largely disparaged upgrade to their operating system with Vista. That’s much more of a moving target than the web standards, which with the exception of Internet Explorer (another Microsoft project) make writing cross-browser, cross-operating system applications a relative ease.

“Should every employee have a browser?”

You know what? Lots of people e-mail jokes to their families from their work accounts, let’s not allow people to write e-mails anymore. I heard that sometimes people make personal calls from the office, so let’s get rid of the phones, too. Not only is this point inherently distrustful of the work ethic and general competency of most employees, it doesn’t even hold water: browsers can be used to access internal applications even if all outside internet access is restricted.

In the end, I may have spent too much time here refuting his arguments without making the real case for web applications. So, very briefly, here’s it is:

Massively Agile: Web applications can be built, deployed, and put into general use in a matter of weeks, not months or years. New features can be rolled out on a continuous basis rather than waiting a year for a new “point release.”
Massively Accessible: Web applications can be accessed from any device that can access the internet, regardless of operating system or system requirements. As mobile phones become more web capable this becomes even more apparent and necessary. Desktop applications require completely separate development efforts.
The Local Data Problem: There’s no need for “shared” folders and collision control on documents in a web application. Everything is on the server, everything is up-to-date as soon as it is accessed.
Web is the new Desktop: Technologies such as Adobe AIR and site-specific browsers have made it so that web applications are becoming more and more like desktop applications, bringing the ease of development and deployment with them.
Collaboration is King: Web applications, due to their centralized nature, can naturally encourage less isolated, more collaborative work between employees.

Web applications aren’t the solution to every problem a business faces. If you need graphically intense 3D visualizations for your buciness, web applications probably aren’t the way to go for you. But for most businesses, most of the time, web applications will be more cost-effective, more useful and more agile than the alternative.

HasAvatar: Defining an Application Vocabulary

2009-01-28T00:00:00-08:00

One of my favorite techniques to DRY up a Rails application is to pull out common functionality into a simple “vocabularized method,” by which I mean a simple descriptive method call that can be made from within your model or controller definition. For instance, in some applications I might have multiple models that have an “avatar.”

These avatars all behave the same and should do the same things so I don’t want to just repeat myself in the code. Instead I set up a file called has_avatar.rb inside my config/initializers folder. We use Paperclip for attachment handling at the moment, so I am going to create a wrapper for the specific Paperclip functionality I need for the avatars. Here’s the code:

module HasAvatar
  STYLES = { :large  => ["200x200#", :png],
             :medium => ["100x100#", :png], 
             :small  => ["70x70#", :png],
             :little => ["50x50#", :png],
             :tiny   => ["24x24#", :png] }
             
  def self.included(base)
    base.extend ClassMethods
  end
  
  module ClassMethods
    def has_avatar
      has_attached_file :avatar,
                        PAPERCLIP_DEFAULTS.merge(
                          :styles => HasAvatar::STYLES,
                          :default_style => :medium,
                          :default_url => "https://assets.presentlyapp.com/images/avatars/missing_:style.png",
                          :path => ":account/avatars/:class/:login/:style.:extension"
                        )
    end
  end
end

ActiveRecord::Base.send :include, HasAvatar

We define a module, HasAvatar that will add a new class method called has_avatar into whatever class it is included. I defined a constant STYLES that lets me access the style hash outside of the attachment definition. A final piece of DRYness in the code is the PAPERCLIP_DEFAULTS constant which is just the default setup for all attachments (S3 Bucket, etc.) and I override the options I need for the avatars by merge-ing them in.

class User < ActiveRecord::Base
  has_avatar
end

class Group < ActiveRecord::Base
  has_avatar
end

Now both users and groups will have all of the expected Paperclip functionality without having to repeat ourselves. This is a simple example but it shows the general practices behind building your application vocabulary, which is just my made-up term for the abstract reusable components that are specific only to this application. Of course, if it’s useful outside of the application, you might want to just go ahead and pluginize it!

The usefulness of these abstracted methods also comes in through the inherently polymorphic nature of Ruby. Throughout my code I can write helpers, views and more to support avatars without caring whether the object in question is a User or a Group. Basically, the DRYer you start the DRYer you stay.

Twitter Search Plus: Find Replies Inline With Twitter Search

2009-01-22T00:00:00-08:00

Last night after watching the Lost premiere I had a question to which I was having a hard time finding the answer. The show had just ended and I wanted to know (tiny spoiler alert) who the woman Benjamin Linus was talking to at the end of the episode was. Google was no help (the episode had finished mere minutes before) so I turned to Twitter for some real-time searching.

By searching for lost old woman I was able to find plenty of other people asking the same question I had, but no one was giving the answer. I suspected that a reply to one of the tweets in question would have the answer so a few more minutes of manually searching for replies to the search result tweets finally yielded my answer. It also showed me how useful Twitter Search could be with a built-in way to find replies to the tweets. Rather than request the feature and wait until Twitter decides to implement it, I got my hands dirty with Greasemonkey and rolled my own.

Twitter Search Plus

This userscript (which requires the Greasemonkey Firefox Extension or equivalent userscript support in another browser) will automatically add a “Find Replies” link to the actions on Twitter search results and go out, find, and insert the replies to the user in question inline, just like the Show Conversation view. Here’s a screenshot of it in action:

This makes it really convenient to discover if a tweet you found while searching sparked any conversation. While I used it for entertainment, you could easily also find out who replied to a negative post about your brand, or if anyone else has already answered a question you were about to answer.

Installation and Limitations

You can install the script by following this link and see the source right here as a GitHub Gist. The script has also been posted to UserScripts.org.

Because there is no way to sort Twitter searches from oldest to newest, you will only see the 15 most recent replies to the user posted after the tweet in question. If the tweet is old or the user is extremely popular you might not get the replies you’re looking for. I’m open to suggestions as to how to make this work better.

Happy Twittering!

Sort Your Files By Date

2008-12-04T00:00:00-08:00

Others have talked about people being “searchers” or “filers” when it comes to e-mail. I think the same thing applies to hard drive organization, and I’m definitely a searcher. I don’t have much in the way of organization in my folders short of basic overarching functional categories (Documents, Pictures, Rails, etc). Right now my Documents folder has 365 items in it and absolutely no canonical organization strategy. However, it rarely takes me more than a few seconds to find what I’m looking for at any given point. The secret? I just sort my files by date.

I may be giving myself too much credit here (this may be completely obvious to lots of people), but most of the people I have talked to about it never even thought about the idea of defaulting to a file sort other than by name. So why does sorting by date help?

Most of the time, I’m looking for a file that I’ve worked with recently.
A good 50% of the time, I’m looking for the most recently modified file (uploading docs to e-mails, finding the app I just downloaded etc).
I’m a pretty good visual scanner, so I can usually spot what I’m looking for without much trouble in a list of files.
If all else fails, it’s not like I can’t go back to sorting by name.

So this isn’t exactly the life-altering stuff of epiphanies, but it’s a little time saver that helps me be more productive throughout the day.

The Importance of External Downtime Resources

2008-11-28T00:00:00-08:00

Back in the days when Twitter was going down early and often, the biggest complaint by users often wasn’t that Twitter was down but rather that they didn’t know what was happening or when it would be fixed. Thus the Twitter Status Blog was born, an externally hosted Tumblr that would be updated when they were having issues. GitHub did similarly after a recent bout of outages.

Why are such resources so important? Because ultimately it’s not the fact that a service you want to use is unavailable that’s a problem so much as the feeling of helplessness of something you want/need to use being unavailable with no hint as to why or when it will be back.

Case in point: today is Black Friday and Live.com is offering a 12 hour 40% cash back promotion with HP. I’ve been trying to get through for the past six hours with no success (the entire Live.com cashback section has been down for most of that time). This would be fine if I had any idea what the problem was, how I could ensure that I can get the cashback even with the site being down, or even a “sorry, you’re out of luck.” A call to Microsoft support simply directed me to an e-mail support form with no promise of resolution before the deal expires. Instead I’m a slave to my refresh button trying to get the deal during brief bouts of uptime.

So if you have a product that people depend on, make sure you have some ways to let people know what’s happening without depending on your app itself. Present.ly, for instance, employs both a Twitter account that we monitor to quickly respond to any questions about service interruptions and a support site that is externally hosted and will continue to work even if Present.ly is down. It is only in the case of three independent services going down simultaneously that we will be out of luck.

Ultimately all that matters is that your customers are happy. You can keep them happy even in times of outage by making sure that they know that you’re working on it, you know about it and you care about it.

Hacking the Mid-End (Great Lakes Ruby Bash Edition)

2008-10-11T00:00:00-07:00

I just finished giving my “Hacking the Mid-End” talk at the Great Lakes Ruby Bash. It was a bit longer format, so I updated the slides a bit and added a third example to the code. The slides are embedded below and the new code is available in the GitHub Repository.

I’m still at the conference, but I wanted to post up the slides and code immediately! Enjoy.

Colorist: Color Manipulation for Web Heads

2008-08-18T00:00:00-07:00

While writing color customization code for a recent project, I once again ran into the fact that the existing color gems for Ruby seem to be built for vastly different purposes. To that end, I decided to write a new library for dead-simple manipulation of colors with an emphasis on ease-of-use and being useful for web developers.

Installation

gem install colorist


The Basics
To instantiate a color in Colorist, you use a number of methods:
require 'colorist'
include Colorist

red = Color.new(0xff0000)
red = 0xff0000.to_color
red = "red".to_color
red = "#f00".to_color
red = Color.from_rgb(255,0,0)
Note: I include Colorist in these examples, but there’s no reason you can’t leave it namespaced i.e. Colorist::Color instead.
The idea is to give maximum flexibility without making it complicated. Once you’ve instantiated a color, you can figure out a few tidbits about it and perform some basic operations:
red.brightness # => 0.299
red.r # => 255
red.invert # => #<Color #00ffff>
red.text_color # => #<Color #ffffff>
red.to_s # => "#ff0000"
red.to_s(:rgb) # => "1.000, 0.000, 0.000"
Operations
The real value of Colorist comes in comparison and addition. You can use normal operators with the colors to add them together, subtract them, and compare them based on brightness. You can also do this with the string or numeric representations of colors:
red = 0xff0000.to_color
green = 0x00ff00.to_color
yellow = red + green
yellow = "red".to_color + "green"
yellow.to_s # => "#ffff00"
red - 0.2 # => #<Color #cc0000>
Comparisons work off of the brightness of a given color. You can also calculate the contrast between two colors using the W3C’s formula:
red = "red".to_color
red > "black".to_color # => true
red > "white".to_color # => false
red.contrast_with("green".to_color) # => 0.500653594771242
Get Coloring!
That’s most of the basic functionality, for all of the details you can view the RDoc on RubyForge. The source is available on GitHub and there is a Lighthouse project for any bugs or feature requests. Enjoy!



Fetches: Bringing Your ActionController Its Slippers
2008-07-28T00:00:00-07:00
There is a piece of code that shows up more than 80% of the controllers that I write, and it goes a little something like this:
class UsersController < ApplicationController
  def user
    @user ||= User.find(params[:id])
  end
  helper_method :user
end
A simple memoization method to allow me to easily grab the parameter-referred user in all of my actions. If I’m using nested routes, that means I can write two, maybe three of these methods into a controller. I’m basically using slight variations on the same code 20 different times in an application. Since we live in a world that loves to be DRY, I thought, “I can do better.”
Fetches: Memoizing Your Parameter Record Retrieval
Fetches is a simple extension to ActionController that lets you simply define those kinds of fetch methods on a one-line command. For the example above, I can rewrite it like so:
class UsersController < ApplicationController
  fetches :user
end
That’s pretty useful! Not only can I call the “user” method from the controller, but it’s automatically helperized so that I can use the same call in my views. Of course, there are times when more advanced fetching is called for, say using a method other than find or storing to a different variable name. Let’s take a look at a slightly more complex example:
# assuming a route like /users/:user_id/articles/:id
class ArticlesController < ApplicationController
  fetches :user, :as => :author, :from => :user_id, :using => :find_by_login
  fetches :article
end
Now if I were to call “author” in any of my controller actions, it would be equivalent to User.find_by_login(params[:user_id]). Similarly, calling “article” is equivalent to Article.find(params[:id]). The “from” option can also take a Proc in case your fetching is not simply a parameter key:
class UsersController < ApplicationController
  fetches :user, :from => Proc.new{ |c| c.params[:user_id] || c.params[:id] }
end
The main advantages to fetches are brevity, clarity and DRYness. I’ve found that this method covers every use case for parameter-based fetching that I’ve needed, and as such provides a much simpler, more readable, and shorter way to fetch models for use in your controller and views.
Installation
Fetches is available as a gem as well as in traditional plugin format. To install

as a gem, add this to your environment.rb:
config.gem 'mbleigh-fetches', :source => 'http://gems.github.com', :lib => "fetches"

To install it as a traditional plugin:
script/plugin install git://github.com/mbleigh/fetches.git

Resources
The source is available on GitHub, the Acts As Community project is there for general discussion, and the Lighthouse is there for bugs and feature suggestions.
UPDATE: A commenter requested that the plugin be able to handle creation of new records in addition to fetching existing records. I have added in the :initialize option to do just this. Examples:
fetches :user, :initialize => true # initialize from params[:user]
fetches :user, :initialize => :author # initialize from params[:author]
fetches :user, :initialize => Proc.new{ |c| {:login => c.params[:login], :email => c.params[:email]} }

  



Using HTTP Status Codes for Rails AJAX Error Handling
2008-07-23T00:00:00-07:00
A problem that often arises in AJAX-based web applications is how to handle it when things go wrong. The user should be informed of the problem in a descriptive manner, but obviously the internal workings of the application should not be revealed. A generic and useful way to handle this problem is to use HTTP Status Codes to indicate the type of failure, and use the javascript to cope appropriately.
In this example I will be using jQuery, but the principles behind are just as applicable to Prototype or any other Javascript library.
Your Friends 403 and 500
Anyone who’s built a Rails site is familiar with the 500 error. That’s the generic exception code thrown whenever something goes wrong in your application. Users should, hopefully, never ever see this when they’re using the site. However, oftentimes there are exceptions or errors that users should experience just as result of improperly filling out fields, permissioning, etc. So how do we differentiate?
The Rails render method has the ability to render out an arbitrary HTTP Status Code (i.e. 500 for error, 404 for not found, and many more). The “403 Forbidden” code means that the server understood the request made of it, but is refusing to complete it. This sounds like an apt description for typically “caught” exceptions. So let’s use the 403 code to intelligently handle the exceptions that we want to be seen by the user.
In the controller
Let’s take the simplest example, an invalid record. If you are creating a record via AJAX, a flash[:error] with a render :action => "new" is not going to suffice. Let’s try something like this instead:
class ItemsController < ApplicationController
  def create
    Item.create!(params[:item])
    # continue on your merry way if it works
  rescue ActiveRecord::RecordInvalid => e
    respond_to do |format|
      format.html { 
        flash.now[:error] = "There was a problem creating the item."
        render :action => "new"
      }
      # Render out the validation failed message with a
      # 403 status code.
      format.js { render :text => e.message, :status => 403 }
    end
  end
end
All right, now that we’ve got it handled on the controller side, it’s time to work some Javascript magic on our AJAX call.
$('a#ajax_link').click(function() {
  $.ajax({
    url: '/items', 
    success:function(data, textStatus) {
      // do success things
    },
    error:function(request, textStatus, errorThrown) {
      // Use the specific message for a 403, but
      // a generic failure message for a 500
      var message = (request.status == 403) ? 
        request.responseText : "An unknown error occurred. Support has been contacted.";
      // Simple alert for example, but you can handle
      // however you want, such as populating an error message
      // div and making it appear.
      alert(message);
    }
    return false;
  });
});

Now when your AJAX request fails, it will render a user-friendly error message if it’s an ‘expected’ error or a generic message if the request fails with an unexpected exception.
This is a simple example, but by building a general framework for error expectations you can make it much easier to provide user-friendly error handling that gives them all of the information they need without revealing any of your internal processes.

  



UberKit Update: UberForms to Ease Form Building
2008-07-14T00:00:00-07:00
Last week the Uberkit kicked off with some helpers to make your menu-building much easier. This week we’re following it up with UberForms, a Form Builder that DRYs up your repetitive form stresses. Let’s see how it works!
Building an Uber-er Form
UberForms automatically generate all of the standard boilerplate HTML that goes around your forms. By wrapping everything up in an easily style-able package, it becomes a much easier business to make new forms as well as re-use form styling across projects. With the form markup taken care of, you can focus on the more important aspects of your UI building and keep your views deadly clean.
While UberForms are available as a standard form builder (Uberkit::Forms::Builder), you may find it more useful in its helper form (automatically available when the UberKit plugin is loaded:
<% uberform_for :user do |f| %>
  <%= f.text_field :login %>
  <%= f.password_field :password %>
  <%= f.submit "Submit"%>
<% end %>
This will automatically be translated into some nice, CSS-ready HTML:
<form method="post" class="uberform" action="/users">
  <div class="field_row">
    <label for="user_login">Login:</label>
    <input type="text" size="30" name="user[login]" id="user_login" class="text_field"/>
    <br/>
  </div>
  <div class="field_row">
    <label for="user_password">Password:</label>
    <input type="password" size="30" name="user[password]" id="user_password" class="password_field"/>
    <br/>
  </div>
  <button type="submit">Submit</button>
</form>
You can also change the label, add a description or help text to a field by adding the relevant options:
<%= f.text_field :login, :label => "Username", 
                         :help => "Only a-z and underscores.", 
                         :description => "The name you will use to log in." %>
Becomes…
<div class="field_row">
  <label for="user_login">Username:</label>
  <input type="text" size="30" name="user[login]" label="Username" id="user_login" help="Only a-z and underscores." description="The name you will use to log in." class="text_field"/>
  <span class="help">Only a-z and underscores.</span>
  <span class="description">The name you will use to log in.</span>
  <br/>
</div>
Finally, you can create custom HTML inside an UberForm field by passing a block:
<% f.custom :label => "State", :for => "user_state" do |f| %>
  <%= state_select :user, :state %>
<% end %>
Becomes…
<div class="field_row">
  <label for="user_state">State:</label>
  <div class="pseudo_field">
    <select id="user_state">...</select>
  </div> 
  <br/>
</div>
Easy, right? That’s all there is to it, now you can be UberForming to your heart’s content
Installation
To install the UberKit (which includes more than just forms) you can do so either as a gem or a traditional plugin. As a gem, just add this to your environment.rb:
config.gem 'mbleigh-uberkit', :lib => 'uberkit', :source => 'http://gems.github.com'
As a traditional Rails plugin:
script/plugin install git://github.com/mbleigh/uberkit.git

The Future of the UberKit
These two pieces are pretty helpful, but there’s more coming for the UberKit. Stay tuned for more updates, including more hooks and ways to customize the UberKit to fit your needs as a developer.

  



UberKit: Building a Rails UI Swiss-Army Knife
2008-07-07T00:00:00-07:00
So many of components we build into our web applications have a grain of an extractable element, a standardization waiting to happen. Starting today, I am putting together a “Standard UI Kit” for all of the tools that help me build interfaces faster. Together, they are called the UberKit. This week, the first segment is coming: UberMenus.
UberMenu: Abstract Menu Generation
Most people who build interfaces will build their menus with the same structure over and over. I finally took the time to abstract this out into a single helper that can pretty much serve all of my navigational needs. Here’s how you use it in a view:
<% ubermenu do |m| %>
  <% m.action 'Home', '/' %>
  <% m.action 'Users', users_path %>
  <% m.action 'Log Out', logout_path, :class => "special" %>
<% end %>
Becomes this HTML (assuming you’re at the document root):
<ul>
  <li class="first current first_current"><a href="/">Home</a></li>
  <li><a href="/users">Users</a></li>
  <li class="special last"><a href="/logout">Log Out</a></li>
</ul>
The current class will automatically be set on whichever page responds to the built-in Rails helper current_page? and the action syntax behaves just like a link_to. If a given action has multiple classes, they will also be joined with underscores as an additional class for browsers that do not support multiple class declarations. But in addition to easily creating simple menus, you can also easily generate multi-level navigation menus:
<% ubermenu 'nav' do |m| %>
  <% m.action 'Home', home_path %>
  <% m.submenu 'Services', services_path do |s| %>
    <% s.action 'Service A', service_path('a') %>
    <% s.action 'Service B', service_path('b') %>
  <% end %>
<% end %>
Which will become this HTML:
<ul id='nav'>
  <li class='first current first_current'><a href="/">Home</a></li>
  <li class='last'><a href="/services">Services</a>
    <ul>
      <li><a href="/services/a">Service A</a></li>
      <li><a href="/services/b">Service B</a></li>
    </ul>
  </li>
</ul>

Installation
UberKit is available both as a gem and a traditional plugin. For the gem version, add this to your environment.rb:
config.gem 'mbleigh-uberkit', :source => "http://gems.github.com/", :lib => "uberkit"
Or as a traditional plugin:
script/plugin install git://github.com/mbleigh/uberkit.git

Future of the UberKit
While UberMenu is a useful tool, the UberKit will continue to grow over time, so stay tuned for additions (next on the slate: UberForm). It may also grow to include some common styles and javascripts that can be used in conjunction with the helpers to provide an even easier track to a full-fledged UI.
Resources
As always, the source is on GitHub and there is an Acts As Community Profile available as well. If you have any problems with it or would like to request new features, enter them on the Lighthouse project.

  



What the World Needs Now is CSS3
2008-07-02T00:00:00-07:00
The discussion around HTML 5 has been heating up recently, with people advocating to get it finalized and implemented sooner rather than later (and lamenting the ulterior motives of major browser vendors in lobbying for specs). I simply can’t get passionate about this fight, much as I’ve tried. While some of the things that HTML 5 offers will certainly be a boon for web developers, by and large the issues that it addresses (in terms of interactivity) are surmountable simply by using the excellent Javascript libraries we’ve all become dependent upon. The next version of the CSS specification, however, is an entirely different story.
I recently started a new project and as an experiment decided to play with using the non-final border-radius implementations available in Firefox and Safari. After using it for about 15 minutes, I decided that I would simply forgo rounded corners in the interface for Internet Explorer. After using it for three days, I am wondering why every designer and developer on the internet isn’t simultaneously demanding immediate forced adoption of CSS3.
Styling is Fun Again
Our interfaces and style tastes have grown much more complex as the web has grown up, but the tools we use to implement those styles haven’t been keeping up. It shouldn’t feel like a trip to the dentist just to get a box to have some rounded edges. It shouldn’t be a nightmare to try to use translucent pngs for overlays (admittedly this has nothing to do with CSS3 and everything to do with IE6, the browser that won’t die no matter how much we pray).
I can tell you that styling on the edge doesn’t just feel good, it feels amazing. I’m able to implement in a few seconds what I might otherwise spend three hours styling while polluting my markup with hack tags.
Rounded Corners: Nemesis of Designers Everywhere
There is no good way to make rounded corners. The javascript libraries are buggy, images are limited in practicality, and getting it just right in all browsers is downright painful and usually ends up with markup something like this (and a whole mess of CSS to go with):
<div class='rounded'>
  <div class='tl'>
    <div class='tr'>
      <div class='bl'>
        <div class='br'>
          So much for semantics...
        </div>
      </div>
    </div>
  </div>
</div>
In the CSS3 specification, the same effect is achievable like so:
.rounded { border-radius: 10px; }
But it’s not just a convenient way to shortcut the hacks to which we’ve all grown accustomed, it opens up entirely new possibilities for design that would simply not be worth the effort to hack without it.
Lead By Example
Let me explain what I mean by example. Form design has always been one of the trickiest parts of web design, what can we do with a little CSS 3 magic? Let’s say we have a simple form that takes a person’s name:
<form id='sample_form'>
  <label for="name">First Name:</label>
  <input type='text' name="name" id="name"/><br/>
  
  <label for="name">Last Name:</label>
  <input type='text' name="name" id="name"/><br/>
  
  <button type="submit">Submit</button>
</form>
Simple enough, this turns out looking something like this:

Now we can add some standard CSS to make it look a little more acceptable:
label {
  display: block;
  float: left;
  width: 100px;
  font-weight: bold;
  padding: 4px 5px;
  font-family: Verdana, sans-serif;
  font-size: 12px;
  margin-bottom: 5px;
  clear: both;
  text-align: right;
}

input {
  font-size: 12px;
  margin-bottom: 5px;
}
button {
  margin-left: 115px;
  margin-top: 10px;
}
And our result is a perfectly usable form:

But what if we use just a taste of what CSS3 has to offer? We can make a form that looks completely unique without using a single image:
label {
  display: block;
  float: left;
  width: 100px;
  padding: 4px 5px;
  border: 2px solid #037;
  background: #06a;
  color: #fff;
  font-family: Verdana, sans-serif; 
  font-size: 12px;
  margin-bottom: 5px;
  font-weight: bold;
  clear: both;
  text-align: right;
  border-radius: 13px;
  border-top-right-radius: 0px;
  border-bottom-right-radius: 0px;
}

input {
  background: #fff;
  border: 2px solid #8ac;
  border-left: 0px;
  padding: 5px 5px;
  margin-top: 0;
  margin-bottom: 5px;
  margin-left: 0;
  border-radius: 5px;
  top-left-radius: 0px;
  border-bottom-left-radius: 0px;
}

button {
  background: #080;
  color: #fff;
  border: 2px solid #060;
  font-size: 12px;
  font-weight: bold;
  margin-left: 112px;
  padding: 5px 10px;
  border-radius: 13px;
}
It’s a hefty chunk of code, but anyone experienced in writing CSS can knock something like that out in about five minutes. The result is well worth it:

This kind of styling opens up with the application of just a single new attribute from the CSS3 draft specifications. Designers have had to hack, cheat, and wrangle every semi-complex interface that has been developed in the last 5 years thanks to the limitations of CSS (and more specifically the limitations of Internet Explorer), but it doesn’t have to stay that way forever.
State of the Browser
The complete CSS3 spec is not coming to a browser near you any time soon (more accurately not all browsers), and that’s a real shame. It brings to the table powerful new tools that can really enable the kind of semantic markup that we all wish was possible with today’s browsers. Rounded corners are just the “tip of the iceberg”; once CSS3 sees widespread adoption, interface design will take a leap forward unlike any it has seen before.
In the meantime, keep an eye out on the WebKit Nightlies for cutting edge CSS implementations (just added: CSS Variables). Five years from now we’ll look at the troubles we used to have and laugh. Until then, a person can dream…

  



Using RSpec and Autotest While Writing Rails Plugins
2008-06-25T00:00:00-07:00
RSpec is a great tool that has come to replace Test::Unit for many Rails developers. Autotest makes it go even faster, and has become an indispensable part of my development environment. However, it has always been somewhat-to-extremely difficult to use RSpec when developing Rails plugins. In this post I will walk through step-by-step how to get RSpec and Autotest working with your plugin.
This plugin is assuming that you are running Rails >= 2.1 and have already installed RSpec and RSpec::Rails as plugins in your Rails project like so:
script/plugin install git://github.com/dchelimsky/rspec.git
script/plugin install git://github.com/dchelimsky/rspec-rails.git
And also gotten RSpec up and running by calling script/generate rspec.
Generate It
Luckily, I wasn’t the first person who ever wanted to create a plugin that was tested with RSpec. The Rspec Plugin Generator will do most of the heavy lifting for us when we start out. Just install it like so:
script/plugin install git://github.com/pat-maddox/rspec-plugin-generator.git
And you’re ready to get started. I’m assuming here that this is a brand new plugin, if it’s already in development you may need to run this in a fresh directory and then copy/paste files as needed to glue it together. Let’s say I’m writing a plugin called new_fu. I can generate an RSpec-ready plugin simply by calling:
script/generate rspec_plugin new_fu
This will generate the standard plugin structure as well as some extra files:
create  vendor/plugins/new_fu/spec
create  vendor/plugins/new_fu/spec/spec_helper.rb
create  vendor/plugins/new_fu/spec/new_fu_spec.rb
You can take a look at these to see how they work, but pretty simply they hook your plugin up so that it can be run with rake spec:plugins. Let’s add a simple example to our new_fu_spec.rb file:
require File.dirname(__FILE__) + '/spec_helper'

describe "NewFu" do
  it "should have a pending spec"
end
Now if you run rake spec:plugins you should see one pending spec. Congratulations, your plugin is now running on RSpec!
Autotest Like a Champ
Ok, so now we’re up and running with RSpec on our plugin. That’s great, but if you have several plugins in the same Rails app that all have specs, it starts to get messy when you run that rake spec:plugins. Not to mention how long it takes between runs! We need to get an autotest setup like we have for our main Rails app!
I struggled with getting this to work for a long time, so thanks to this post on Rails Symphonies for finally pointing me in the right direction. First we need to create an autotest/discover.rb file in our plugin’s lib directory. In that file, put this code:
$:.push(File.join(File.dirname(__FILE__), %w[.. .. rspec]))  
   
Autotest.add_discovery do  
  "rspec" 
end
This gets us almost exactly where we want to be. However, the first time I ran it I had two problems: some specs that I had written were strangely failing, and it wasn’t in color or following the rest of my spec.opts preferences from my main app!
To remedy this, we need a spec.opts in the spec directory of the plugin. You can either copy and paste it in from your Rails app (my recommendation if you are publishing your plugin) or you can just create a softlink back to it:
ln -s ../../../../spec/spec.opts spec.opts
That’s it! Now if you run autotest you should be running all of the specs for your plugin just as you would if you were running them for your app. Note that this doesn’t hook in to your app’s autotest, which may be desirable or undesirable to your specific needs.

  



SubdomainFu: A New Way To Tame The Subdomain
2008-06-23T00:00:00-07:00
An extremely common practice for Rails applications is to provide keyed

access through subdomains (i.e. http://someaccount.awesomeapp.com/). However,

there has never been a real unified convention for handling this functionality.

DHH’s Account Location

works for some circumstances but is more tailored for a Basecamp domain model

(i.e. the app is on a separate domain from all other functionality, so you

can always expect a subdomain) than the more common usage of one domain only.
SubdomainFu aims to provide a simple, generic toolset for dealing with subdomains

in Rails applications. Rather than tie the functionality to something specific

like an account, SubdomainFu simply provides a foundation upon which any

subdomain-keyed system can easily be built.
Usage Fu
SubdomainFu works by riding on top of the URL Rewriting engine provided with

Rails. This way you can use it anywhere you normally generate URLs: through

url_for, in named routes, and in resources-based routes. There’s a small

amount of configuration that is needed to get you running (though the defaults

should work for most).
To set it up, you can modify any of these settings (the defaults are shown):
# in environment.rb
  
# These are the sizes of the domain (i.e. 0 for localhost, 1 for something.com)
# for each of your environments
SubdomainFu.tld_sizes = { :development => 0,
                          :test => 0,
                          :production => 1 }

# These are the subdomains that will be equivalent to no subdomain
SubdomainFu.mirrors = ["www"]

# This is the "preferred mirror" if you would rather show this subdomain
# in the URL than no subdomain at all.
SubdomainFu.preferred_mirror = "www"
Now when you’re in your application, you will have access to two useful

features: a current_subdomain method and the URL Rewriting helpers.

The current_subdomain method will give you the current subdomain or

return nil if there is no subdomain or the current subdomain is a mirror:
# http://some_subdomain.myapp.com/
current_subdomain # => "some_subdomain"

# http://www.myapp.com/ or http://myapp.com/
current_subdomain # => nil

# http://some.subdomain.myapp.com
current_subdomain # => "some.subdomain"
The URL rewriting features of SubdomainFu come through a :subdomain option

passed to any URL generating method. Here are some examples (in these examples,

the current page is considered to be ‘http://intridea.com/’):
url_for(:controller => "my_controller", 
  :action => "my_action", 
  :subdomain => "awesome") # => http://awesome.intridea.com/my_controller/my_action
  
users_url(:subdomain => false)  # => http://intridea.com/users

# The full URL will be generated if the subdomain is not the same as the
# current subdomain, regardless of whether _path or _url is used.
users_path(:subdomain => "fun") # => http://fun.intridea.com/users
users_path(:subdomain => false) # => /users
While this is just a simple set of tools, it can allow the easy creation

of powerful subdomain-using tools. Note that the easiest way to locally

test multiple subdomains on your app is to edit /etc/hosts and add

subdomains like so:
127.0.0.1	localhost subdomain1.localhost subdomain2.localhost www.localhost
Adding an entry for each subdomain you want to use locally. Then you need

to flush your local DNS cache to make sure your changes are picked up:
sudo dscacheutil -flushcache
Installation
SubdomainFu is available both as a traditional plugin and as a GemPlugin

for Rails 2.1 and later. For a traditional plugin, install like so:
script/plugin install git://github.com/mbleigh/subdomain-fu.git
For a GemPlugin, add this dependency to your environment.rb:
config.gem 'mbleigh-subdomain-fu', :source => "http://gems.github.com/", :lib => "subdomain-fu"
Implementing A Simple Account Key System
Let’s take this functionality and implement a simple account-key system based

off of the subdomain. We’ll start with some controller code (assuming that

we have an Account model with a ‘subdomain’ field):
class ApplicationController < ActionController::Base
  protected
  
  # Will either fetch the current account or return nil if none is found
  def current_account
    @account ||= Account.find_by_subdomain(current_subdomain)
  end
  # Make this method visible to views as well
  helper_method :current_account
  
  # This is a before_filter we'll use in other controllers
  def account_required
    unless current_account
      flash[:error] = "Could not find the account '#{current_subdomain}'"
      redirect_to :controller => "site", :action => "home", :subdomain => false
    end
  end
end
That’s really all we need for a basic setup, now let’s say we have a

ProjectsController that you must specify an account to access:
class ProjectsController < ApplicationController
  # Redirect users away if no subdomain is specified
  before_filter :account_required
end
There’s lots more you can do with the plugin, but this is a simple use case

that everyone can relate to.
Resources and Plans
A feature that I hoped would make it to the first release of SubdomainFu

but is now a planned feature is subdomain-aware routing so that you can

add conditional subdomain routes to your routes.rb file. Keep an eye

out for more on that in the future.
In the meantime, the project will live at its home on Acts As Community for intermittent

updates, is available on GitHub as always, and bugs/feature requests may

be passed on through the Lighthouse.

  



GemPlugins: A Brief Introduction to the Future of Rails Plugins
2008-06-11T00:00:00-07:00
The new Gem Dependencies of Rails 2.1 give developers an easier-than-ever ability to keep track of and maintain the various library dependencies inherent with any project. However, a much-overlooked additional feature of the Gem Dependencies is the ability to package traditional Rails plugins as a gem and have them hooked in properly. This article is designed as an introduction to how to write and use plugins as gems in Rails projects.
The Basics
The basic method by which this is achievable is that any plugin included through a config.gem command will automatically have the gem-packed file rails/init.rb run upon Rails’s initialization. All it takes is a little bit of effort, and any Rails plugin can be packaged as a gem and easily depended upon through gem dependencies.
You may be wondering why this is a “big deal.” Plugins are already dead simple to install in Rails (and you can even script/plugin install straight from Git now!), why do we need GemPlugins? It’s simple, really: RubyGems are a rock-solid established way of easily distributing versioned reusable bits of code. Using gems for plugins allows for a greater standardization of the way in which plugins are maintained and distributed, as well as a simple path for version-locking to ensure compatibility with legacy code etc.
Another reason that GemPlugins are important is that they provide a level of abstraction from Rails: by releasing a gem rails/init.rb you could also use the same exact code to release a Merb plugin or any other framework that supports gemified add-ons. I think you will begin to see a number of cross-framework plugins be developed as Rails gets some company and shares alike.
Using a GemPlugin
First, let’s go through the process required to use an existing gem plugin. I’m going to be using my Acts As Taggable On plugin as an example throughout because I just recently went through the process of making it available as a gem.
First, you will need to include the dependency in your environment.rb file. I’m assuming here that most plugins are going to be hosted on GitHub, but the same should be true for any gem source.
# in environment.rb
  
config.gem "mbleigh-acts-as-taggable-on", :source => "http://gems.github.com", :lib => "acts-as-taggable-on"
This is the standard usage of gem dependencies, and for more info on this you can see Ryan Daigle’s post or watch the RailsCast on the subject. Now assuming that you don’t already have the gem in question installed, it’s simple to grab it:
rake gems:install
This will automatically install any gem dependencies in your project, and will tell you what’s happening the same as if you had run gem install from the command line.
That’s it! Once you have successfully installed the necessary gem, you can simply start up your Rails server and the plugin will be loaded and initialized as though it were living in your vendor/plugins directory.
Now that you know how to use a GemPlugin, I’ll show you how you can take an existing plugin and gemify it quickly and painlessly.
Making a GemPlugin
Let’s say I have a plugin called awesome_fu that lives on GitHub at mbleigh/awesome-fu. I’ve already released this plugin, it works great, and now I want to make it compatible with GemPlugins.
First, let’s create a gemspec called awesome-fu.gemspec in line with the requirements for the GitHub Gem Repository. In order to make the file list, I usually find it’s easiest to “find **” in the plugin directory, then copy it into TextMate, make the modifications I need for manifest (using a regular expression to quote each of the files), and saving it in the spec. If you have only a few files in your plugin, it may be easier just to add them by hand.
Next we need to add rails/init.rb. This is a little bit troublesome, because we still want our plugin to work if installed through the traditional method, so we also need init.rb to run the same code (this is automatically fine in edge Rails). What I did for my plugin is copy all of my init.rb code into rails/init.rb and then change init.rb to the following:
require File.dirname(__FILE__) + "/rails/init"
Now they both run the same code without any kind of replication, great! This means that now I have set up my plugin to work equally as a GemPlugin or a traditional plugin with just a couple minutes of work.
All that’s left to do is switch on the RubyGem setting for my GitHub project, update the README, and push! Now anyone will be able to easily require the plugin as a gem dependency and you will get all of the accolades associated with releasing your plugin the “new and hip” way.
Caveat Coder
The one problem with GemPlugins that I have run into is that if you unpack your gems using “rake gems:unpack” the rails/init.rb file is not run on initialization. This is a known issue that is supposed (?) to be resolved but I have still experienced this problem in my experiments. Hopefully this issue will be fully resolved in edge Rails soon and the glorious future of GemPlugins can begin.

  



ActsAsTaggableOn Grows Up
2008-06-09T00:00:00-07:00
Acts As Taggable On (original post here), the tagging plugin with custom tag contexts, has gathered up some great new features over the past weeks thanks to the efforts of the community as well as fellow Intrideans Pradeep Elankumaran and Brendan Lim. I just wanted to take this opportunity to go over some of what’s new and interesting in the world of acts_as_taggable_on.
Community Fixes
First, Peter Cooper was kind enough to submit a patch that allows acts_as_taggable_on to work with Rails 2.1’s named_scope when using find_options_for_tag_counts.
Secondly, the much requested support for Single Table Inheritance is finally in! It was just a matter of using a class inheritable attribute instead of a class instance variable, and big thanks to slainer68 for hunting that down and taking the time to submit a patch.
If there’s anything you’ve hacked on to Acts As Taggable On, I urge you to submit a patch to the Lighthouse Project. I try to get new patches integrated into the codebase as quickly as possible, so please do submit anything!
During the Community Code Drive at RailsConf two great features were added: taggers and related objects.
Taggers
Tags can now have ownership, allowing for such things as User-tracked tags and more. This was a requested feature and something that I’d been looking forward to myself. Here’s the usage:
class User < ActiveRecord::Base
  acts_as_tagger
end

class Photo < ActiveRecord::Base
  acts_as_taggable_on :locations
end

@some_user.tag(@some_photo, :with => "paris, normandy", :on => :locations)
@some_user.owned_taggings
@some_user.owned_tags
@some_photo.locations_from(@some_user)
Find Related
Another request (and another great idea) is the ability to find related objects by similar tags. This is now available through the @object.find_related_on_tags syntax:
@bobby = User.find_by_name("Bobby")
@bobby.skill_list # => ["jogging", "diving"]

@frankie = User.find_by_name("Frankie")
@frankie.skill_list # => ["hacking"]

@tom = User.find_by_name("Tom")
@tom.skill_list # => ["hacking", "jogging", "diving"]

@tom.find_related_on_skills # => [<User name="Bobby">,<User name="Frankie">]
@bobby.find_related_on_skills # => [<User name="Tom">] 
@frankie.find_related_on_skills # => [<User name="Tom">] 
Gemified!
Acts As Taggable On now works as a GemPlugin in Rails. This is a new way (as of Rails 2.1) of distributing plugins as gems and having them still automatically link up and do their magic. To use it as a gem, add it to your config/environment.rb like so:
config.gem "mbleigh-acts-as-taggable-on", :source => "http://gems.github.com", :lib => "acts-as-taggable-on"
Now you should be able to get the latest version of the plugin just by running rake gems:install. However, this hasn’t been working for me so the alternative is just to install the gem directly:
gem install mbleigh-acts-as-taggable-on --source http://gems.github.com/

Now when you run your Rails app, even though it’s not in vendor/plugins it should be running! To make sure, look for this line on startup:
** acts_as_taggable_on: initialized properly

There are still a couple of issues outstanding in Rails regarding GemPlugins (if you unpack it, it will not run the initialization properly for some reason), but I wanted to give everyone the latest and greatest way to install the plugin possible. It will still work fine using the conventional methods as well.
Community and Future
I’ve been really happy with the response and support of the community, and I would like to do everything possible to cultivate future participation. To that end, I have created an Acts As Community Project for acts_as_taggable_on that will hopefully provide some casual communication about the project. Feel free to post on the wall or in the forums, and look out for additions soon.
Finally, the area of the plugin that still needs some work is tag caching. This is not a particular area of my expertise, so I’m hoping that someone from the community will write up some specs that flesh out the caching functionality in new and interesting ways.
Thanks for all of the patches, and I hope you continue to enjoy using Acts As Taggable On!
UPDATE (6/10/08): The improvements keep on rolling! After writing the post, I went off on a tangent and decided to make the plugin work both traditionally and as a gem. See more details above in the “Gemified” section.