Context

There are some other gems out there that attempt to solve this problem, so it would be remiss of me not to mention them. Client Side Validations is feature-rich and does a lot of work for you. There’s also LiveValidation, which has been around for a long time and might be a good choice for people with legacy Rails apps that need Prototype.

I wanted a solution that was as small as possible. This is a simple job – no need for middleware, no need for extensions to core Ruby classes. I also wanted it to be as flexible as possible - no assumptions should be made about form markup, styles, classes and so on. I started hacking away, using the jQuery plugin pattern as a starting point for the client side code. It soon became clear that jQuery had to go. Writing Judge as a jQuery plugin was a mistake – the code I wrote ended up tightly coupled to specific event bindings, specific DOM elements etc. That kind of stuff should really be left for the user to decide.

Examples

Setup

Add validation to an attribute in your model.

1
2
3

class Thing < ActiveRecord::Base
  validates :name, :presence => true
end

Use the Judge::FormBuilder in your view. Add :validate => true to the options hash of any form element that you wish to validate on the client side.

1
2
3

<%= form_for(@thing, :builder => Judge::FormBuilder) do |f| %>
  <%= f.text_field :name, :validate => true %>
<% end %>

Quick validation

The judge object has a static validate method for immediate validation:

1
2

judge.validate(document.getElementById('thing_name'));
  // => { valid: false, element: HTMLInputElement..., messages: { blank: "Can't be blank" } }

The same method used within a keyup event handler (requires jQuery):

1
2
3
4

$('input#thing_name').keyup(function() {
  var input = this;
  console.log(judge.validate(input));
});

Note that we are not passing a jQuery object into the validate method here, but the DOM element itself. The jQuery get method will often be of use when validating elements that have been wrapped by jQuery.

Validation with watchers

Most of the features of Judge are based around watchers – JavaScript objects that hold information about the form elements to which they point.

1
2
3
4
5
6
7

// instantiate watcher
var nameInput   = document.getElementById('thing_name'),
    nameWatcher = new judge.Watcher(nameInput);

// some time later:
nameWatcher.validate();
  // => { valid: false, element: HTMLInputElement..., messages: { blank: "Can't be blank" } }

Validating stored elements

Most of the time, validating immediately on keyup or change will be enough to achieve the intended user experience. But there are times when storing a reference to a form element, or a group of form elements, can be useful. For example, validating elements conditionally based on user triggers. This is where the Judge store comes in.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// store some text input elements
var textInputs = document.querySelectorAll('form.thing-form input[type=text]');
judge.store.save('foo', textInputs);

// retrieve watchers for your stored elements
judge.store.get('foo');
  // => [ { element: HTMLInputElement... }, { element: HTMLInputElement... }, ... ]

// retrieve your stored elements
judge.store.getDOM('foo');
  // => [ HTMLInputElement, HTMLInputElement, ... ]

// validate all elements stored against key 'foo'
judge.store.validate('foo');
  // => [ { valid: true, ... }, { valid: false, ... }, ... ]

Use it

Go ahead! Feedback is all kinds of welcome.

1

gem "judge", "~> 1.0.0"

• Judge on RubyGems.org
• Judge documentation
• Judge source on GitHub

I’ve come up with the following matcher to do just that:

Use it like so: expect($('input#foo')).toHaveEvent('keyup');

I’d be interested to hear of any thoughts or improvements. Likewise, I’ve started work on testing for events attached using $.fn.live(). These are handled a bit differently, since live events aren’t actually bound to the selected element. Instead they sit there, bound to the document, listening for the event to bubble up the DOM tree.

So: expect($('input#bar')).toHaveLive('focus');

Again, any improvements or thoughts are welcome.

You can make these matchers available by using this.addMatchers.

Aaron Quint’s route-driven JavaScript framework Sammy, ships with QUnit tests. This is an obvious choice, since QUnit is jQuery’s test framework and Sammy depends on jQuery. I, however, am not the biggest fan of QUnit. It works really well, but I find the syntax a little unwieldy. On a recent project, I thought I’d try out Jasmine – a library-independent JavaScript BDD framework with a more readable syntax.

In this post I’ll run through some typical Sammy scenarios and show you how I’ve written the corresponding Jasmine tests. For reference, I’m using Jasmine 0.11.1 and Sammy 0.5.4.

Setting up Sammy

Let’s start with a fairly simple Sammy app with some common features.

At the top of the app, the context variable is assigned, providing easy and unambiguous access to the Sammy.Application instance itself, for use elsewhere. A GET route is declared, which simply triggers an event named myEvent. The second argument to trigger passes an object to the event:

Here is the event that was triggered in the GET route. Bound events accept a custom object as their second argument, which is used in this example to pass in some arbitrary values:

Here, a (very) rough example of a modular design pattern is established for any non-event driven parts of the app. I like to group functions by similarity of purpose.

An aside: Can I read all this shit easily?

I’ve started to ask myself this question frequently. If the answer is no, it’s time to abstract.

Particularly where jQuery is involved, I often find code that looks similar to this:

It only takes a few lines of jQuery, chained to the hilt, to achieve a lot. This is seen as an advantage, and rightly so for small pieces of UI scripting, but it’s a huge pain when testing larger applications since it leads to bloated specs. Imagine trying to test the above example – a long list of calls needs a long list of assertions. But testing needn’t be a chore! Whichever way a JavaScript project is structured, from fully modular and enclosed to fly-open-for-everyone-to-see, keeping functions succinct and limited in purpose makes for much easier testing. Readable code == readable tests == clear statement of intentions to leave for future developers == painless development.

Testing with Jasmine

Here’s an initial attempt at testing the above Sammy app using Jasmine. The specs are within describe blocks. These aren’t strictly necessary but nesting them helps to describe your tests in relation to the structure of your app. See how the nesting follows the namespacing of the url.build function, for example:

Since the app involves DOM insertion, it’s clear that some kind of setup and teardown of temporary DOM elements is required. Using Jasmine’s beforeEach method, the relevant elements are inserted into the DOM before each spec is run. Since each spec within this describe block refers to the same event, the event trigger is here as well, to avoid repetition. The DOM elements are cleaned up using afterEach.

Specs are enclosed in the it blocks and assertions/expectations are made using expect. The syntax, when read out loud, sounds pretty close to how I’d describe my tests. “It should etc.”; “Expect actual to match expression”. Jasmine has various matcher methods such as toMatch.

Befriending the DOM

There’s something a little clunky about certain aspects of the above tests. In particular the DOM-related areas look a little hacky. It would be unfair to call this a fault of the testing framework – DOM manipulation isn’t even on the Jasmine agenda. So this is where velesin’s jasmine-jquery extensions step in.

jasmine-jquery allows for various improvements on the original tests:

Firstly, the manual setup and teardown is no longer required, thanks to loadFixtures, which loads in the necessary DOM elements from an external file, inserts them into a wrapper div inside the document body, and cleans up automatically after each spec is run. Big win. People who are really smart might even try to load fixtures in from the same files as partials to avoid duplication (I have a feeling this could all come together beautifully with Sammy’s new Meld feature…). An alternative is to use setFixtures, which accepts either an HTML string or a jQuery element as its only argument rather than loading from an external file.

jasmine-jquery also provides a set of custom matchers. Here, for example, there’s no need for the workaround of checking the innerHtml of an element against a regular expression, when toHaveText does the trick.

Conclusions

The Jasmine documentation could really do with a spruce up – especially in the less immediately obvious areas like spying, mocking and stubbing. It’s possible to bundle through and get some pretty nifty async tests running (blog post on this topic pending) but clearer instructions would be a big help. I’m sure better docs are in the pipeline with version 1.0.0 proper due to be released soon.

I find testing with Jasmine a more pleasant experience than any I’ve had with another JavaScript testing framework. The only thing that has come close for me is JSpec, which has very similar syntax to Jasmine if you eschew the custom Rubyesque grammar.

Provided you structure your Sammy application in a sensible way, it’s easily testable with Jasmine. I’d like a way of testing the Sammy routes themselves, something akin to functional testing as apposed to unit testing. But I’m happy enough with relying on the Sammy internal tests and keeping the routes as simple trigger calls.

Concept

You submit two Twitter users, who are then queried a handful of times through the Twitter API and a “fight” of sorts is created between the two users. They are attributed points based on various “fight”-worthy criteria: bad language; negative language (words like “kill” or “hate”, for instance); previous Tweet Fighter fight record; and – this being Twitter – number of followers and number of tweets to date. The (fuzzy) thinking behind this is that, along with the fighting talk, the mouthiest users with the most backup from their group would have an advantage in a fight situation.

It’s pretty silly, I know. I considered hacking away at some kind of worthy cause, but I’m a big kid. Maybe I’ll get around to creating a parking metre/carbon emissions cross-referencing Google Maps mashup one day when I’m older and crabbier. Hopefully nobody reading this will assume that I’m advocating random violence by making a fight-based application, but we’ll see.

I lifted the visuals from Street Fighter II, which was one of my favourite games as a kid (please don’t cease-and-desist me, Capcom. It’s a tribute). I seem to remember playing as Vega a lot, despite him not being very good.

Inside

As mentioned before, Tweet Fighter is written in Ruby, on Sinatra. My ORM buddy of choice right now is Sequel. I like the intuitive, chainable query syntax. As such, I was happy to see the recent announcement regarding plans to make Active Record more, well… Sequel-esque.

I’m also using httparty to allow users to tweet directly from their fight pages – basic authorisation is easy with httparty and it felt like a much better fit than overkilling the project with OAuth.

Issues

Overall, the Twitter API is easy to work with. It’s a little weird having the search API split away from the remainder of it, but it’s no big deal. One major limitation of the Twitter API – the unsearchable nature of any status updates over a certain age – actually turned out to be a blessing. It means that fights involving the same Twitter users will be different from week to week (or even day to day), depending on how sweary/misanthropic the users have been feeling recently. Sure, follower counts will remain roughly the same for weeks on end, but a couple of good old blue-tinted rants about your local transport provider will have you beating opponents in no time.

Future

A leaderboard is in order. Anything else I think of might just get done too. Any suggestions/bugs/breakages, please let me know.

I want to go to there

Update, 12 Feb 2010

I’ve just read that Twitter is phasing out basic authentication much sooner than I’d anticipated. Will have to get cracking on OAuth!

Update, 18 June 2010

I stripped out the basic auth tweet form and replaced it with a TweetBox from Twitter’s @Anywhere platform. Pro: Trading a controller action and two gems for a few lines of JavaScript isn’t bad at all; Con: non-JS users miss out again.

I’m looking forward to writing applications in this way (and I’m trying to think of an excuse to do so), but what Sammy also kindly allows is direct, linkable access to the inner workings of some of the more usual Javascript implementations too.

I’ve put a few examples together to demonstrate.

jQuery Accordion

Pretty much every developer out there who deals with the front-end will have come across collapsing accordion-style lists. They’re in wide use nowadays as they make pages with lots of text look a lot friendlier (for example FAQ pages). Also, people like seeing stuff move around.

But what if you wanted to retain the accordion effect, whilst providing users/clients with direct links to the page with a particular list item expanded?

http://playground.joecorcoran.co.uk/sammy/accordion/

Click around and notice that the URL in the address bar is changing. If you copy one of the new URLs, like

http://playground.joecorcoran.co.uk/sammy/accordion/#/section/3

into a new window, you’ll be taken to the same page with the 3rd section expanded.

Here’s my Sammy / Accordion code, to demonstrate how simple it is to implement.

jQuery Cycle

http://playground.joecorcoran.co.uk/sammy/cycle/

Another way in which Javascript is used quite frequently is to present slideshows. Again, we could be using Sammy to provide direct access to a slide that would usually be buried in the cycle:

http://playground.joecorcoran.co.uk/sammy/cycle/#/slide/3

This one was slightly harder to implement, but still achievable with a bit of hacking around. I couldn’t get the ‘previous’ and ‘next’ options from the Cycle plugin working nicely with Sammy without screwing the transitions up, but I’m sure it’s possible with more work.

Here’s the Sammy slideshow code.

Friendly form wizard

This one is less common, but it’s where my imagination took me after the first two. It’s a single page, Sammy app-powered form wizard.

http://playground.joecorcoran.co.uk/sammy/form/

The stages of the wizard are simply fieldsets hidden/shown appropriately. There’s a simple validation attempt at the end which checks for empty fields and gives helpful links back to any stage that needs to be amended. Once all fields are filled, the submit button appears and Sammy handles the post request. Obviously, performing more complicated validation on page would become unwieldy, but handling it with AJAX is an option.

Here’s my Sammy form code.

I’m really impressed with Sammy and it’s definitely changed the way I think about working with Javascript for the better. I’d certainly recommend downloading the latest version (0.2.0 at time of writing) and weaving it into some of your existing Javascript – it’s a nice way to familiarise yourself with Sammy whilst adding an extra slice of accessibility to your work.

Update, 4 Jan 2011

Just thought I’d better say this, since this post is still getting a lot of traffic. While the examples I wrote here are quite useful, Sammy itself has changed quite a lot in the meantime. Please make sure you check the Sammy docs before you give yourself a headache.