It has dragging-related behaviors: it drags, groups, sticks and un-sticks.  It has editing-related behaviors: it records and remembers stuff you type into it. It will have physical behaviors such as the ability to minimize and enlarge.  And it will be able to export its data when asked, either independently or from the group it belongs to.

One way of looking at this is as a collection of state and behavior: an object. State includes visual properties (such as  color, width, height) and behavioral properties (such as flags that indicate whether it is in “sticky” mode or not).  Behavior includes methods for dragging, grouping, sticking and unsticking, sharing content, resizing, etc.

It would therefore be easy to extrapolate this to a class Sticky that might look something like this (JavaScript-y pseudocode):

var Sticky = (function(){
  return{
    color: yellow,
    width: 100px,
    height: 100px,
    isSticky: true,
    findOrCreate: function(domId){
      var sticky = $(domId);
      sticky.attr("color", color);
      // etc.
      return sticky;
    },
    onDrag: function(dragEvent){
       // do something to handle dragging
    },
   onSave:function(){
      // do something to handle saving via AJAX
   }
   // etc.
  };
}());

Where  you find or create the relevant DOM object, encapsulate it in a Sticky namespace, and bind static properties and behaviors triggered by events.

This is reasonable, but this can quickly get unwieldy because the DOM element is mixed up in the logic and because there are methods that handle different types of behavior all mixed into one class. While it is only 15 or so lines above, it would grow with new functionality such as exporting, docking, etc.

Given this, we moved away from the idea of a class Sticky that can stamp out sticky objects, and towards building collections of behaviors that can be applied on as as-needed basis to DOM elements — e.g., behaviors that “make” an existing DOM element “sticky”.

I think of it as creating an enhanced element. The canonical representation of a sticky is the DOM element and behaviors are applied on a just-in-time basis. For instance, a “dragging sticky” is what is able to drag around and do all drag-related activities. Think of it like wrapping a sticky in adjectives to make it ‘enhanced’ in a particular way.

Here’s an example, a proof-of-concept created in a JavaScript spike session:

var createDraggingSticky = function(sticky_dom_element, newNeighborMover, neighborLookup){
    var sticky_id = sticky_dom_element.attr("id");
    var draggingSticky = {
      dom_element: sticky_dom_element,
      id: sticky_id,
      updatePositionBy: function(dx, dy){
          var element, oldLeft, oldTop;
          element = $(this.dom_element);
          oldLeft = element.position().left;
          oldTop =  element.position().top;
          element.css("left", oldLeft+dx);
          element.css("top", oldTop+dy);
      },
      youAreBeingDragged : function(dx, dy, neighborMover) {
          if(!neighborMover) {
             neighborMover = newNeighborMover(this);
          }
          neighborMover.moveMyNeighbors(dx,dy, this);
          this.updatePositionBy(dx, dy);
      },
      getNeighbors:function() {
          return neighborLookup(this);
      }
};

And this gets attached on the drag handler, which gets triggered by jQuery drag, like so:

draggingSticky = createDraggingSticky($(ui.helper), Factories.neighborMover, Relationships.getNeighbors);

So until the div is dragged — and again, after it is dragged — it is just a regular DOM element wired up with a few jQuery plugins such as draggable and editable. When the dragging starts and the sticky needs to be able to call upon its dragging behaviors, a reference to the DOM element is passed to the dragging behaviors (so they know who to act on), and the behaviors are attached and can interact with the sticky: at this point the sticky is now dragging_sticky.

Then, when the sticky stops dragging, its neighborlookup and other caches are cleared, and the behaviors are no longer applied. The pattern reminds me of mixing in a module of behavior in Ruby, except here it is mixed in just in time for use and only the relevant module is added at any given point.

From the standpoint of a user interacting with the application, however, it appears that the sticky always has those behaviors: after all, every time you drag it, it acts like a dragging_sticky, and you never see it behaving as a non-dragging-sticky. Sure, when it’s sitting still and you’re just writing in it, you could say it’s non-dragging, but that’s not really fair, since it’s not supposed to be dragging then. So in this respect — from the experience of it — it is seamless and always endowed with what it needs.

But from an application standpoint the ‘enhanced stickies’ are ephemeral: they only exist during the time they are needed, rather than hanging around in memory or cluttering up a large object, such as my JS pseudo-code example from before. Instead of 50 JavaScript objects held in memory, waiting to be used, we have 50 DOM elements, each able to be enhanced on a hair trigger and reverted as needed. It’s a smaller footprint.

Similar patterns can be applied for other types of behaviors, such as physical behaviors and editing behaviors I mentioned at the beginning. We’re still working this out, but it seems very promising and clean, and it keeps a clear separation between the DOM side of things and the application logic side of things.

As a final thought, working in this way reminds me of getting my head around the concept of Existentialism in college: the philosophy that a person is a total of their actions, not a predetermined “self”. While a person may appear to be a seamless construct of self (indisputably Sarah or indisputably Zak), we really just seem that way because for the most part, our behavior sets are consistent with themselves — i.e., I usually do things that I usually do. However, if I change my actions, I am changing myself.

It is really that idea we are building into the application as we move away from the immutable concept of the Class into a shifting collection of actions that are applied at runtime.

First: what should the URL for unclaimed surfaces be? My first thought was /surfaces; That seemed reasonable. Then I wondered about using /surfaces/unclaimed. Is the extra part of the URL unnecessary, is it a violation of YAGNI?

Second: what should the URL for viewing your claimed surfaces be? Should it be /surfaces/claimed, showing the surfaces belonging to the logged-in user? Or, should I be explicit and use /users/:user_id/surfaces? Should I also add /users/:user_id/surfaces/claimed?

I had an intuition about what the solutions should be, but, when I am uncertain, I like to fall back on base principles, such as the 4 rules of simple design and the SOLID principles. I thought I would write a blog post outlining how I went about analyzing these 2 problems.

Simple Design

The 4 rules of simple design are as follows:

• Passes all tests
• Reveals Intent
• Contains no duplication
• Is Small

J.B. Rainsberger makes a convincing argument that there are really only 2 rules: no duplication and reveals intent, since ‘passing all tests’ is like breathing and ‘is small’ comes naturally from the other principles.

Unclaimed Surfaces

A driving force in the user experience for the stickies project is the ability to very quickly try the system, even before registering. The surfaces created by unregistered users are considered ‘unclaimed’ and public to everyone else. I wrote a blog post outlining this approach a little while ago. A major and important decision is what the URL should be for these surfaces (Sarah wrote a post on our choice of domain). The natural first thought would be /surfaces, since it seems like a natural root name.

Thinking about this, though, I realized that the decision to use /surfaces as the url broke the rule about revealing intent. This rule can also be thought of as ‘named clearly.’ What is the usual expectation of a URL like /surfaces? In general, it is used as the index, or the list of all surfaces. Giving it an implicit filter (unclaimed) is a violation of this. Another interpretation of ‘reveals intent’ is the Principle of Least Surprise – you shouldn’t be surprised when you access something. An explicit URL for the unclaimed surfaces would be /surfaces/unclaimed.

Being explicit also opens you up to extensibility and future enhancements without having to worry about it. No, I’m not saying that you should be designing for unknown future requirements, but, given a choice, I like to choose the path which will give me the most flexibility in the future. Having explicit filters on the /surfaces URL, such as /unclaimed, provides both a precedent and a mechanism for this. I am a firm follower of the SOLID principles, and one of my favorites is the Open-Closed principle: systems should be open for extensibility, closed for modification. There are a lot of resources online with detailed explanations, but it boils down to this: build systems that can accept behavorial changes through extension without requiring modification of the core system. We can take this idea to our resource locators, as well. So, if we hide some implementation behind /surfaces, then we create the potential need to change what it means in the future. By relying on a form of extension, /surfaces/unclaimed, then we create a situation where we can more easily and predictable add future behaviors simply by adding a new filter: /surfaces/private or /surfaces/about_to_be_deleted, for example.

Claimed Surfaces

Viewing a user’s claimed surfaces seems natural to use /users/:user_id/surfaces. Most people wouldn’t argue with this. When using an authentication system in Rails, though, generally you are given a #current_user method on your controller. This provides access to the currently logged-in user. I often see people taking a shortcut when scoping resources. In our case, it would be using #current_user to scope the surfaces given when accessing /surfaces. So, when you access /surfaces, you are actually getting the equivalent of current_user.surfaces, or, all the surfaces belonging to the logged-in user. This seems reasonable, since it feels like overkill to provide the user id on the URL: /users/:user_id/surfaces. We already have the user id, don’t we? Don’t the 4 rules say we shouldn’t have duplication? Yes, they do, but this isn’t really duplication. In addition, this scheme creates a severe inconsistency in the addressing scheme due to a subtle implication of the DRY principle.

The idea of duplication isn’t just about code, but more importantly about concepts. The DRY principle (don’t repeat yourself) is a form of ‘every concept should have a single representation in your system.’ There is a nice corollary that every representation should be of one concept.

Suppose you use /users/:user_id/surfaces to view some claimed surfaces (other people’s), yet /surfaces or /surfaces/claimed to see your own. The concept of ‘surfaces claimed by a user’ now has two different representations in the system. The second rule of simple design (eliminate duplication) comes into play, so we should eliminate one of them; since we already have a concrete use for /users/:user_id/surfaces, it makes sense to stick with that.

What about duplication between the location of the user id: if my id is 3, then I have /users/3/surfaces, and I also have a 3 in my session somewhere, stored as ‘current user id.’ Is this duplication? No, it isn’t; it is just happenstance that they coincide. When eliminating duplication, it is important to remember that you sometimes have constants which represent different concepts. In this case, the concepts are ‘user owning the viewed surfaces’ and ‘user currently logged in.’

Aside: This idea of a number representing two different concepts comes up a lot at coderetreat. According to the rules of Conway’s Game of Life, a live cell stays alive if it has 3 neighbors, and a dead cell comes to life if it has 3 neighbors. It is common to see people refactor both of those 3′s into a single representation. This generally leads to less understandable code, as the meaning gets lost, muddled in a haze between two different thoughts. It also makes the system less flexible, as the extraction of the ‘magic number’-ness of it becomes difficult, due to an unnecessary coupling between the two different rules.

Should it be /users/:user_id/surfaces/claimed?

This is an interesting question. On one hand, we do have /surfaces/unclaimed, so it seems as though the symmetry of having /users/:user_id/surfaces/claimed is desirable. But, taking this URL apart, we can notice something important: there is duplication in concept. The URL /users/:user_id/surfaces reads as ‘the surfaces belonging to the user represented by :id.’ The /surfaces/claimed reads ‘the surfaces claimed by …’ Since ‘belonging to’ and ‘claimed by’ are synonyms in our system, we can see that the single URL /users/:user_id/surfaces/claimed has duplication in it. Since we have already seen that the prefix /users/:user_id is needed, the /claimed suffix should be dropped.

So, all of this discussion has lead us to the following identifiers for our collections:

/surfaces – all surfaces, both claimed and unclaimed. What does this mean, how best to represent it? I’m not sure, and I don’t think we’ll implement this quite yet;
/surfaces/unclaimed – all unclaimed surfaces;
/users/:user_id/surfaces – all claimed surfaces for user represented by :id;

It has been really interesting to see how I did this before, and see how this has evolved into a new approach.

I wrote the original prototype of the stickies project about three years ago. When I began coding, I had the concept of “a group” in my mind. This was directly related to how I thought about stickies, which was possibly more like a user than a developer: I was describing the outcome of the behavior — “stickies are in groups” — and modeling that. After all, that’s what inspired me to write the application. My approach was very straightforward: each sticky knew everyone in its group, and told them to move when it moved. It recalculated the members of a group at critical moments: on dragDrop, onDelete, onResize, as each of those events could directly affect which stickies were touching.

It did this by finding its intersects (those stickies it was immediately touching) and then it’s “recursiveIntersects,” as I called them: the stickies that each of its intersects were touching. In short, its extended family. I wrote a function called groupOnIntersect that was called whenever a sticky was dropped (or deleted or resized). This method added and removed stickies to their new group by figuring out the current configuration of the stickies on the stage (which we are now referring to as a ‘surface’, see my previous post on naming). When this method completed, the groups were configured. This way when a sticky was dragged it would simply access its group by a group ID number, loop through the group, and set the x and y position of everyone in its group, like so:

if( this.isSticky  ){
  for( var i in group ){
    var sticky = group[i];
    if( sticky.isSticky && sticky != this ){
      sticky.xpos += deltaX;
      sticky.ypos += deltaY;
      $Dom.setXY(sticky.id, [sticky.xpos,sticky.ypos]);
    }
  }
}

This worked and was a valid approach to the problem of moving stickies around, but it generated a lot of long function definitions. I ended up with code to go through all the states that I could envision the stickies being in, in order, and writing code for each one. This approach led to a lot of conditional checks, for example:

var len = this.intersects.length;
if( len == 0 ){
   /* intersects w/nobody, needs to have own new group */
   ... do stuff
} else if( len == 1 ){
   /* intersected w/only one other element so add to its group */
} else if( len > 1 ){
   /* intersected w/more than one element */
}

While code in this style can work just fine, it is not very flexible and it doesn’t have clear abstractions. It is also fragile: because it relies on a number of diverse condition-checks, there is always the possibility for leaving one out, having duplication, inadvertently creating a bug, or having trouble scaling into new conditions. Another side-effect of code like this is that it can get physically long, which makes it hard to read on the page. So there is a lot of visual scanning, looking for where this “if” started, and what “else” we are inside. When scanning the code this way, it is harder to see the abstractions and pull them out.

Anyway, I’ve come a long way since then, so it was exciting to revisit this problem and look at different types of solutions for grouping and moving the stickies. Corey has more experience applying patterns and abstractions, and he is also removed from the problem, so we were able to look at it together with fresh eyes. We talked through three different ways: two based on some standard design patterns and one a combination of the two. We decided to start with an implementation of the Visitor Pattern. As a note, it was great to talk through them all on the whiteboard: rather than approaching them as dry examples in a book, we literally acted them out in the living room, understanding how they could work in the context of the stickies. I recommend story-telling and whiteboarding for these types of design discussions.

So, the current implementation is as follows: when a sticky begins to move, as triggered by the jQuery drag event, it will access or create an object that we are calling a MovingVisitor (MV). This object is responsible for getting the collection of neighbors (what I called intersects in the first iteration) from the sticky, and then telling each of those (that it hasn’t visited before) to move (and by what deltaX and deltaY). It continues making visits until all of the stickies have been visited. As you can see, this approach obliterates the need for the concept of recursiveInterects entirely! The MV takes care of traversing the set of stickies, thereby simplifying our calculations.

Here is an extraction of the code as it is being developed, test-first, in the JavaScript specs:

// Sticky
sticky = {}
sticky.youAreBeingDragged = function(dx, dy, movingVisitor) {
     if(!movingVisitor) {
         movingVisitor = createMovingVisitor();
     }
     movingVisitor.moveMyNeighbors(dx,dy, sticky);
};
sticky.getNeighbors = function() {
     return neighborLookup(sticky);
};

// MovingVisitor
 var movingVisitor = {};
 movingVisitor.moveMyNeighbors = function(dx,dy,sticky){
    $(sticky.getNeighbors()).each(function() {
         this.youAreBeingDragged(dx,dy, movingVisitor);
    }
  );
};

The code does not yet do a few critical things:

1. Track the stickies who have already been visited
2. Be explicit about how the neighbors are calculated (neighborLookup)

These things will come next, and then this will be wired up and moved from the spec files into the JavaScript objects themselves. But it is a great example of leveraging an existing pattern and having clean abstractions. One of the benefits that I see from applying the pattern is that the sticky itself does not have to worry about doing a large overhead calculation to determine its whole extended family; it just does its thing (move), and passes on this information to someone else (the visitor). It is then the job of the visitor to tell the others. They each have their own jobs, so we have shorter code with more clearly defined roles, and tasks specific to each actor in the story.

The most exciting thing I am getting from this, beyond the code-benefits from this approach, is an interesting insight into the procedural mind-set and a more object-oriented or abstract mindset. Looking at my original approach, I can see how logical it was. This is how we as humans complete tasks: I am going to wash the dishes, then I am going to dry them, followed by putting them on the shelves, and if there are too many, I will put them on another shelf, at which point I will get one out to eat dinner, etc. Yet at the same time, adapting that step-by-step mindset to writing code is not the cleanest translation, though it may seem the most direct and familiar when you are starting out. It is also interesting that some applications, like Flash, offer both a timeline and an editor w/a scripting language, to accommodate different styles of thinking (though of course you can go step-by-step in an editor, it is just more clearly represented that that is what you are doing in a timeline).

What is required is a kind of mental transliteration: from the procedural way of understanding tasks to a more abstracted way of sending messages between objects.

Get away from the DOM as soon as possible

Even with great tools like jQuery, interacting with the browser blows big time. So, build a very thin layer at the entry points to your system, detach yourself from the actual DOM by creating JavaScript object wrappers and manipulate those. This has a lot of benefits, including the usual ones gained from isolation. A lot of times, I hear people talk about JavaScript being all UI/view code. In the stickies project, we are putting the majority of our system in JavaScript, using the browser as an application platform. This means that we have view code and domain logic all running in there. So, as with any architecture, you should be isolating the UI and just testing the innards.

So, I have a general rule, only a small set of functions are allowed to pass a string into the root jQuery selector, a la $(<string>), the rest of the functions, if they access the DOM at all, must use a context-based find, such as $(element).find(<string>). This keeps the code ignorant of any unnecessary structural details. Most of the these functions that work on the DOM would be highly encapsulated inside JavaScript objects.

Side story: When I was first learning about test-first programming, I had to build a user interface for the automation tool I was writing. I was pairing with Bob Koss at the time, and I had come to work in the morning after struggling all night with the idea of writing tests for the user interface. I asked him about it, and he reinforced the rule that most people believe, but few people truly do: there should be no logic at all in your user interface. That is, the layer directly behind the UI should be receiving events, grabbing the data and sending it to the underlying logic components. I’ve been doing it religiously ever since. When you start moving heavily from test-first to test-driven, you really start to see that you can’t do anything but isolate the user interface. After all, when your executable examples are treated as a client of your system, your UI will just be the second client, heavily relying on a well-defined api.

Object creation is cheap

In the stickies project, a sticky is represented on the screen by a div. Plugins, such as jQuery UI, interact with our system via the DOM, not via our JavaScript objects. So, why not have the div be the canonical ‘sticky’ object, spinning up JavaScript-based ‘stickies’ whenever we need them. Create a builder function that takes a div and returns a JavaScript object. However, we don’t persist these JavaScript objects, they are built on an as needed basis, generally due to a stimulus from a user event, then thrown away when we are done reacting to the event. This also allows us to easily test our functionality by passing in dummy objects that we create in our tests. Yeah, we could use jQuery to spin up some dummy DOM elements, but then you have a lot of unnecessary cruft around.

Test doubles are free

One beauty of JavaScript’s prototype-based nature, as opposed to being class-based, is that the concept of ‘type’ really frees itself from the usual tight-coupling with ‘class’ that most people think of. A JavaScript object is this: {}. That’s it. Nothing more than that. What type is it? Well, no real type, yet. Want to change the type of it? Add some behaviors, either by mixing in a new prototype or just add the individual behaviors, yourself. Using jQuery makes this very easy, as it has an extend function, which you can use to easily mix in behaviors. This allows you to very easily evolve the type of an object as it moves through it’s lifetime.

What does this mean for test doubles? Well, you don’t need anything other than {} to create yourself a test double. Need to stub out a behavior?

function functionUnderTest(collaborator) {

  return 2 + collaborator.foo('hello');

}

Do something like

var double = {};

double.foo = function() { return 5; }

functionUnderTest(double);

Because functions in JavaScript are closures, you can even do something like:

var double, returnValue;

returnValue = 5;

double = {};

double.foo = function() { return returnValue; }

functionUnderTest(double);

Want to capture the arguments? That’s easy, too:

var double, __args_stubbedFunction;

__args_stubbedFunction = 5;

double = {};

double.foo = function() { __args_stubbedFunction = arguments; }

functionUnderTest(double);

I’ll leave it as an exercise to the reader how to both capture the arguments and return a value. :)

As I’ve been spinning my own doubles, I’m starting to notice a few patterns begging to be extracted. Stubbing a function with a given return value and collecting the arguments given is a common task. It is the most common activity that I do. I occasionally do it on existing objects, but most of the time it is on doubles that I’ve spun up to pass in. I’ve allowed the duplication to persist for a while, trying different techniques, but I’ve pretty much settled on the one. This means that it is time to extract it. I don’t know whether they will come out into a cohesive set that could be called a doubling framework, or just stay a set of functions that I reuse. I’ll definitely put it out on github, though.

There are other things I’ve learned, but I want to end this and get it posted. We are doing our best to post regularly, so you can expect more thoughts on JavaScript while we continue to build the stickies project. We are close to initial feature complete, so a beta release is on the horizon. No specific date, yet, but it will be soon.

At some point soon we’ll be moving to Bundler, and at that point there will be a treat of a blog post about it :) Right now, this is how I feel about Bundler: optimistic, excited and cautious, all from personal experience.

While I’m on this house-cleaning topic, for those of you who do vendor jslint_on_rails, be sure to specify it’s :lib setting, otherwise it looks for a non-existent file called jslint_on_rails.rb, when it really wants jslint.rb:

config.gem 'jslint_on_rails', :lib => "jslint"

For those of you who *are* using Bundler that would translate to:

gem 'jslint_on_rails', :require_as => "jslint"

And for those of you who are wondering what’s up with JSLint, it is a “a JavaScript program that looks for problems in JavaScript programs”. JSLint comes with a warning, though: as it states flat out, JSLint will hurt your feelings!

Why? Because the easy, loosy-goosy JavaScript that you’ve most likely learned to write over the years is actually a hotbed of errors waiting to happen. It’s like one of those microscopic views of an everyday surface, such as, oh, your keyboard: everything looks OK from normal distance, but then there’s all these little creepy things crawling around.

JSLint is a script written by Douglas Crockford, who is awesome and is the best source to both boggle and clear your mind about JavaScript. JSLint allows you to check your JavaScripts against a number of sloppy coding practices that are allowed by JavaScript but that can cause problems in your application or when your code is minified. Some of the things we are allowed to do in JavaScript but encouraged against are: leaving semicolons off (can cause trouble when your scripts are minified as line breaks won’t be read correctly); creating non-standard markup (such as UPPERCASE tags); using eval, which can leave your code open to being exploited by user input; failing to declare your variables before using them (as failure to initialize a JS var creates it in the global namespace, where it can easily and mysteriously cause namespace collisions); and more.

To use jslint_on_rails, you set up a config file, config/jslint.yml, where you declare your tolerance for a set of conditions. You can also set paths where JSLint should look, so it checks your own JavaScripts and not, for instance, JQuery or the entire YUI library.

Going through the jslint.yml config can spark great discussion, so be warned that it’s more fun to do it with someone else. It’s like one of those quick-dating sites where you can learn more about a person than you really wanted to… (“You voted for George Bush?? In 2004?” ..or, the web developer equivalent.. “You use UPPERCASE attrs in your html??”) Of course, other things may horrify you than horrify me, but that’s the fun of it. Here’s a glimpse of our config file, to see some of the options.

adsafe: false # true if ADsafe rules should be enforced. See http://www.ADsafe.org/
bitwise: true # true if bitwise operators should not be allowed
newcap: true # true if Initial Caps must be used with constructor functions
eqeqeq: true # true if === should be required (for ALL equality comparisons)
immed: true # true if immediate function invocations must be wrapped in parens
nomen: true # true if initial or trailing underscore in identifiers should be forbidden
onevar: false # true if only one var statement per function should be allowed
plusplus: true # true if ++ and -- should not be allowed
regexp: false # true if . and [^...] should not be allowed in RegExp literals
safe: false # true if the safe subset rules are enforced (used by ADsafe)
strict: false # true if the ES5 "use strict"; pragma is required
undef: true # true if variables must be declared before used
white: false # true if strict whitespace rules apply (see also 'indent' option)


Anyway, it’s simple to set up and then you just run:

rake jslint

(We made that part of the default rake task, so we don’t have to think about it). And the JavaScripts you included in your paths are checked.

JSLint is something I would recommend working with when you’re starting a project as opposed to when you already have a ton of JavaScripts. It’s like a strict teacher who can keep you on the straight and narrow, and depending on how far you’ve strayed it may be too hard to start using it when you’re already knee deep in undeclared variables. Otoh, that may be when you need it most. More than anything though, wander over to their site and read about it: it’s a great read and gives a lot of insight into JavaScript and coding practices.

So tonight’s post turns out to be about strictness: vendoring gems, checking javascripts. Luckily, tomorrow is Friday so all bets are off and we can forget our semicolons at the bar :)

Happy coding.

Feature: Unclaimed Surfaces
  In order to easily see whether the stickies project has functionality I want to use
  As a visitor to the site
  I want to create a surface and stickies without registering

We began calling this type of surface ‘unclaimed.’ You can try out the functionality immediately, see what it is all about, then decide whether you want to register for the site. Naturally, what you see is going to make you want to register. What happens to this surface, though, when you register? It would be nice if you could associate it with your user. This led to the idea of “Claimed Surfaces:”

Feature: Claimed Surfaces
  In order to keep track of surfaces that I have created
  As a registered user
  I want to claim a surface and associate it to my account

The idea of ‘claimed’ and ‘unclaimed’ are different from public and private, though. From a resource perspective, the URIs would be different:

Unclaimed: /surfaces/:unclaimed-surface-name
Claimed: users/:user_id/surfaces/:claimed-surface-name

Note: We have talked about public and private surfaces, but those are later stories that change the nature of claimed surfaces. For now, there is no authorization functionality implemented. This also means that you can edit other users’ claimed surfaces (until we implement authorization stories).

Previous cards related to editing surfaces had created the functionality related to ‘unclaimed’ surfaces. The question was how best to add the functionality for users to have surfaces associated with them. We wanted to do it as simply as possible. When we started the project, we decided that the idea of a user had no intrinsic value on its own. Instead, we wanted to wait to see what value-creating feature would cause us to need the concept. And, here we are, ‘claimed surfaces.’ We discussed other options, including a simple naming system, where you could create a group of surfaces that would stand in for user. In the end, looking at the next stories coming (spoiler: public and private surfaces), we decided that adding users made sense here. So, how best to add this functionality? Could we add claimed surfaces without making many changes to our system? As it turns out, it took very little effort at all to add this functionality while keeping the unclaimed surfaces working.

As it stood, we had cucumber features for unclaimed surfaces.
Note: in the interest of brevity, I’m only going to show the basic cucumber scenarios.

Feature: Creating an unclaimed surface

  Scenario: Create surface from new surface page
    Given I am on the new surface page
    When I submit the surface name "foo"
    Then I should be on the surface page for "foo"

And it was passing. I wanted to add something like:

Feature: Creating a claimed surface

  Scenario: Create surface from new surface page
    Given I am logged in as user "coreyhaines@example.com"
    And I am on the new surface page
    When I submit the surface name "foo"
    Then I should be on the surface page for "foo" belonging to "coreyhaines@example.com"

The first step we did was to implement user registration/login/etc. Well, to say we ‘implemented’ it would be a bit of overkill. After all, we are in the rails ecosystem. We downloaded Clearance, by the prolific guys at thoughtbot and went through the quick and easy instructions to implement a ready-made user-authentication system. In the end, I think we spent about 4 pomodoros this. Why so long? Well, we initially had used an older version, found they had a dependency on Factory-Girl (go figure), so we had to install that. The Clearance-generated cucumber features for user and session functionality were still failing. We stumbled a bit creating our own factories, as they hadn’t been brought over when we generated. After a pomodoro, or two, we decided to look again at the documentation and realized that there was a newer version. We scrapped what we had, installed the newer version, generated it, and voila, everything worked great. So, we now had a working user authentication system, which also included registration (with confirmation emails) and forgotten password. Yeah, Clearance is pretty awesome.

But, this was just a precursor to getting our own cucumber feature passing. Let’s start going through the ‘change the message or make it pass’ loop to get it implemented. First pass, we get that the “I am logged in as user…” step isn’t defined. Well, looking at the Clearance-generated scenarios, we see that we can use the following steps:

Given I am signed up and confirmed as "coreyhaines@example.com/password"
And I sign in as "coreyhaines@example.com"

to create a user and login. The feature changes to incorporate this.

Feature: Creating a claimed surface

  Scenario: Create surface from new surface page
    Given I am signed up and confirmed as "coreyhaines@example.com/password"
    And I sign in as "coreyhaines@example.com"
    And I am on the new surface page
    When I submit the surface name "foo"
    Then I should be on the surface page for "foo" belonging to "coreyhaines@example.com"

Now, the creation of the surface uses the same steps as the unclaimed surface scenario, so we don’t have any worries there. In fact, I’m happy that we can reuse those, as we want the user experience to be the same whether you are logged in or not. The rub is that last step:

Then I should be on the surface page for "foo" belonging to "coreyhaines@example.com"

When we run cucumber, we find that there is no path defined for this step. We have a path for an unclaimed surface, but nothing for specifying it is claimed. At this point, we notice that there is a bit of a language mismatch. From a rails perspective, we are talking about surfaces belonging to a user, but we keep bouncing between the terms ‘belonging to’ and ‘claimed.’ Sarah talked about the importance of keeping the metaphor going through our language (ubiquitous language as James Martin points out in the comments to her post), so let’s change this step:

Then I should be on the surface page for "foo" claimed by "coreyhaines@example.com"

Changing the term didn’t get us any closer to having a path for it, though. Let’s go look at implementing it.

when /the surface page for "([^"]*)" claimed by "([^"]*)"$/
  surface = Surface.find_by_name($1)
  user = User.find_by_email($2)
  user_surface_path(user,surface)

When I run this, I find that I don’t have a user_surface_path. Of course I don’t, because the routes only have

map.resources :surfaces, :has_many => :stickies

This provides me with all the basic xxx_surface routes, but I want to also support having routes that include a user. Reading through the rails documentation a bit (routing is always one of those places that I stumble upon new capabilities), I find that I can add some options:

map.resources :surfaces, :has_many => :stickies,
              :path_prefix => '/users/:user_id', :name_prefix => 'user_'

I want to support both, so what happens if I just put add the above line, keeping the basic map.resources :surfaces above it? Will I get two sets of routes? Spoiler Alert: Yes, it works. So, if I do a rake routes, I’ll see both the basic surface routes, as well as ones related to xxx_user_surface routes. Very sweet! Let’s run cucumber and see where we stand. Ah, the functionality seems to work, but the path we are on is wrong:

expected: "/users/1/surfaces/foo",
got: "/surfaces/foo" (using ==)

This makes sense, we don’t have anything that would cause the controller to route us to different URL. Now, we are using resource_controller, so I actually think this should be given to us for “free.” Let’s see if what it would take. Well, first off, we need the new surface form to send to the correct url:

unclaimed: POST /surfaces
claimed: POST /users/:user_id/surfaces

This is a matter of using the Clearance helpers. Let’s change from

-semantic_form_for surface do |form|
  -form.inputs do
    = form.input :name
    = form.buttons

to

-action = signed_in? ? user_surfaces_path(current_user) : surfaces_path
-semantic_form_for surface, :url => action do |form|
  -form.inputs do
    = form.input :name
    = form.buttons

This should cause the form to post to the desired url depending on whether we are signed in.

When we run this, we still don’t get routed to the correct url (still going to /surfaces/foo). This is because the surfaces controller doesn’t realize that we are trying to scope our surface to a user. Luckily, we are using James Golick‘s most excellent resource_controller gem (yes, it really is most excellent). How does this help us? Well, it supports nested controllers. All we have to do is tell the controller that surfaces can belong to users by adding the following line to the surfaces controller:

belongs_to :user

Yup, that’s all it takes for the controller to become aware of a relationship between the user and the surface. When we run our cucumber feature, though, we get an exception at an unexpected point in the scenario:

Given I am signed up and confirmed as "person@example.com/password"
And I sign in as "person@example.com/password"
  undefined method `surfaces' for # (NoMethodError)
  (eval):2:in `click_button'
  ./features/step_definitions/webrat_steps.rb:20:in `/^(?:|I )press "([^\"]*)"$/'
  features/create_surfaces_logged_in.feature:4:in `And I sign in as "person@example.com/password"'

This makes sense. When we log in, we are going to the index page for surfaces. Resource Controller is trying to set the @surfaces variable to the surfaces scoped to the user we just logged in as (after login, we route to /users/:user_id/surfaces). This is an easy enough fix, let’s add the relationship to the User model:

Given I am signed up and confirmed as "person@example.com/password"
And I sign in as "person@example.com/password"
  undefined method `surfaces' for # (NoMethodError)
  (eval):2:in `click_button'
  ./features/step_definitions/webrat_steps.rb:20:in `/^(?:|I )press "([^\"]*)"$/'
  features/create_surfaces_logged_in.feature:4:in `And I sign in as "person@example.com/password"'

Let’s run our cucumber feature. Wow! It passes. Let’s run the cucumber feature creating an unclaimed surface. Beautiful! That passes, as well. So, looking back, we added the ability to create a claimed surface by adding effectively 3 lines of code: get the form posting to the correct URL, let Resource Controller know that surfaces can belong to users and let the user model know that it has surfaces. Pretty sweet!

At this point, a question comes up: where are the rspec-level examples? Why didn’t I write any isolation tests? This is a great question, and an interesting discussion point around the level of examples that are needed to drive out declarative statements for the underlying framework. I don’t generally write an example for model relationships, relying on some behavior to cause me to write them. In this case, the model relationship was driven by the cucumber scenario. The belongs_to declaration in the surfaces controller sits in the same space for me: I’m declaring a relationship to the underlying framework, Resource Controller. The last question is the logic in the view, deciding which url to use. I tend not to write view specs, relying on cucumber to tell me if there is something missing. This is logic, though. Shouldn’t it be tested? There are definite arguments for it. Actually, as we began rippling the concept of claimed surface through the rest of the CRUD operations on surfaces, we found this pattern to appear multiple times, resulting in a very definite need to refactor away the duplication. When refactoring, the tests are there to give us confidence that we haven’t broken anything. In this case, the cucumber scenarios provide us with that confidence. They do this, because the scenarios were failing until the logic was added. This gives me a sense of security that they will catch any mistakes I make.

As we filled out the rest of the CRUD operations on claimed surfaces, we found that we also needed to add the declaration to the surface model that it belonged to a user. This was

class Surface < ActiveRecord::Base
  belongs_to :user
end

Adding this line completed the relationship between a surface and a user, and the stickies project now had the concept of ‘claimed surfaces.’ Once Clearance was installed, the driving out of the complete claimed surface CRUD took 4 pomodoros: 2 hours. Pretty quick work of what could have been a complicated architectural change.

Just as a base point, the app currently supports user/session functionality, CRUD operations on claimed and unclaimed surfaces, and CRUD operations on stickies assigned to a surface. Here are the code stats (not including javascript or plugins):

+----------------------+-------+-------+---------+---------+-----+-------+
| Name                 | Lines |   LOC | Classes | Methods | M/C | LOC/M |
+----------------------+-------+-------+---------+---------+-----+-------+
| Controllers          |    45 |    36 |       4 |       2 |   0 |    16 |
| Helpers              |     3 |     2 |       0 |       0 |   0 |     0 |
| Models               |    19 |    16 |       3 |       0 |   0 |     0 |
| Libraries            |     0 |     0 |       0 |       0 |   0 |     0 |
| Model specs          |    58 |    51 |       0 |       0 |   0 |     0 |
| View specs           |     0 |     0 |       0 |       0 |   0 |     0 |
| Controller specs     |    95 |    81 |       0 |       0 |   0 |     0 |
+----------------------+-------+-------+---------+---------+-----+-------+
| Total                |   220 |   186 |       7 |       2 |   0 |    91 |
+----------------------+-------+-------+---------+---------+-----+-------+
  Code LOC: 54     Test LOC: 132     Code to Test Ratio: 1:2.4

Random Fact: this blog post was written at around 38000 feet above the atlantic ocean

“Explain this little world of yours”

or

“This thing you’re describing: What’s it like? How does it work? What makes it special?”

The first time I wrote the stickies project, I created the following resources: Users, Stickies, Projects. It was remarkably simple. There was also the concept of Groups (a cluster of related stickies); and a Dock (a place to move those groups out of the way). Beyond that, though — go get a hamburger, we’re done. We’ve got users, the people using the application; stickies, those little sticky notes; and projects, well…

Wait.

I’d chosen “Project” without thinking about it too much. Having projects and thinking about new ways to keep track of projects is one of our favorite occupations as web developers (and people) these days. Plus, it’s a status symbol. Have a lot of projects! Yum, projects. Yum, to-dos. Yum, airport-bookstore-manage-your-life books.

Yum.

However, had I been on the Domain Modeling ball, I would have seen that when I sat down and stuck stickies to the floor, table, or wall, it had more to do with cataloging a tumbleweed of thoughts and feelings, creating clustered relationships and visualizing a brain dump than doing project related tasks such as creating milestones, to-dos and deliverables. Well, I actually did know that, but I would have also said…

Hey, wait! While there’s nothing stopping a user from using stickies to flesh out a particular, extant project or to start a new one — hell, the stickies project even hooks into the Basecamp API because somewhere on your living room rug you might find the seed of a project and want to manage it — project management is not where the impulse to stick originates.

What I had been calling a Project was really… a big, open, preferably flat, preferably indoor, often private, always dry… surface.

And so we changed “Projects” to “Surfaces”.

Big deal, right? While it may seem like a minor name change that affects a few files, getting the domain name right can have a small, then bigger, then biggest-of-all effect on the design and world of your application. It’s similar to character development as a writer or a director: observe and listen to your subject until you find their unique twitch, their particular motivation. Finding this can drive their purpose, save them from cliche, and make them real to the audience.

While steering clear of cliche is an ongoing task, clarifying the “surfaces” domain has led us to some organic ideas for the design. Ideas that we hope will enrich the application. Getting closer to the “real world” of sticking will allow us to create a more specific “web world” of stickies.

This experience has helped me to recast “Domain Modeling” in my mind to simpler things, such as listening to your environment, paying attention to what you or your clients are actually doing, and steering clear of the default classification buckets in our minds. Use all the tools you have handy and feel comfortable with, but remember that getting the domain right starts before the tools come out: it’s more of a paying attention kind of thing.

In the theater, actors are encouraged not act out an emotion, but to try to achieve a specific objective. Who wants to watch someone “act sad”? A similar directive for us as application developers would be to look out for general types of things we think we understand (such as “projects”) and instead focus on the little, simple, tasks we are actually trying to represent. You might find that everything changes shape.

Find the twitch: that unique and domain-centric something that needs to be expressed, and then delve deep.

So, Sarah and I have sticky notes being added, moved, editing, persisted, etc., and the application is coming along nicely. In fact, we are getting close to opening up the first public beta. Just having stickies is only good for a single decision, so the two remaining features are surfaces and users. The process we are modeling, as Sarah outlines in the original screencast, is a large surface with stickies moving around. So, using that metaphor, we are adding the concept of ‘surfaces,’ separate areas that you can add and manipulate stickies on. We already have a single-surface implementation done, so it is just a matter of having them associated with a specific surface.

We started discussing implementation details, and I brought up a technique that I learned from Joe Fiorini a while ago about resource modeling via URI. The basic idea (it can get more complex) is to focus on the URIs and the behaviors related to specific HTTP verbs. I mentioned this to Sarah, so we got out the whiteboard markers and her well-used eraser, and we began mapping both how users would interact with the system and how the application would interact with the backend resources. I didn’t do it exactly as I learned from Joe, but the slightly looser form I used achieved our goals.

Here’s a view of our final board, and I’ll make some comments on it:

From TheStickiesProjectBlog

Side Note: Yes, that is a big-ass, framed whiteboard on Sarah’s living room wall. Tell me that does not equal AWESOME!

One of the first things we talked about was

GET /surfaces/:name(.format)

as the canonical accessor for a surface and its stickies. When accessed via html, it would display the surface layout + the necessary javascript calls to place the stickies on the surface. One interesting feature that I really pushed for, inspired by http://tomatoi.st (the pomodor timer that we use while coding), is the idea that doing

GET on /surfaces/:non-existing-surface-name

would create that surface for you. I like the idea of just being able to create a new one as simply as possible. Sarah was worried about having too many of them just floating around, so we decided on having a cleanup job that would remove any surface that had not seen activity for an hour. I do worry about the possibility of a DOS attack, but, if we get to that point, then we can look at throttling techniques, maybe IP-based, as a simple workaround. I’d hate to think someone would do that to us, though. :) This also means that sharing a surface would be as simple as sending the URL.

I’ll write more later about some of the other design decisions we made from this, but I wanted to get this up, especially to talk about the first interesting feature we are planning.

One of the first things that we’ll need to do is be able to edit the content of a sticky. We decided on using the jEditable component, as it seemed the easiest to integrate, and it was really high up on the google page. In this series of blog posts, I’m going to take a look at how we went about not only integrating the component, but also how we went about improving our design through shifting to a TDD approach and listening to what the tests were saying as they guided and influenced our design. Along the way, I learned some valuable lessons about bringing old habits from other language styles over without thinking about them. That comes later, though.

Link to the gist for all the code samples

Do I even know the javascripts?

It has been a long time since I wrote serious JavaScript; I think the last time I did what I would call an actual ‘JavaScript application’ was in 2002, or so. Sure, I’ve written a few things here and there. In fact, at the startup I worked at, I wrote a couple in-browser things that I was proud of at the time (looking back, naturally, I can see the parts that I’m not so proud of). But, all-in-all, most of what I do has been pretty non-dynamic. Back in 2002, I’m pretty sure I was only seeing the beginnings of JavaScript frameworks. There were some libraries coming out, but I seem to remember them being very focused on hiding the differences between DOM implementations. I wrote a couple things back then, but nothing incredibly crazy; I remember writing a client-side form validation library that was pretty damn sweet for the time. :)

So, both my JavaScript and JavaScript testing skills were a bit rusty. I’ve used this as an example before when talking about using the term ‘pragmatic’ to really be a cover over lack of skill: I never tested my JavaScript, not because I was pragmatic about testing, but because I flat-out didn’t have the skills needed to do it effectively. This was one of the reasons I was so excited to work on The Stickies Project: as I outlined initially, this application is going to be almost entirely JavaScript, so I will have a great opportunity to patch what I consider a significant hole in my skillset. After setting up BlueRidge, I began writing some examples for my code, but I found that, while I was writing tests, I wasn’t really doing TDD; I was writing some functions, trying to figure out how to get the desired behavior, while writing tests alongside them.

Figuring out the component

At first, I was just trying to get things working, figuring out how the component worked, so I wrote the following spike code:

function update_sticky_text(value, settings) {
  var stickie = $(this);
  console.log("value " + value + " settings " + settings + " this " ));
  var url = sticky_update_url_for(stickie);
  console.log("url " + url );
  // jQuery.post(url, {content : value, method : 'put'});
  return value;
}

function sticky_update_url_for(sticky_div){
  return sticky_div.attr('data-update-url');
}

Screw.Unit(function(){
  describe("getting information from sticky div", function(){
    it("can get the update url", function(){
      sticky_div = $("#sticky_23");
      sticky_div.attr('data-update-url', "/stickies/25");
      expect(sticky_update_url_for(sticky_div)).to(equal, "/stickies/25");
    });
  });
});

Hmmm… Reflection

Yeah, looks pretty bad. But, it was enough to learn the jEditable component, so I was pretty happy. However, I definitely had a few major problems with the code:

1. global functions
2. no sense of cohesion other than being in the same file for these two functions, even though the dependency was there
3. #sticky_update_url_for was not used anywhere else, only by #update_sticky_text
4. no test coverage for the #update_sticky_text function.

Learning from the spike

Now that I had finished the spike, it was time to actually write some code. I had identified some design problems with the resulting code, and I was curious to see how those problems would be resolved. Before moving on, though, we took a bit of time to learn some more about ScrewUnit. I had learned the expect(…).to(…) syntax, but wasn’t sure what the setup was for checking if methods are called. I’m tend to do collaboration-style tests, so it is important for me to be able to set expectations on method calls. I wasn’t ready to jump into using a mocking framework, so I decided to stick with the simplest way I knew how: replace the method with your own that sets a flag if it was called. Something like this should suffice:

Screw.Matchers['expect_called'] = function(obj, func_name, block){
  var got_called = false;
  obj[func_name] = function(x) { got_called = true; }
  block();
  this.expect_true(got_called);
};


// used like this
it("calls #parent_sticky", function(){
    expect_called(this, 'parent_sticky', function(){
    old_update_sticky_text("foo", null);
  });
});

This is the easiest way to check if something was called, but, of course, it doesn’t reset the function at the end (I wrote that later), so it isn’t perfect. But, this allowed me to write isolation-based examples for my functions. With this in hand, I was equiped to write a full set of examples for what was going to be known as #old_update_sticky_text:

describe("#old_update_sticky_text", function(){
    
    before(function(){
      this.sticky_update_url_for = function(x) { return null; }
      this.parent_sticky = function(x) { return null; }
      this.update_sticky = function(x) { return null; }
    });

    it("returns the value passed in", function(){
      var value = old_update_sticky_text("foo", null);
      expect(value).to(equal, "foo");
    });

    it("calls #parent_sticky", function(){
      expect_called(this, 'parent_sticky', function(){
        old_update_sticky_text("foo", null);
      });
    });

    it("calls #sticky_update_url_for", function(){
      expect_called(this, 'sticky_update_url_for', function(){
        old_update_sticky_text("foo", null);
      });
    });

    it("calls #update_sticky", function(){
      expect_called(this, 'update_sticky', function(){
        old_update_sticky_text("foo", null);
      });
    });
});

So, I was pretty happy that I was able to write isolation tests, but I was still annoyed by the other problems, primarily what I considered to be the big problems of global functions and lack of a sense of cohesion. My experiences have led me to trust in TDD to guide me when I’m not 100% sure where to go. Let’s get going. I’ve comfortable enough with ScrewUnit now, so I thought I would just jump in head-first.

Let’s try some TDD

First example? How about this:

require("spec_helper.js");
rails_require('tsp');

Screw.Unit(function(){
  describe("TSP", function(){
    describe("#update_sticky_text_handler", function(){
      it("returns the value passed in", function(){
        var value = TSP.update_sticky_text_handler("new text", null);
        expect(value).to(equal, "new text");
      });
    });
  });
});

It felt somewhat reasonable. This is a handler across all the sticky object editable components, so hanging off a TSP (the stickies project) object feels like it will at least afford me a bit of cohesion while I figure out a better method.

Now to get it passing:

var TSP = {
  update_sticky_text_handler : function(value, settings){
                                 return value;
                               }
};

There, that made it passed, plus satisfied the first behavior that the jEditable component required: the handler returns the new value. In our case, we didn’t need anything fancy, so this was good enough. Of course, this didn’t do much, so we need to add the code that would interact with the back-end. The jEditable component executes the handler in the context of the inline editor div, so ‘this’ would be that div. The schema for a sticky was starting to look like:

<div class='sticky'>
  <div class='editable' id='sticky_23'></div>
</div>

Looking at this, and knowing that we were executing in the context of div.editable, it seemed naturally to have a 2-step process for updating the sticky:

1. construct some sort a sticky object from the div.editable
2. call #update_content on the sticky object

Reflecting on the work so far

• I felt really good with the way that things were progressing, especially how the spike led me to some conclusions about my code and drove me to learn ScrewUnit a bit more. The side-by-side testing on the spike gave me confidence with the toolset, so I was able to build some examples with the code there to base it on.
• By holding myself to a bit of isolation, I see that an abstraction has snuck in: ‘sticky object.’ What is going to be? I don’t totally know at this point, but I do know that it is constructed from div.editable somehow and it has an #update_content method which, apparently, updates the content in the backend.
• Having a global TSP object feels a bit weird. It is going to be shared between everything, and that makes me uncomfortable. Of course, it is much better than just having free-floating functions out in the world. Not the spoil the surprise, but having a global object like this causes me a bit of pain and annoyance soon, so I end up getting rid of it. :) But, that is a story for the near future.

What is coming up in the next installment

I’ve got an idea of what needs to be done, so it is time to write the examples for the updating process and implement the code. Also, we’ll start writing more examples, learn the smoke framework, get annoyed with the smoke framework, realize that our annoyance is telling us something about our preconceptions, accept that our frustration has a lesson hidden in it, then listen to what the difficulties tell us about our design.

This post will discuss my experiences setting up and trying out the Blue Ridge JavaScript testing environment.

My previous experience with testing JavaScript was almost non-existent (I did a tiny bit with my own assertEquals function), so it was time to settle down and do some learning. There are a lot of JavaScript testing solutions out there, but, based on my knowledge of the maintainers, I chose to use Blue Ridge by Relevance Software. I know those guys, having spent a couple months working with them, and I have a lot of respect for their code. There are other blog posts (Jason Rudolph’s and Dr Nic’s) that outline the inner details and usage of Blue Ridge (it packages other tools, such as ScrewUnit, to form the whole solution), so I’ll just write here the steps I took to set it up. I was a bit nervous about what effort it may take to get it up and running in my app, but, as you’ll see, it was trivial to get my first tests running. By no means am I a ScrewUnit expert, having only written a few tests now all in the form expects(x).to(equal,y), but after only a couple minutes of investigation, I had a test up and running in my own system.

Note: I know that Blue Ridge wraps a lot of other frameworks in a nice package, so some things that I attribute to Blue Ridge might actually be part of ScrewUnit or env.js or Rhino or Smoke, but I haven’t done the deep-dive to figure out which parts are which. So, for the sake of my sanity and time, I’m going to just say everything is part of Blue Ridge. If I mention some feature that is part of one of the packaged frameworks, feel free to put a comment here that sets the record straight.

I want to stress that, while I’m learning the framework, I am doing a combination of test-first and test-while programming, not TDD. In other languages, where I am comfortable with the tools, I live in a fairly strict BDD workflow, but I’m still getting used to the tools here. So, as JB Rainsberger talks about, I’m still at the point of worrying about testing and not ready to listen to what they are telling me about my design. Also, while I’ll be looking at jsSlim in the future to fill the heart-shaped hole in my chest that keeps me from doing a nice BDD workflow in the javascripts (I worked on the original RubySlim implementation, so I have a sweet spot in my heart for slim. Plus, I saw Uncle Bob talk about the latest and greatest things in FitNesse last week at the Columbus Ruby Brigade, and I must say that I am pretty damn impressed), I don’t have the tools, yet. So, I’m starting at the beginning and building up to TDD.

Setting up Blue Ridge

Holy Shit! Talk about easy to setup. I followed the instructions in the readme in the project, and, what do you know, they were right. Here’s a summarized version of them:

1. install the plugin (command)
2. generate a spec file for your js file
3. run rake spec:javascripts
4. add spec:javascripts to my default rake task

Note: application_spec.js
It is worth mentioning that I deleted the application_spec.js file. I usually delete my application.js file when I init a new rails app, as having it there sets a bad precedent as a dumping ground for the javascripts. I like to keep mine organized, just like I do in other languages, so, since we were dealing with stickies, I generated a stickies_spec.js to go along with the stickies.js file.

HTML Fixtures

A nifty part of Blue Ridge is the html fixtures. They provide a dom that I can configure in my own way to test out my codes. It was nice to use it as a proving ground for the structure of my html, which I could then use as a concrete example when building my views. A happy side-effect was that it showed a few places where I felt the need to write a view spec. This was surprising to me, as I generally don’t write them.

For example, the main user-interface element is the sticky. The visual representation of the sticky is a div.sticky, and, especially since we were still building towards the appropriate javascript abstraction, it was important to have a good schema for the it. When posting new content (using the inline editing component jEditable), we needed to have the uri for updating the sticky. Being a good little boy, I decided that it should be generated on the server and passed with the sticky, so I needed a place to put it that was accessible. The sticky content was a child div (.editable), and I first put the uri as @data-update-url at this level, but, as I was writing the javascripts for posting any new content to the update uri, it became clear that the update url was not associated with the content, but was related to the sticky, itself. So, up it moved to the .sticky div. This seemed pretty important to me, so I quickly generated a view spec and wrote an example for showing that the @data-update-url was being correctly populated on the div. As expected, it failed, so I jumped over the view and moved it to the correct place. Growl growled at me that all was green, and, appropriately enough, the birds started singing happy songs about the green bars of lore.

HAHA! I just told Sarah “a couple paragraphs above, I mentioned that I wasn’t doing TDD with javascript, then I realized that I wrote a paragraph about how my tests recommended some design improvements.”

Well, that’s it for now. I’ll be writing more blog posts with details about testing the javascripts later!