MetaSkills.net - Home

Code-O-Lanterns: What Scares You?

2008-10-13T19:52:00Z

While reading the The Unofficial Apple Weblog today I noticed this sweet little Jack-O-Lantern screensaver for OS X. After some feedback on the 757.rb group, I decided to make some Code-O-Lanterns.

Follow the instructions for the Jack-O-Lantern screensaver on where to put the carving files. If you are not on a Mac, I have taken some screen shots that you can use for desktop pictures. If you would like to see a code o lantern that is not up... just ask for one, providing it has a logo!

While reading the The Unofficial Apple Weblog today I noticed this sweet little Jack-O-Lantern screensaver for OS X. After some feedback on the 757.rb group, I decided to make some Code-O-Lanterns.

Code-O-Lanterns Files

Plug It In Plug It In

2008-10-11T01:52:00Z

I've been busy putting together some plugins form misc work. If you did not catch my latest article Jack has_many :things where I covered GroupeScope, by all means check it out. I've also just finished up a pretty solid backport of NamedScope that can be found on my Github page. It bills itself as a well tested complete back port for rails 1.2.6 and 2.0.4.

One thing that has been a real help while I've been developing these plugins is this autotest class I put together specifically for developing rails plugins. I even got mention on rubyonrails.org. Sweet! More to come.

Resources

The NamedScope plugin.
The GroupedScope plugin.
The RailsPlugin class for Autotest.
Vilcus plug dactyloadapter. Developed specially for people who enjoy closing electrical circuits with their own fingers.

Jack has_many :things

2008-09-28T19:34:00Z

I am Jack's sofa, stereo and wardrobe... I make Jack's life complete. I reside in a ActiveRecord table called "things" and Jack is the only one that has the key. This is Jack's life, and it's ending one minute at a time.

As rails developers, we have done this simple relationship over and over again. I'm sure the has_many association is by far the most common in app/db design. It gives a single resource quick and easy access to others, but as your application grows, and depression sets in...

It's cheaper than a movie, and there's free coffee.

I am talking about groups. Not the underground ones that carve us out of wood, but ones where we share with those around us. This is healing. The time has come to for our objects to do the same, but how?

The problem is that the ActiveRecord has_many association is scoped to an individual. No matter what conditions are tacked on, they are always pwned by the proxy owner. The things they own have ended up owning you! Sure we could model some groupable schema and go through it, ActiveRecord is beautiful that way. But what about our hard work in all those existing has_many associations and named_scopes?

I felt like destroying something beautiful.

The solution is on everyone's face, it is on the tip of everyone's tongue. I just gave it a name. It is called GroupedScope and it will fundamentally change the constructed SQL for the has_many associations you want to share. The best part is that it will leave those associations untouched for continued use. GroupedScope even works with your existing association extensions and any named scopes. Let's have a session.

First we need to install the plugin.

./script/plugin install git://github.com/metaskills/grouped_scope.git

Now let's open up our Person model and schema, so Jack can share.


class PeopleCanChooseAGroup < ActiveRecord::Migration
  def self.up
    add_column :people, :group_id, :integer
  end
  def self.down
    remove_column :people, :group_id
  end
end


class Person < ActiveRecord::Base
  has_many :things
  has_many :acquaintances
  has_many :problems
  grouped_scope :things, :problems
end

@jack = Person.find_by_name('Jack')
@bob  = Person.find_by_name('Bob')

@jack.update_attribute :group_id, 1
@bob.update_attribute :group_id, 1

Every Person object in our app is now ready to share their :things and their :problems. I have also just arbitrarily put Jack and Bob into the same group. Declaring grouped_scope in the model generates a new group instance method that will allow us to iterate over its members.

12	@jack.group # => [#<Person id: 1, name: "Jack", group_id: 1>, #<Person id: 2, name: "Bob", group_id: 1>]

We all started seeing things differently.

The object returned by the group method, an instance of GroupedScope::SelfGrouping, is far cooler than you think. It looks and acts as an enumerable array, but in reality it is a proxy object that can delegate to generated grouped association reflections which mimic their originals. Essentially giving the group access to all associated objects of its members, in this case their :things and :problems. Did I loose you?


@jack.problems.size   # => 6
@bob.problems.size    # => 2

@bob.group.problems        # => [#<Problem...>,#<Problem...>,#<Problem...>,#<Problem...>,....]
@bob.group.problems.size   # => 8
@jack.group.problems.size  # => 8

Without going into the detail of Jack's and Bob's problems, we can see that within the group, they are all shared. This is what the GroupedScope plugin is really all about. It allows existing has_many associations to be called on the group which changes the SQL generated to be owned by the group, essentially from id = 1 to id IN (1,2).

The way it accomplishes this is pretty sweet. GroupedScope creates an association reflection and accessor that will proxy all critical reflection calls back to the original association reflection. This means that it can be really smart and maintain all the logic in the existing association which could include custom options like :class_name, :foreign_key, :though, and :extend, very handy for legacy/custom associations. It also lets you chain named scopes on the grouped scope. Here is very contrived example:


class Person < ActiveRecord::Base
  has_many :mental_issues, :class_name => "MentalState", :foreign_key => :name do
    def dangerous
      find :all, :conditions => {:snap_tolerance => 10}
    end
  end
  grouped_scope :mental_issues
end

class MentalState < ActiveRecord::Base
  named_scope :treatable_by, lambda { |doctor| 
    {:conditions => {:doctor_id => doctor.id}}
  }
end

@jack.group.mental_issues.dangerous.treatable_by(@doctor) # => [#<MentalState...>,#<MentalState...>]

This is probably one of those "cry for help" things.

The GroupedScope plugin is not done. It is however well tested and can do what I have outlined in both rails 1.2.6 and 2.1.1. I have marked some TODO's in the project README but I thought I would cover a few here in detail.

First, every model that declares grouped_scope also generates a belongs_to :grouping association that can be used to get to the GroupedScope::Grouping object. This object has no underlying schema and is not being used right now. Eventually this will be the place where you write your own evil twin plugin that defines your business logic to what a group (not the selfgrouping proxy) can do. For now, it would be a good idea to generate a "groupings" table and create rows and use those IDs when assigning group_ids.

Also, you may have noticed that GroupedScope focuses on a single group and that no single owner can essentially have many groups. I think at some point I might like to see this and work like all the examples above. Have other ideas? Send me an email. I'm ken at this domain dot com.

I'd like to thank the Academy.

Using Autotest For Rails Plugin Development

2008-09-19T17:46:00Z

I love autotest. I have event posted before how to extend the idea of autotest sounds to a red/green playlist but now that I am taking more time to extract some of my work to plugins, I really wanted autotest to come with me. The problem is that the default autotest mappings do not play with rails conventions, the biggest being that test files for a lib match the name of the lib with _test.rb at the END of the...

Today I posted a new project to my Github account, called Autotest::Railsplugin. This project should be a great start for fleshing out all the typical mappings, ignore, libs, etc. that autotest needs to know about when developing a rails plugin. I invite you to download it and give it a try and provide feedback on missing details.

To Install

Download
Rename the directory to "autotest"
Place inside of your plugin’s root directory.
From your plugin root, you can now use autotest.

$ autotest
  loading autotest/railsplugin

By default, autotest will scan your present working directory for an autotest folder that has a discover.rb in it. So it should find and display the loading autotest/railsplugin which means it found the plugin class just fine. If this is not the case make sure you have the directory named correctly. If you have a conflicting autotest directory for some reason you can always force the plugin class, again assuming you have it in the right, place using:

$ autotest -railsplugin

Resources

Going Horizontal On The Multicade

2008-09-14T18:31:00Z

A few months ago I "invested" in a upright Galaga multicade. This is no costly refurb/restoration unit, but rather a customized new build from a great company called Arcadeshop Amusement. This place does two great things. First they will manufacturer/build you a new cabinet of your liking with all the parts professionally installed. This includes the display, JAMMA harness, coin door assembly, control panel, and all artwork. I chose a classic Galaga/Ms.Pacman/Midway cabinet with a 19" CRT display. My only deviation from the Galaga theme was a multicade control panel that had a 4-way joystick and two buttons for the left or right handed.

The second thing about this great company is that sell one of the coolest Multicade JAMMA PCBs I have seen. This board is programmable with a standard serial cable to run game ROM's in their approved list and that included such greats that I wanted like Galaga, Donkey Kong, Ms.Pacman, and Phoenix. For the record... I am not going after Billy Mitchell's record. I just wanted a nice...

So these games held me over for a time, but I really wanted to be a bit more flexible with the option to play some horizontal games. To that end, I invited my friend and fellow 757.rb'er Geoff Parsons over to help me rotate my CRT. Before we got to that jun part, I had to manufacture my own horizontal cross members to hold the display. Thankfully a trip to LOWES steel part section and a new hack saw yielded a very decent support system, see here. The icing on the cake after we remounted the CRT was to replace the 4-way joystick with a new 4/8-way super stick from HAPP Controls, a new 19-in-one JAMMA PCB from Lizard Lick, and a new monitor bezel for the horizontal display. Now with this PCB, I am enjoying games like Super Mario Bros, Gradius, and Defender.

For those that may ask, why did I not go with some sort of MAME system. Sometimes options are good... but too many are distracting. I really like the idea of having as much as my multicade mimic the old arcade cabinet as possible, and hacking on another computer to do that was not in the cards. I love just slapping in a JAMMA board and having the set of games I like. Low-tech fun!

Hell'OO HomeMarks

2008-08-18T01:22:00Z

Well HomeMarks v2.0 is done and ready for the public. You can download it from my Github project page. It has a real simple rake app:bootstrap task that I came up with over the weekend will have you running a local copy in only a few seconds, give it a try. Sometime over the next few days, I'll move over the live site to this code base too. If you have not yet kept up on the implementation mantra I set down for the HomeMarks v2 project, you might want to read an older post as well as this excerpt from the project README.

HomeMarks was built using the Ruby on Rails framework with a heavy emphasis on object oriented JavaScript to make AJAX requests to a RESTful back-end. Unlike most Rails applications it does not use any inline JavaScript helpers nor does it rely on RJS (Remote JavaScript) for dynamic page updates. Instead it is nearly 100% unobtrusive JavaScript which uses simple HEAD or JSON responses to communicate to the objects on the page. This has yielded very slim controller code which is decoupled from the views and easily testable in isolation at a functional level.

So what do I think of this implementation and writing all this object oriented JavaScript? Well – its been real hard, I've been in JS Hell-OO for the better part of a few weeks as I came closer to finishing the project. Coming from a self inflicted addiction to unit/functional testing in rails, it is very hard to get into the habit of opening the browser to test view code. A big part of me hates writing all this JS without one bit of unit testing. I've heard that Prototype v2 will have unit testing, that would be awesome!

So, bitching aside, I am very happy that my JS-fu is stronger. The end result besides all those buckets of water up the hill is that I can now really appreciate the ruby object model and how prototype strives to make JS class construction follow its example. Kudos really goes to Sam Stephenson for bridging the two object models. As I learned more about how prototype's classes work, I actually learned quite a bit about ruby too. Using that knowledge I gave a talk at the Hampton Roads Ruby Users Group (757rb) on the topic. You can download the PDF version of the slides from the files section of the Google group page. Look for the file titled OO JavaScript Class Construction

Stop Exception Notifications With The ZombieShotgun

2008-07-06T19:14:00Z

I am all about knowing how to survive a zombie invasion – as much as I am a firm believer of using the right tool for the a given job. It can not be argued that killing zombies with a shotgun to the head is as natural a fit as peanut butter to chocolate. They simply just go together.

I am all about knowing how to survive a zombie invasion – as much as I am a firm believer of using the right tool for a given job. It can not be argued that killing zombies with a shotgun to the head is as natural a fit as peanut butter to chocolate. They simply just go together.

Now real zombies may not be a daily nuisance, but computer zombies are a daily pain in the butt to network administrators as well as software engineers alike. If you have ever deployed a rails application into production that used some sort of exception notification, then you may at some time seen some zombie attacks throw a bunch of exceptions. My solution a few years back was to build my own ZombieShotgun module, see below.

The idea is simple, include the module and add this line to the very top of your filter chain before_filter :shoot_zombies. Just like in real life, if rails detects a zombie attack, it will issue a 404 not found error in the beautiful rails syntax head :not_found. I love it when code models the real world! Please note that there are a ton of better ways to accomplish user agent filtering, most notably, in your web server config... but that does not mean this is not a fun module to use.


module ZombieShotgun
  
  ZOMBIE_AGENTS       = ['Microsoft Office Protocol Discovery','Microsoft Data Access Internet Publishing Provider Protocol Discovery','FrontPage']
  ZOMBIE_ATTACK_DIRS  = ['_vti_bin','MSOffice','verify-VCNstrict','notified-VCNstrict']
  
  protected
  
  def shoot_zombies
    head :not_found if zombie_attack?
  end
  
  def zombie_attack?
    zombie_attack_on_directory? || zombie_agent_attack?
  end
  
  def zombie_attack_on_directory?
    attack = request.path.from(1)
    attack_dir = attack.index('/').nil? ? attack : attack.to(attack.index('/')-1)    
    ZOMBIE_ATTACK_DIRS.include?(attack_dir)
  end
  
  def zombie_agent_attack?
    ua = request.env['HTTP_USER_AGENT']
    !ua.blank? && ZOMBIE_AGENTS.any? { |za| za =~ /#{ua}/ }
  end
  
  
end

RESTful AJAX with Forgery Protection

2008-06-18T02:41:00Z

Writing the new HomeMarks has been a great exercise. I've learned that the AJAX Head <strike>Design Pattern</strike> Implementation is more akin to developing a service-oriented application (SOA) since I have moved all client-side coupling from the controllers, like RJS, and only respond with HEAD or JSON data. Today I learned about Halcyon which is self described as a JSON web application framework built on Rack. If you take a look at their example, it looks a lot like HomeMarks v2, pretty cool!

Getting To The Point

Last week I finally got around to doing the controller CRUD for the user's column objects. The core homemarks/app.js JavaScript class contains the one (and only one) AJAX dispatcher/handler for the entire application. One problem that I ran into was how to continue to use forgery protection in rails to protect from CSRF attacks while relying solely on ad-hoc JavaScript requests to a RESTful back-end. I could have turned off protect_from_forgery but that did not feel right. I wanted RESTful AJAX with forgery protection.

My Solution

Since the HomeMarks v2 app has one AJAX dispatcher/handler for the entire app, all I had to do was to get the authenticity token into each and every request. It took a bit of digging in the rails source to find the methods I wanted but here both the ERB snippet I am using in my layout and the helper method found in my application_helper.rb file.

1234	<script type="text/javascript"> <%= auth_params_js_var %></script>


def auth_params_js_var
  unless RAILS_ENV == 'test'
    %|var authParams = $H({#{request_forgery_protection_token}:#{form_authenticity_token.inspect}});|
  end
end

What does this do? It creates a JS variable called authParams at the window level (right term?) that all other functions can use. That variable returns a JavaScript hash that will have a single key/value pair for the rails authenticity token, see below. Basically at this point all you have to do is merge this hash with your parameters option for your AJAX object. You can reference the HomeMarks app.js file in the resources section if you want to see how I did this on my app, code snippet below too.


  doAjaxRequest: function(elmnt,finishMethod) {
    // ...
    var method = elmnt.method || 'post';
    new Ajax.Request(elmnt.action,{
      onComplete: function(request){
        this.completeAjaxRequest(request);
        if (finishMethod) { finishMethod.call(this,request) };
      }.bind(this),
      parameters: parameters.merge(authParams),
      method: method
    });
  }

Resources

The Latest HomeMarks app.js Class. See doAjaxRequest() function.

Coulda Shoulda Woulda

2008-05-30T03:21:00Z

It has been about 6 months now since I started using the Shoulda testing plugin as my BDD/TDD tool of choice. Unlike a lot of other people, I did not flock to the RSpec bandwaggon. Personally I think RSpec is horribly bloated a sledgehammer for a simple issue, the need to have test code organized with nested setups and context blocks.

If you are new to Shoulda, I highly urge you to take a look at the Thoughbot project page for it. If you have the time take a look at some of their other projects, like Paperclip. These guys are really smart. If you really want to see how shoulda can sing, check out Tammer Saleh's presentation of it at the MountainWest RubyConf 2008. In that presentation he covers how you can extend Shoulda and write your own macros that generate additional tests. This is what my blog post is about.

Sample Shoulda Macro For Functional Require Login

Here is a simple module that you might find for any restful authentication system. This would be included in your main test_helper.rb file where it would add the normal login_as(user) method. The good part I want to point out is the should_require_login(*actions) macro method that shows off a neat example of how you could use Shoulda in your functional tests at the class level.


module AuthSystem
  module TestHelper
    
    def self.included(receiver)
      receiver.extend ClassMethods
      receiver.send :include, InstanceMethods
    end
    
    module ClassMethods
      
      def should_require_login(*actions)
        actions.each do |action|
          should "Require login for '#{action}' action" do
            get(action)
            assert_redirected_to(login_url)
          end
        end
      end
      
    end
    
    module InstanceMethods
      
      def login_as(user)
        if u = users(user)
          @request.session[:user_id] = u.id
        end
      end
      
    end
    
  end
end

Here is how it would look in the controller functional test. These are all contrived examples, but I think it illustrates how Shoulda can be used and in general how you can make your own macros that test at a higher level.


class UsersControllerTest < ActionController::TestCase
  
  should_require_login :edit, :update, :etc
  
end

The "AJAX Head" Design Pattern

2008-05-24T20:00:00Z

This is the first of a few articles covering the total rewrite of the HomeMarks.com code base as I upgrade it to Rails 2.1. The "AJAX Head" pattern is the moniker I have assigned to methodology that has come about during said rewrite and the design decisions I choose early on. The rules were simple...

Total Unobtrusive JavaScript (No Tag Soup)
No RJS Controller Responses

Rails makes it very easy to generate JavaScript with Ruby. The generator methods are extensive and cover both the Prototype and Scriptaculous libraries. The first version of HomeMarks used the generators exclusively to augment both the views and controller responses. In fact, I used a technique that is covered in the latest Advanced Rails Recipes (way before it came out) under the "Replace In-View Raw JavaScript" chapter. Basically I created helper methods that generated JavaScript shared by both the views and controllers. It was a great technique but things got messy quick. So life was good back then, I had a lot of Ruby code and a very dynamic site, but something did not seem right...

What Is The AJAX Head Pattern?

It is an experiment into a vision to see what happens when you make the decision to totally go unobtrusive. Not just in your views but the controllers too! Imagine it this way — your controllers are slim APIs. They should do nothing but render a page on a GET request and when it comes to a POST/PUT/DELETE they should do nothing more than just say YES or NO (with errors).

Now lets think about that. What does that mean for an application that uses exclusive AJAX calls for dynamic page updates? It means that your visual client (the browser) will need to know ALOT less from the controller about what to do. It's great, the browser knows what is on the page, from the GET request, and what it needs to do with it. The client only needs to tell the remote resource store what it did. In this pattern the controller is relegated to nothing more than acting on model data and letting the client know if it succeeded or failed. So in short.

The AJAX head design pattern forces the view and controller to work in isolation with the most minimal coupling possible. Kind of like a web service.

Tools and Code Needed

A application that does just about everything with AJAX.
Fluency with ActionController::Base#head method and HTTP status codes.
Site-wide exception rescues for ActiveRecord::RecordInvalid.
Global client-side AJAX request and response handlers.
Global client-side error handlers.

This may seem like a daunting list, but its pretty simple when you break it down. Let's do each one at at time with some of the current code from HomeMarks. The HomeMarks app is my first check on the list. When I did this app just about EVERYTHING was done via an AJAX call to update the page. Now on to the others.

2) Head And Status Codes

The ActionController::Base#head method and HTTP status codes are the second item on the list. The head method is very useful when you just want to respond with HTTP headers and no body content. This is typical behavior when an app responds to external web services requests. This is important to note, I chose to rely on head responses as a way to meet my design decision of not using any RJS responses from the controller.

The basic usage of the head method is simple, you just pass a symbol to the head method that is the lowercase underscore equivalent to an HTTP status code. For instance, if you wanted to respond with success, choose a status code from the 200 range, the easiest being 'OK', which would look like head(:ok). If you wanted to respond to bad authentication, you might use the 401 code like so, head(:unauthorized). Here is an example from HomeMarks restful user signup action.


class UsersController < ApplicationController
  # ...
  def create
    User.create!(params[:user])
    head :ok
  end
  # ...
end

There is actually a number of things going on in those 2 lines of code above. If the user is created, the AJAX request will get a simple 'OK' message via the head method. Obviously the client will need to know what to do on its own. But if errors happen what to do? This brings us to...

3) Invalid Object Handling

When Rails 2 came out, it gave us a very useful tool for our controllers, the ActionController#rescue_from method. It allows you to delegate exception handling to a method either per controller or site wide for a specific exception class. So enter the RenderInvalidRecord module, show below.


module RenderInvalidRecord
  
  def self.included(base)
    base.rescue_from(ActiveRecord::RecordInvalid, :with => :render_invalid_record)
  end
  
  protected
  
  def render_invalid_record(exception)
    record = exception.record
    respond_to do |format|
      format.html { render :action => (record.new_record? ? 'new' : 'edit') }
      format.js   { render :json => record.errors.full_messages, :status => :unprocessable_entity, :content_type => 'application/json' }
      format.xml  { render :xml => record.errors.full_messages,  :status => :unprocessable_entity }
      format.json { render :json => record.errors.full_messages, :status => :unprocessable_entity }
    end
  end
  
end

Once included in your application.rb file, every ActiveRecord::RecordInvalid exception will be handled by the render_invalid_record method. I use this pattern often and it is the primary reason I always use the bang methods that end with an exclamation point, such as create! or save!. This module above was inspired by Joshua Peek's own module of the same name but has been edited here to fit my needs. Both the "xml" and "html" response formats are not used by HomeMarks but are included here to show how this module can work for any request type.

Now, how this fits into the AJAX Head pattern. The design decision of not having RJS responses means one of two things needs to come from the response. First, if the response is a success, meaning in the 200 range, then it is assumed that the client only needs to know that all is 'OK'. Second, if the request has errors, then the response needs to communicate them. I choose JSON for the format of these errors since all AJAX request objects from Prototype automatically include a application/json accept header. So that is why I changed both the "js" and the "json" response type in the RenderInvalidRecord module to both serialize the objects full error messages into a JSON array with an HTTP status code of 422 "Unprocessable Entity" which seemed to make the most sense to me. This pretty much wraps up the server side part of the pattern. Now onto the client side. Everything from here on is personal taste on how your client will react to an "good" or "bad" response object.

4) Client-Side AJAX Handlers

I can not stress enough how much you have to bake your own functions to handle the client side reaction to both good and bad AJAX responses. The client's ability to know what to do with errors will be tightly coupled to AJAX handlers and the design choices of your site. In the examples below I have broken up methods in the same JavaScript classes to show you the parts for a specific behavior in a more concise manner. Also please note that I am using Prototype module and class organization heavily in HomeMarks. This allows me to build a Base JavaScript module and classes that mimic Rails models which inherit/mixin Base methods. I also use the Scriptaculous Builder class for creating DOM fragments too. Now back to business.

The first part of the AJAX head pattern was to use unobtrusive JavaScript. Because of this design choice, there are no remote_form_for methods in the HomeMarks view code. All forms are simple form_for methods. Below is a sample of the HomeMarksSite JavaScript class that creates AJAX handlers for all site forms. The below example is slimmed down to only show the initialization of this behavior for the signup form. But no matter which form is given this behavior the process is the same.

The form's submit event is handled by startAjaxForm(). It does the following:

Stops the normal submit behavior.
Adds a loading spinner in the #form_loading span.
Creates a new AJAX.Request using the forms own action. It also binds a function to delegate the logic of completing the form when the request is finished. More on that later in #2 below.
Finally it disables the form.

Once a response comes back from the server, the delegateCompleteAjaxForm() function will be called with both the form object and the AJAX request object. The logic of this function includes:

Figuring out the "mood" of the request using getRequestMood() function which is part of my base module.
Sends the form and mood to the completeAjaxForm() function. This function will replace the loading spinner with an image that reflects a good or bad response.
If the mood is good, meaning the response status code was within a 200 range, then the function will delegate to a function specific for that forms success using a simple case statement.
If this mood is bad, meaning the response status code not within a 200 range, the form will be enabled and the response JSON errors will be displayed. Currently I am using a modal class for this. Again more on that later. You may also note that my base module has a function called messagesToList() that process the response into a DOM <ul> list.


var HomeMarksBase = {
  getRequestMood: function(request) {
    return (request.status >= 200 && request.status < 300) ? 'good' : 'bad';
  },
  messagesToList: function(request) {
    var messages = request.responseJSON;
    var messageList = UL();
    messages.each(function(message){ 
      messageList.appendChild( LI(message.escapeHTML()) );
    });
    return messageList;
  }
};
var HomeMarksSite = Class.create(HomeMarksBase,{ 
  initialize: function() {
    this.signupForm = $('signup_form');
    this.initEvents();
  },
  startAjaxForm: function(event) {
    event.stop();
    var form = event.findElement('form');
    var options = Object.extend({imgSrc:'loading_invert.gif'}, arguments[1] || {});
    var loadArea = form.down('#form_loading');
    var imgTag = IMG({src:('/images/'+options.imgSrc)});
    $(loadArea).update(imgTag);
    new Ajax.Request(form.action,{
      onComplete: function(request){ this.delegateCompleteAjaxForm(form,request) }.bind(this),
      parameters: form.serialize(true)
    });
    form.disable();
  },
  delegateCompleteAjaxForm: function(form,request) {
    var mood = this.getRequestMood(request);
    this.completeAjaxForm(form,{mood:mood});
    if (mood == 'good') { 
      switch (form) { 
        case this.supportForm : this.completeSupportForm(request); break;
      }
    }
    else { 
      form.enable();
      if (!request.responseText.blank()) {
        var flashHTML = DIV([H2('Errors On Form!'),this.messagesToList(request)]);
        this.flashModal('bad',flashHTML);
      };
    };
  },
  completeAjaxForm: function(form) {
    var options = Object.extend({mood:'good'}, arguments[1] || {});
    var loadArea = form.down('#form_loading');
    var completeId = 'complete_ajax_form_' + form.id;
    var imgSrc = '/images/'+options.mood+'.png';
    var moodHtml = SPAN({id:completeId,className:'m0 p0'}, [IMG({src:imgSrc})]);
    $(loadArea).update(moodHtml);
    setTimeout(function() { $(completeId).fade(); },3000);
  },
  completeSignupForm: function(request) {
    var message = "Thank your for signing up for your own HomeMarks page. An email has been sent to " +
      "your address along with a link to activate your account. If you have not done so already, please " +
      "take a moment to read the HomeMarks documentation.";
    var flashHTML = DIV([H2('Signup Complete:'),P(message)]);
    this.flash('good',flashHTML);
  },
  initEvents: function() {
    if (this.signupForm) { this.signupForm.observe('submit', this.startAjaxForm.bindAsEventListener(this)); };
  }
});

5) Client-Side Error Handling

Currently I have 3 client-side options that I can use to present errors back to the user from the JSON array in AJAX response. The first I started out with was using the alert() function. That got boring real quick, but I left my implementation below which is part of the base class, called messagesToAlert().

The second slightly more interesting way was to create a flash message that used the same XHTML/CSS already present in my layout file. This was real easy to implement. Basically using the ERB fragment below in my layout, I guaranteed that I had 3 unique DOM elements for each of my flash message styles, good/bad/indif. Now all I had to do was to create an accessor in my HomeMarksSite class. I choose this.flashes. I then created a clearFlashes() function and then a flash() function that would take the mood and the HTML to embed, viola – I can now call this.flash.('good',someHTML) and I get the same type of flash one would have seen if I set it in the controller and rendered. Note, this is what I used on the the signup form success above.


<% [:good,:bad,:indif].each do |key| %>
  <div id="flash_<%= key %>" class="flash_message" style="display:<%= flash[key].blank? ? 'none' : 'block' %>;">
    <span><%= flash[key] %></span>
  </div>
<% end %>


var HomeMarksBase = {
  messagesToAlert: function(request) {
    var messages = request.responseJSON;
    var alertText = messages.join(".\n");
    if (alertText.endsWith('.')) { alert(alertText); } else { alert(alertText+'.'); };
  },
  messagesToList: function(request) {
    var messages = request.responseJSON;
    var messageList = UL();
    messages.each(function(message){ 
      messageList.appendChild( LI(message.escapeHTML()) );
    });
    return messageList;
  }
};
var HomeMarksSite = Class.create(HomeMarksBase,{ 
  initialize: function() {
    this.flashes = $$('div.flash_message');
  },
  clearFlashes: function() {
    this.flashes.invoke('hide');
    this.flashes.invoke('update','');
  },
  flash: function(mood,html) {
    this.clearFlashes();
    var moodFlash = this.flashes.find(function(e){ if (e.id == 'flash_'+mood) {return true}; });
    moodFlash.update(html);
    moodFlash.show();
    $('site_wrapper').scrollTo();
  }
});

Lastly, and probably the coolest, is the HomeMarksModal JavaScript class I created. This is my new default way of errors to a user. It can be seen in all my video examples on this page. To the right is another example of the login form that uses the same handlers described above. The HomeMarksModal JavaScript class is a bit large to paste inline in this article, but if you want to see the latest version, you can always get it from the master branch of the homemarks_core project on Github.com. When you bind an instance of this object to the window/document, it will automatically crate the modal HTML using Builder. If you want to use it, make sure to get the CSS and images the project too. Below is a function that I put in my site class that allows me to call this.flashModal('good',someHTML)).


var HomeMarksSite = Class.create(HomeMarksBase,{ 
  flashModal: function(mood,html) {
    var moodColor = this.flashMoodColors.get(mood);
    HmModal.show(html,{color:moodColor});
  }
});

Wrapping It Up

This article turned out a lot longer than I had wanted. The AJAX head pattern is pretty simple and it is really fun to see a two line user signup action yield such interactive results. Something also feels good about not putting view code in the controller, yes you can look at inline RJS as view code. Sure it requires that you do a lot more JS work, but there are benefits.

Image you have team of programmers, one person can stay in model/controller land while the other stays on the view/javascript. The model/controller person would write their own tests (PLEASE TAKE A LOOK AT MINE), while the view/javascript person might even take the initiative to use selenium to test the JavaScript. At the time of this writing, I have not done any selenium tests since the plugin for rails is not compatible for 2.0. That last benefit I could think of for this design pattern is that you could easily update view code without restarting your rails app. Just update the JavaScripts and your good to go.

In closing, please let me know what you think. Perhaps you have a better name for the design pattern? Perhaps someone else has a name for it already?

Resources

Original application_helper.rb from HomeMarks v1. An overboard example of shared view/controller tagsoup/rjs.
The latest Advanced Rails Recipes book. See the chapter on "Replace In-View Raw JavaScript". I discourage this technique used in mass.
Rails API for the ActionController::Base#head method.
Rails API for the HTTP status codes.
Rails API for the ActionController#rescue_from method.
The latest RenderInvalidRecord module from the HomeMarks core.
The latest HomeMarksModal JavaScript class from the HomeMarks core.