Genetic Symphony – A Genentech, IDEO, and Carbon Five collaboration for TED2012. Participants provide a genetic sample via a cheek swab, which is processed overnight and used to generate a unique song and visualization. Tech includes: Backbone, CoffeeScript, Audia, PhoneGap, SoX, RMagick, Rails, Jasmine and Sinon.

Presenters: David Hendee and Sean Durham, Carbon Five

ChatOS – A collaborative UX/programming experiment that allows participants to build a shared real-time web experience. It provides the basic plumbing that makes collaborative programming possible and leaves it up to the participants to build the tools and design the interactions. The talk will provide a live, interactive demonstration, and will briefly cover the technology behind the application including Node.js, Mocha.js, HTML 5, Web Sockets, and Mongo DB.

Presenter: Alex Cruikshank, Carbon Five

Escape from the Pyramid of Doom – If you set out to build real, reliable apps using Node.js you will need to tame the callback-based asynchronous jungle you find yourself in. For the last several months at Good Eggs we have explored solutions that include a combination of third party libraries, homegrown libraries, and convention. For this talk, we use our journey to provide a survey of different techniques for writing asynchronous code in Node.js including fibrous, the library solution that we currently use to support our established conventions.

Presenters: Alon Salant and Randy Puro, Good Eggs

Q & A – We want to continue discussing anything already mentioned, or go over other topics that might be interesting (e.g. js testing, tech stacks, hosting, project management, etc).

Wednesday April 25th. Doors at 6 and talks start around 6:30. Food and drinks will be provided. Huge thanks to CBSi for the venue and sponsoring food/drinks!

Please RSVP on the SF JS meetup event page!

Learn more about Dart at http://dartlang.org.

Thanks Seth! Looking forward to the next one.

While more and more of our clients are engaging us in full-service design/build projects, we still enjoy working with outside or on-staff designers. And even when we are providing design services, we always want to maximize the collaboration between the designers, engineers and business owners on our projects.

Last year, Janice Fraser of LUXr introduced us to an activity called the “Wireframe Walkthrough.” It’s probably something you’re already doing on projects without quite putting a formal name or process around it. We’ve taken the activity and deconstructed it a bit, added our insights, and put a fancy title on it in the hopes that others will try it out and add their experience and wisdom.

What is it?

A collaborative design critique from a technical perspective to identify hard features and suggest alternatives.

Why do it?

By engaging designers and engineers in a constructive discussion of tradeoffs you stand to get more bang for your development buck. Posting wireframes on walls also helps externalize ideas and define the project’s collaborative space.

When to do it?

It’s typically done weekly during the planning session as the designers generate wireframes for the next iteration or two; but it can be done any time and should definitely be done during kickoff.

How to do it?

1. (Designer) Print out and post the latest wireframes on a wall at gallery height. Find a developer and put them at arms length from the drawings.
2. (Developer) Ask about the current state of the designs and what kind of feedback they’re looking for. Find out if the designer is more interested in generative or evaluative feedback. Try asking “Where are you at?”
3. (Designer) Let the developer know about your goals for the walkthrough. For instance, say “I’m really interested in hearing your thoughts on…”
4. (Developer) Acknowledge the challenge. Good design is as hard as writing good code. Share some enthusiasm. Then walk through the flow, pointing where your mouse would be. Narrate what you are thinking and doing as a user. Say things like “I’m trying to find the contact us page.”
5. (Designer) Take notes on stickies. Place the stickies directly on the wireframes to mark the location of the comment or observation. This is essentially a free usability test!
6. (Developer) Note missing functionality or difficult technical challenges. Ask questions about the user rather than making statements. For instance: “How would I find a forgotten password?” rather than “You forgot the forgot your password screen.” Keep in mind that this is a cooperative discussion about the design, not a judgement on the designer.
7. (Designer) Take notes and offer insights into the current design solution. Listen, breathe, and try not to get defensive (or think of elephants). Postpone deep or off-topic discussions. For instance, say “That’s something we’ve been really struggling with. We should schedule a meeting to talk about that after.”
8. (Developer) Suggest alternatives to any particularly challenging engineering implications. Try engaging the designer with phrases like “What user need are we trying to address here?” or “We could try… and get a similar result with less effort.” Challenge yourself and throw the designer a bone by saying something like “This is the main feature so it makes sense that we spend extra time on it.”
9. (Designer) Thank the developer. Incorporate feedback as appropriate. Rinse and repeat. It’s better to do this a little bit all the time.

That’s it! Please let us know if you have any tricks or tips to add, or if you have a suggestion for our next Lean UX ‘recipe.’

Integrating with an External API

Our example app is a stock Rails 3.2 app. Let’s imagine that we’re assigned the following story:

In order to find interesting links for the intellectually curious
As a user
I want to see the latest Hacker News posts on the homepage

This story involves integrating content from an external site. Hacker News doesn’t have an API, but they do have an RSS feed that we can use instead.

The Testing Strategy

A typical implementation of our story will look something like this:

1. A request for the homepage is routed by Rails to a controller.
2. The controller asks a Post model for recent posts.
3. The Post model asks a Hacker News library for recent posts.
4. The Hacker News library gets the latest posts from the Hacker News RSS feed.

To test this we’ll:

1. Start with an end-to-end integration test. I like to use RSpec, so we’ll use RSpec Rails’ request specs. vcr will be used to record the actual Hacker News HTTP request and response.
2. Skip controller specs. Directly specifying the controller won’t gain us much, because it will be thin and completely exercised by the request spec.
3. Mock out the Hacker News library in the Post model’s specs. Since we already have an integration test, there’s no need to perform another mini-integration test between our domain model and its collaborator.
4. Specify the Hacker News library directly. Instead of mocking, we’ll again use vcr to record the actual Hacker News HTTP request and response. This will give us the ability in the future to change our HTTP client without breaking our specs.

Starting at the Outside with a Request Spec

Our request spec uses capybara to simulate a homepage request. We tell vcr to record any HTTP requests by using its RSpec metadata support.

spec/requests/homepage_spec.rb

require 'spec_helper'

describe 'The homepage', :vcr do
  before do
    visit '/'
  end

  it 'displays recent posts from Hacker News' do
    hacker_news_links = all '#hn .post a'
    hacker_news_links.should_not be_empty
    hacker_news_links.each do |link|
      link[:href].should match(%r{http://news\.ycombinator\.com})
    end
  end
end

The first time this spec is run, vcr will record the actual Hacker News HTTP request and response and save it to the filesystem. Future spec runs will then reuse this recorded HTTP interaction. Since we don’t know the latest posts on Hacker News at the time this spec is first run, we only specify an expected DOM structure.

$ rspec spec/requests/homepage_spec.rb                                                                                                                                  
F

Failures:

  1) The homepage displays recent posts from Hacker News
     Failure/Error: visit '/'
     ActionController::RoutingError:
       No route matches [GET] "/"
     # ./spec/requests/homepage_spec.rb:5:in `block (2 levels) in <top (required)>'

Finished in 0.05392 seconds
1 example, 1 failure

This failing spec guides us to the following controller and view implementation.

config/routes.rb

Sample::Application.routes.draw do
  root to: 'posts#index'
end

app/views/posts/index.html.haml

#hn
  - @recent_posts.each do |post|
    .post
      = link_to post.title, post.url

app/controllers/posts_controller.rb

class PostsController < ApplicationController
  def index
    @recent_posts = Post.recent
  end
end

The second run of the request spec goes further than the first, moving us to the domain model.

$ rspec spec/requests/homepage_spec.rb                                                                                                                                  F

Failures:

  1) The homepage displays recent posts from Hacker News
     Failure/Error: visit '/'
     NameError:
       uninitialized constant PostsController::Post
     # ./app/controllers/posts_controller.rb:3:in `index'
     # ./spec/requests/homepage_spec.rb:5:in `block (2 levels) in <top (required)>'

Finished in 0.07371 seconds
1 example, 1 failure

Mocking Collaborators in the Domain Model Spec

Instead of programming our controllers and views to the interface of our Hacker News library, we’ll introduce a domain model. The domain model is where we’ll consolidate our app’s business logic. It also gives us another level of indirection, allowing us in the future to change how we get Hacker News content without having to change our controllers and views.

Our domain model won’t directly make any HTTP requests. Instead, it will collaborate with a separate Hacker News library that will be responsible for making HTTP requests and parsing RSS. This library acts as an adapter layer, allowing our domain model to define its relationship to the outside world in its own terms. With an integration test already in place, we can use mocking to test our domain model in isolation.

spec/models/post_spec.rb

require 'spec_helper'

describe Post do
  describe '.recent' do
    before do
      posts = [
        { title: 'Post #1', url: 'http://example.com/1' },
        { title: 'Post #2', url: 'http://example.com/2' },
        { title: 'Post #3', url: 'http://example.com/3' }
      ]
      HN::Post
        .should_receive(:recent)
        .and_return(posts)

      @recent_posts = Post.recent
    end

    it 'returns recent posts' do
      @recent_posts.should have(3).posts
    end

    it 'sets their title' do
      @recent_posts.each do |post|
        post.title.should be
      end
    end

    it 'sets their url' do
      @recent_posts.each do |post|
        post.url.should be
      end
    end
  end
end

lib/hn/post.rb

module HN
  class Post
  end
end

app/models/post.rb

class Post
  def self.recent
    posts = HN::Post.recent
    posts.collect do |post|
      new post
    end
  end

  attr_accessor :title,
    :url

  def initialize(attributes)
    self.title = attributes[:title]
    self.url = attributes[:url]
  end
end

Our domain model is now specified but a re-run of our request spec reminds us we still have work to do. Mocking allowed us to implement our domain model by faking its collaborator, but we still have to implement that collaborator. Whenever you mock, you must have a higher-level test that actually tests the full integration between all your objects.

$ rspec spec/requests/homepage_spec.rb
F

Failures:

  1) The homepage displays recent posts from Hacker News
     Failure/Error: visit '/'
     NoMethodError:
       undefined method `recent' for HN::Post:Class
     # ./app/models/post.rb:3:in `recent'
     # ./app/controllers/posts_controller.rb:3:in `index'
     # ./spec/requests/homepage_spec.rb:5:in `block (2 levels) in <top (required)>'

Finished in 0.066 seconds
1 example, 1 failure

We can now drop back down and spec out the Hacker News library.

Black-Box Testing the Library

Our Hacker News library will be responsible for getting the latest posts from Hacker News. Like in our request spec, we’ll use vcr to record the actual HTTP request and response to Hacker News. This keeps our spec accurate. Future runs of this spec will then reuse the recorded HTTP interaction. This keeps our spec fast. Stubbing at the HTTP level instead of mocking out our HTTP client, gives us the ability to change our HTTP client later (granted it’s one of vcr‘s supported HTTP clients).

spec/lib/hn/post_spec.rb

require 'spec_helper'

describe HN::Post do
  describe '.recent', :vcr do
    before do
      @posts = HN::Post.recent
    end

    it 'returns recently submitted posts from Hacker News' do
      @posts.should_not be_empty
      @posts.each do |post|
        post.should have_key(:title)
        post.should have_key(:url)
        post[:url].should match(%r{http://news\.ycombinator\.com})
      end
    end
  end
end

typhoeus and Ruby 1.9.3′s RSS library work together to request and parse the Hacker News RSS feed.

lib/hn/post.rb

require 'rss'

module HN
  class Post
    def self.recent
      response = Typhoeus::Request.get 'http://news.ycombinator.com/rss'
      feed = RSS::Parser.parse response.body
      feed.items.collect do |item|
        { title: item.title,
          url: item.comments }
      end
    end
  end
end

With our library specified, we can move back up to our request spec, which should now be passing.

$ rspec spec/requests/homepage_spec.rb
.

Finished in 0.1785 seconds
1 example, 0 failures

Staying in Sync with External APIs

In our request and library specs, we used vcr to record an actual HTTP request to Hacker News and then in future spec runs reused that recorded HTTP interaction. The specs were accurate and fast but, if the Hacker News RSS feed changes, our specs still continue to pass. We need to keep our stubs up-to-date.

Fortunately vcr can be configured to automatically re-record “out-of-date” HTTP interactions.

spec/support/vcr.rb

VCR.configure do |config|
  config.hook_into :webmock
  config.cassette_library_dir = 'spec/fixtures/vcr_cassettes'
  config.configure_rspec_metadata!
  config.preserve_exact_body_bytes { true }
  config.default_cassette_options = {
    re_record_interval: 1.week
  }
end

vcr stores a timestamp alongside every recorded HTTP interaction. The above default_cassette_options configuration tells vcr to re-record all HTTP interactions that are older than 1 week.

Summary

Depending on an external API in your test suite can easily lead to tests that sometimes pass and sometimes fail. To make your tests run consistently, stub out external APIs. Ensure your stubs are accurate by creating them from actual API responses. And finally, remember to routinely verify that your stubs are up-to-date with the current state of the external API.

What controls the keyboard anyway?

Our first exposure to different keyboard types probably comes from UITextField and UITextView. Both provide conform to the UITextInputTraits protocol which gives us options to set the keyboard type, return key type, keyboard appearance, and other behaviors. Those options cover many of the types of text input we might want to support; plain text, passwords, email addresses, urls, and so on. That’s a good place to start customizing our keyboard options but UITextInputTraits itself doesn’t present the keyboard so when we need behavior the protocol doesn’t provide we will have to keep looking.

Traversing up the class hierarchy we see that UITextField, UITextView, and indeed all UIView objects inherit from UIResponer. All of the responder objects in our views form a responder chain, a sequence of objects which will be given a chance to respond to non-touch input events. (If this isn’t a familiar topic then take a look at “Responder Objects and the Responder Chain” in the “Event Handling Guide for iOS” for a full discussion of how the system works.) Whenever a responder becomes the first responder (see -becomeFirstResponer) it determines what, if any, keyboard needs to be shown. UIResponder gives us two read-only properties for controlling the keyboard’s appearance; inputView which provides the keyboard itself and inputAccessoryView which controls the accessory view attached to the top of the keyboard (containing the “next” and “previous” buttons when editing a form in Mobile Safari for example). By returning our own views from these properties we can replace the system keyboards with any custom UIView we care to construct.

Start simple: customizing UITextView

UITextField (and UITextView) redefine their inputView and inputAccessoryView properties to be readwrite instead of readonly. When working with these view classes we can therefore set their keyboard easily from some other class, like our view controller.

Suppose we were want to support editing markdown formatted text in our app. The system keyboards work well for this but it takes three taps to enter a # or * and \ doesn’t appear on the keyboard at all. That’s going to make it difficult for our users to emphasize text or insert code blocks. Let’s add an input accessory view to give them “emphasize”, “strong”, and “code” formatting controls.

Given a simple view controller with UITextView *textView and UIView *accessoryView outlets we can set the text view’s inputAccessoryView in our -viewDidLoad.

@interface MarkdownViewController : UIViewController

@property (nonatomic, strong) IBOutlet UITextView *textView;
@property (nonatomic, strong) IBOutlet UIView *accessoryView;

@end

@implementation MarkdownViewController

@synthesize textView;
@synthesize accessoryView;

- (void)viewDidLoad
{
    [super viewDidLoad];
    self.textView.inputAccessoryView = self.accessoryView;
}

- (void)viewDidUnload
{
    [super viewDidUnload];
    self.textView = nil;
    self.accessoryView = nil;
}

@end

Now when the text view becomes the first responder we see our accessory view added to the top of the keyboard.

Responding to input

Showing our accessory view is only half of the solution. We also want to make changes to our text view’s content when a user taps one of the accessory view’s buttons. Let’s create a custom view class for our accessory view and give it a reference to the text field.

@interface MarkdownInputAccessoryView : UIView

@property(nonatomic, weak) id <UITextInput> delegate;

- (IBAction)toggleStrong:(id)sender;
- (IBAction)toggleEmphasis:(id)sender;
- (IBAction)toggleCode:(id)sender;

@end

@implementation MarkdownInputAccessoryView

@synthesize delegate;

- (IBAction)toggleStrong:(id)sender {
    UITextRange *selectedText = [delegate selectedTextRange];
    if (selectedText == nil) {
        //no selection or insertion point
        //...
    }
    else if (selectedText.empty) {
        //inserting text at an insertion point
        [delegate replaceRange:selectedText withText:@"*"];
        //...
    }
    else {
        //updated a selected range
        //...
    }
}

- (IBAction)toggleEmphasis:(id)sender {
    //...
}

- (IBAction)toggleCode:(id)sender {
    //...
}

@end

Our controller can then set the delegate property and the accessory view will be able to update the text field.

//...
@property (nonatomic, strong) IBOutlet UIView *accessoryView;
//...
- (void)viewDidLoad
{
    [super viewDidLoad];
    self.accessoryView.delegate = self.textView;
    self.textView.inputAccessoryView = self.accessoryView;
}

Adding complexity: keyboards for a custom UIView

Adding a custom input view is much the same as adding a custom input accessory view. When we’re working with a UITextField or UITextView we can create the custom view and pass it to the appropriate property’s setter.If however we have built a custom UIView subclass then we have to do a little more work.

If it still makes sense for a view controller or other class to provide the view with its input views then we can redeclare inputView and inputAccessoryView as readwrite properties, exposing setters so that the view can be given references to the input views it should use. Alternately we can override the inputView and inputAccessoryView getter methods to return appropriate views. I tend to prefer the latter option because it allows a view to how its own input controls should be presented but if selecting an appropriate input view depends on factors like the current interface idiom or language then it may make more sense for an external service to provide an input view for the current view.

If we wanted to build a view for displaying a score of sheet music we might build something like the following.

@class MusicScoreView;

@interface MusicScoreInputView : UIView

@property (nonatomic, weak) IBOutlet MusicScoreView *delegate;

@end

@interface MusicScoreView ()

@property(nonatomic, readwrite, strong) IBOutlet UIView *inputView;

- (void) loadInputView;

@end

@implementation MusicScoreView

@synthesize inputView;

- (id)initWithFrame:(CGRect)frame {
    self = [super init];
    if (self) {
        [self loadInputView];
    }
    return self;    
}

- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    if (self) {
        [self loadInputView];
    }
    return self;
}

- (void)loadInputView {
    UINib *inputViewNib = [UINib nibWithNibName:@"MusicScoreInputView" bundle:nil];
    [inputViewNib instantiateWithOwner:self options:nil];
}

@end

@interface MusicScoreInputView : UIView

@property (nonatomic, weak) IBOutlet MusicScoreView *delegate;

@end

@implementation MusicScoreInputView

@synthesize delegate;

@end

Visual styling: reacting to the keyboard

Now that we can display a custom keyboard we still need to make sure to adjust our views when it appears. Since the actual presentation of our input view is handled by UIKit we need to observe and react to the notifications the framework sends to announce changes in the input view’s position. Apple provides a set of NSNotifications we can observe:

• UIKeyboardWillShowNotification
• UIKeyboardDidShowNotification
• UIKeyboardWillHideNotification
• UIKeyboardDidHideNotification

Each of these notifications includes a user info dictionary which describes the frame of the keyboard before and after its transition and the timing of the animation which will be used to show or hide it. When we rotate a device the keyboard may be resized to better support the new orientation. In that case we’ll need to update the insets or positions of our other views as well to reflect these new dimensions. Again UIKit provides a set of notifications we can observe to determine the changing bounds of the keyboard and react accordingly.

• UIKeyboardWillChangeFrameNotification
• UIKeyboardDidChangeFrameNotification

Given these we can respond to the appearance or disappearance of the keyboard as needed.

- (void)viewWillAppear:(BOOL)animated {
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(updateScrollInsets:) name:UIKeyboardWillShowNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(updateScrollInsets:) name:UIKeyboardWillChangeFrameNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(resetScrollInsets:) name:UIKeyboardWillHideNotification object:nil];
}

- (void)viewDidDisappear:(BOOL)animated {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}

In most cases we will want to respond by adjusting the contentInset and scrollIndicatorInsets of a UIScrollView to add enough padding to the bottom of our scroll view’s content view that all of its content can scroll to a position above the top of the keyboard. Alternately we might adjust the frames of some of our views directly but this is less desirable because it might leave a blank region on the screen (rather than showing the scroll view’s background color), especially on an iPad where the user can choose to split the keyboard.

To calculate the appropriate insets we need to be aware that the keyboard is presented anchored to the bottom of the window, which is not necessarily flush with the bottom of the current view controller’s view (for example we might have a tab bar or tool bar visible). We should only add insets equal to the height of the portion of our view which is being hidden by the keyboard.

- (void) updateScrollInsets:(NSNotification *)notification {
    //determine what portion of the view will be hidden by the keyboard
    CGRect keyboardEndFrameInScreenCoordinates;
    [[notification.userInfo objectForKey:UIKeyboardFrameEndUserInfoKey] getValue:&keyboardEndFrameInScreenCoordinates];
    CGRect keyboardEndFrameInWindowCoordinates = [self.view.window convertRect:keyboardEndFrameInScreenCoordinates fromWindow:nil];
    CGRect keyboardEndFrameInViewCoordinates = [self.view convertRect:keyboardEndFrameInWindowCoordinates fromView:nil];
    CGRect windowFrameInViewCoords = [self.view convertRect:self.view.window.frame fromView:nil];
    CGFloat heightBelowViewInWindow = windowFrameInViewCoords.origin.y + windowFrameInViewCoords.size.height - (self.view.frame.origin.y + self.view.frame.size.height);
    CGFloat heightCoveredByKeyboard = keyboardEndFrameInViewCoordinates.size.height - heightBelowViewInWindow;

    //build an inset to add padding to the content view equal to the height of the portion of the view hidden by the keyboard
    UIEdgeInsets insets = UIEdgeInsetsMake(0, 0, heightCoveredByKeyboard, 0);
    [self setInsets:insets givenUserInfo:notification.userInfo];
}

- (void) resetScrollInsets:(NSNotification *)notification {
    UIEdgeInsets insets = UIEdgeInsetsMake(0, 0, 0, 0);
    [self setInsets:insets givenUserInfo:notification.userInfo];
}

- (void) setInsets:(UIEdgeInsets)insets givenUserInfo:(NSDictionary *)userInfo {
    //match the keyboard's animation
    double duration = [[userInfo objectForKey:UIKeyboardAnimationDurationUserInfoKey] doubleValue];
    UIViewAnimationCurve animationCurve = [[userInfo objectForKey:UIKeyboardAnimationCurveUserInfoKey] intValue];
    UIViewAnimationOptions animationOptions = animationCurve;
    [UIView animateWithDuration:duration delay:0 options:animationOptions animations:^{
        self.textView.contentInset = insets;
        self.textView.scrollIndicatorInsets = insets;
    } completion:nil];
}

Summary

We’ve seen how to define custom input and input accessory views to enhance or replace the system keyboard. How to add those input views to existing text fields, text views, and to our own custom view classes. When an input view does appear we can also now appropriately adjust the rest of our content to accommodate it. With these tools we should now be ready to build custom input views tailored to the type of data we need and the context in which it will be gathered.

The examples given above are also available at https://jonah-carbonfive@github.com/jonah-carbonfive/CustomInputViewDemo.git

JSONP

JSONP or “JSON with padding” is a technique that can be used to load JavaScript from a server in a different domain. JSONP takes advantage of the fact that JavaScript’s same origin policy doesn’t apply to the HTML <script> element. When using JSONP, the <script> element’s src attribute is set to a resource in another domain. This URL includes a callback parameter corresponding to a local JavaScript function. The server responds with JavaScript that calls this function, passing JSON as an argument. The client then evaluates this JavaScript, giving it access to the server’s data

In the following example, HTML from http://server1.example.com/ includes a <script> element to load JavaScript from a server in another domain, http://server2.example.com. The entire domain, including all subdomains, as well as the port number, are all used by JavaScript to determine if the server is in another domain. Here we have two apps at different subdomains within the same domain. The callback parameter is set to a local function defined in a previous <script> element.

http://server1.example.com/

The JavaScript returned from the server consists of a function call to parseUser, passing user #1 as JSON. Implementing this server-side logic in a Rails app is straightforward. ActionController::Base#render accepts a :callback option to specify the function to pass the resulting JSON to.

app/controllers/users_controller.rb

Let’s try this out (by running the Rails app locally) on the command line using curl.

DRYing up JSONP with Rack::JSONP

Repeating the same :callback option for multiple actions supporting JSONP quickly becomes tedious. rack-jsonp-middleware is a Ruby gem that includes a piece of Rack middleware that can take care of this repetition for us. For any JSONP request, rack-jsonp-middleware will strip the callback parameter value, forward the request on to Rails as if it were a JSON request, and then respond with JavaScript containing a function call to the callback parameter, passing it the returned JSON.

Using rack-jsonp-middleware will require a few changes to our client and server. Let’s first add the gem to our app’s Gemfile.

Gemfile

Then add it to the Rails middleware stack.

config/application.rb

rack-jsonp-middleware considers a request a JSONP request if the url ends in .jsonp. We’ll need to change the ending of our client url from .js to .jsonp.

http://server1.example.com/

rack-jsonp-middleware expects our server-side action to return JSON. Instead of handling JavaScript requests, let’s rewrite our action to return JSON. We can use ActionController::MimeResponds#respond_with and ActionController::MimeResponds.respond_to in our controller to simplify the implementation.

app/controllers/users_controller.rb

Testing this refactored version from the command line returns the same response as our previous implementation.

JSONP is a nice, simple solution for reading data from a server in another domain. But what if you want to write data? For that, there’s CORS.

CORS (Cross-Origin Resource Sharing)

CORS is a W3C standard, that specifies a way for a client to determine if a particular request can be made to a server in a different domain. With JSONP you’re limited to HTTP GET requests. CORS on the other hand, allows any type of request. It requires you to define who can do what to a given resource.

In CORS, the client first makes a “preflight” request to a server in another domain. This is an HTTP OPTIONS request, asking the server if the client can make a particular request. The “preflight” request includes CORS-specific headers specifying the client’s domain, the type of request they want to make (POST, GET, etc.), and any HTTP headers they want to send. The server response answers the request using CORS-specific headers. If the request is allowed, the client can then issue the cross-domain request.

Adding CORS support to a Rails app is easy with the rack-cors Ruby gem.

Supporting CORS in Rails with Rack::Cors

rack-cors handles CORS’s “preflight” requests by adding support for HTTP OPTIONS requests. It also includes a DSL for specifying on a per-resource basis, the allowable requesting domains, the types of requests, and the supported HTTP headers.

Let’s take a look at adding CORS support for updating and deleting users in our Rails app. The first step is to add rack-cors to our app’s Gemfile.

Gemfile

Then we’ll add it to the Rails middleware stack. This is where you configure your resources for CORS.

config/application.rb

Our configuration allows HTTP PUT and DELETE requests from http://server1.example.com to /users/\d+.json (we used a regular expression to match the user id in the URL). The allowable headers in such requests are:

• Origin – the domain from where the request will be made (this is required by CORS).
• Accept – the acceptable response media type.
• Content-Type – the media type of the body of the request.

Let’s try this out from the command line using curl (this is the exact same CORS “preflight” request that jQuery will make when sending a cross-domain AJAX request in a browser).

This “preflight” request uses several CORS-specific headers:

• Origin – the domain from where the request will be made.
• Access-Control-Request-Headers – a list of headers we want to send with our request.
• Access-Control-Request-Method – the type of request we want to make.

Essentially, this “preflight” request is asking the server at http://localhost:3000 if we can send an update from http://server1.example.com to one of its users.

The server response also includes several CORS-specific headers:

• Access-Control-Allow-Origin – the domains that are allowed to make a request to this resource (a value of “*” is a wildcard that matches any domain).
• Access-Control-Allow-Methods – the types of requests that are allowed (both PUT and DELETE in the above response).
• Access-Control-Allow-Headers – the allowable request headers.

rack-cors has also added some additional CORS-specific headers with default values:

• Access-Control-Expose-Headers – a list of additional response headers the client can access. By default, the client can only access simple response headers such as Content-Type and Last-Modified. rack-cors defaults this header to an empty list.
• Access-Control-Max-Age – how long (in seconds) the client can cache this “preflight” response. rack-cors defaults this to 20 days.
• Access-Control-Allow-Credentials – tells the client whether it should send cookies in CORS requests. rack-cors defaults this to true.

Browser Support for CORS

According to Wikipedia, CORS is currently supported by all major browsers (IE 8+) except Opera.

I recently used CORS to support an internal app. This meant only supporting Chrome, Firefox, and Safari. So far, I’ve had no problems using CORS in any of these browsers.

Fine-grained Access Control

The Access-Control-Allow-Origin header in CORS, gives us more flexibility and security than JSONP. Instead of opening up a resource to any domain using JSONP, we can create a whitelist of allowable domains, HTTP methods, and headers.

The Rise of Thick Clients

As client-side JavaScript MVC frameworks continue to rise in popularity, the same origin request policy becomes far too limiting. JSONP offers a simple workaround for reading data from servers in other domains. CORS is more complex, but it provides the ability to not only read but also write data.

JSON APIs are already trivial to implement in Rails. And thanks to Ruby gems, such as rack-jsonp-middleware and rack-cors, opening them up to thick client apps running on other domains is just as easy.

Happy JS hacking!

Outside-in development doesn’t require any specific tool or language. This article will demonstrate it in Rails, using two popular testing tools: Cucumber and RSpec.

Start with a High-level Specification

Starting with a high-level specification requires you to have a clear understanding about what you want to achieve. If it’s still unclear, now is the time to have a conversation with the client. After establishing a clear goal, we can use Cucumber to turn a plaintext story into executable code.

Our sample story will be from a news site. The feature is a JSON API endpoint for news articles.

In order to reference published articles in other applications
As an API client
I want to be able to request articles via a JSON API

This story can be copied directly into a Cucumber feature.

features/api/v1/articles.feature

Feature: Articles API 
  In order to reference published articles in other applications
  As an API client
  I want to be able to request articles via a JSON API 

  Scenario: Get articles
    Given some published articles
      And some unpublished articles
    When I ask for articles from the API 
    Then I should only receive published articles as JSON

Let’s run this feature to figure out what to do next.

$ cucumber features/api/v1/articles.feature
Using the default profile...
UUUU

1 scenario (1 undefined)
4 steps (4 undefined)
0m0.002s

You can implement step definitions for undefined steps with these
snippets:

Given /^some published articles$/ do
  pending # express the regexp above with the code you wish you had
end

Given /^some unpublished articles$/ do
  pending # express the regexp above with the code you wish you had
end

When /^I ask for articles from the API$/ do
  pending # express the regexp above with the code you wish you had
end

Then /^I should only receive published articles as JSON$/ do
  pending # express the regexp above with the code you wish you had
end

Fantasy Coding

Cucumber successfully parsed our feature but it needs definitions for all of our steps. Let’s implement these steps writing code that we wish already existed.

features/step_definitions/api/v1/articles_steps.rb

Given /^some published articles$/ do
  FactoryGirl.create_list :published_article, 3
end

Given /^some unpublished articles$/ do
  FactoryGirl.create_list :unpublished_article, 3
end

When /^I ask for articles from the API$/ do
  header 'Accept', 'application/json'
  get '/api/v1/articles'
end

Then /^I should only receive published articles as JSON$/ do
  articles_json = JSON last_response.body
  articles_json.should have(3).published_articles

  published_articles = Article.all.select {|article| article.published?}
  published_articles.should_not be_empty
  published_articles.each do |published_article|
    article_json = articles_json.detect do |article_json|
      article_json['title'] == published_article.title
    end
    article_json.should be
  end
end

In our two Given steps, we establish a context consisting of published and unpublished articles. These two factories don’t exist yet; we just wrote the code we wish we had. This is a major benefit of developing from the outside in. By writing code that doesn’t even exist, you’ll end up creating ideal objects and interfaces.

In our When step, we exercise our application by first setting a proper HTTP header and then making an HTTP GET request to a non-existent URL. Again, this URL doesn’t exist, it’s just where we would expect the articles to be.

Finally in our Then step, we verify the response. Here we begin to discover our domain model; imagining an Article class with a #published? instance method.

Let Cucumber Guide the Way

With our steps defined, a rerun of Cucumber fails in our Given step because our factories don’t exist yet.

$ cucumber features/api/v1/articles.feature
Using the default profile...
F---

(::) failed steps (::)

Factory not registered: published_article (ArgumentError)
./features/step_definitions/api/v1/articles_steps.rb:2:in `/^some
published articles$/'
features/api/v1/articles.feature:7:in `Given some published articles'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Let’s define these two factories.

spec/factories/articles.rb

FactoryGirl.define do
  factory :article do
    sequence(:title) {|n| "title-#{n}"}

    factory :published_article do
      published true
    end

    factory :unpublished_article do
      published false
    end
  end
end

Cucumber guides us toward our next step.

$ cucumber features/api/v1/articles.feature
Using the default profile...
F---

(::) failed steps (::)

uninitialized constant Article (NameError)
./features/step_definitions/api/v1/articles_steps.rb:2:in `/^some
published articles$/'
features/api/v1/articles.feature:7:in `Given some published articles'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Our factories are being automatically mapped to a non-existent Article class. We can use the Rails model generator to create this class. We’ll also specify the title and published attributes we referenced in our Then step.

$ rails g model article title published:boolean
    invoke  active_record
    create    db/migrate/20120213050147_create_articles.rb
    create    app/models/article.rb
    invoke    rspec
    create      spec/models/article_spec.rb
$ rake db:migrate db:test:prepare
==  CreateArticles: migrating
=================================================
-- create_table(:articles)
   -> 0.0497s
==  CreateArticles: migrated (0.0498s)
========================================

With our setup passing, Cucumber now fails at our API request.

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

No route matches [GET] "/api/v1/articles"
(ActionController::RoutingError)
./features/step_definitions/api/v1/articles_steps.rb:11:in `/^I ask for
articles from the API$/'
features/api/v1/articles.feature:9:in `When I ask for articles from the
API'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Drill Down to the Controller

We need to add a route for our API endpoint.

config/routes.rb

Sample::Application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :articles
    end
  end
end

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

uninitialized constant Api (ActionController::RoutingError)
./features/step_definitions/api/v1/articles_steps.rb:11:in `/^I ask for
articles from the API$/'
features/api/v1/articles.feature:9:in `When I ask for articles from the
API'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

With the routes in place, Cucumber tells us we’re missing a constant. This particular error message is from the Rails #namespace method we used in our routes file. Namespacing our controller will fix this issue. We can use the Rails controller generator to create a namespaced controller class.

$ rails g controller api::v1::articles
    create  app/controllers/api/v1/articles_controller.rb
    invoke  erb
    create    app/views/api/v1/articles
    invoke  rspec
    create    spec/controllers/api/v1/articles_controller_spec.rb
    invoke  helper
    create    app/helpers/api/v1/articles_helper.rb
    invoke    rspec
    create      spec/helpers/api/v1/articles_helper_spec.rb
    invoke  assets
    invoke    coffee
    create      app/assets/javascripts/api/v1/articles.js.coffee
    invoke    scss
    create      app/assets/stylesheets/api/v1/articles.css.scss

Cucumber fails again, this time looking for an #index action in our controller.

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

The action 'index' could not be found for Api::V1::ArticlesController
(AbstractController::ActionNotFound)
./features/step_definitions/api/v1/articles_steps.rb:11:in `/^I ask for
articles from the API$/'
features/api/v1/articles.feature:9:in `When I ask for articles from the
API'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

At this point, some outside-in practitioners will also drop down a level with respect to testing and use RSpec to spec out the controller. Since we’re new to outside-in development, I’m going to skip this step and go straight to the implementation. We’ll look at the value of controller specs and when it makes sense to write them later on.

app/controllers/api/v1/articles_controller.rb

class Api::V1::ArticlesController < ApplicationController
  def index
  end
end

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

Missing template api/v1/articles/index, application/index with
{:locale=>[:en], :formats=>[:json], :handlers=>[:erb, :builder,
:jbuilder, :coffee]}. Searched in:
  * "/Users/jared/Projects/sample/app/views"
 (ActionView::MissingTemplate)
/Users/jared/.rbenv/versions/1.9.2-p290/lib/ruby/1.9.1/benchmark.rb:310:in
`realtime'
./features/step_definitions/api/v1/articles_steps.rb:11:in `/^I ask for
articles from the API$/'
features/api/v1/articles.feature:9:in `When I ask for articles from the
API'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Now we fail because our #index action needs a template. Let’s create an empty template just so we can finally get a non-infrastructure related failure, i.e., a logic error, from Cucumber.

$ touch app/views/api/v1/articles/index.json.jbuilder
$ cucumber features/api/v1/articles.feature
Using the default profile...
...F

(::) failed steps (::)

expected 3 published_articles, got 0
(RSpec::Expectations::ExpectationNotMetError)
./features/step_definitions/api/v1/articles_steps.rb:16:in `/^I should
only receive published articles as JSON$/'
features/api/v1/articles.feature:10:in `Then I should only receive
published articles as JSON'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Drill Down to the View

With the routing and request handling boilerplate out of the way, we finally get a “legitimate” failure from Cucumber. At this point, some outside-in practitioners will drop down a level with respect to testing and use RSpec to spec out the view. Like controller specs, I’m going to skip this step for simplicity. We’ll discuss when a view spec makes sense later on. For now, let’s update our blank view to actually render some JSON (we’ll use the jbuilder Gem to construct the JSON).

app/views/api/v1/articles/index.json.jbuilder

json.array! @articles do |json, article|
  json.title article.title
end

Again, we write this view imagining an “articles” instance variable; ideally, a collection containing our articles. This helps us avoid setting up unnecessary state in our action.

Cucumber fails again, this time with a long stacktrace (abbreviated below) originating in jbuilder.

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

undefined method `empty?' for nil:NilClass (ActionView::Template::Error)

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

This failure is because the instance variable doesn’t exist yet. Let’s update our Api::V1::ArticlesController#index action to find all published articles.

app/controllers/api/v1/articles_controller.rb

class Api::V1::ArticlesController < ApplicationController
  def index
    @articles = Article.published
  end
end

We’ve kept our controller thin and decided to not directly test it. By keeping controller logic to a minimum, skipping controller tests isn’t a significant risk.

Cucumber now guides us to our domain model.

$ cucumber features/api/v1/articles.feature
Using the default profile...
..F-

(::) failed steps (::)

undefined method `published' for #<Class:0x007ff13c529498>
(NoMethodError)
./app/controllers/api/v1/articles_controller.rb:3:in `index'
./features/step_definitions/api/v1/articles_steps.rb:11:in `/^I ask for
articles from the API$/'
features/api/v1/articles.feature:9:in `When I ask for articles from the
API'

Failing Scenarios:
cucumber features/api/v1/articles.feature:6 # Scenario: Get articles

Drill Down to the Model

Despite skipping controller and view specs, I do feel it’s beneficial to drill down a layer in our tests and directly test the model. Model tests will shorten our testing feedback loop and allow us to specify at a level closer to the code. Skipping model tests and relying on Cucumber, keeps the feedback loop too large, slowing you down.

spec/models/article_spec.rb

require 'spec_helper'

describe Article do
  describe '.published' do
    before do
      FactoryGirl.create_list(:published_article, 2)
      FactoryGirl.create_list(:unpublished_article, 1)

      @published = Article.published
    end

    it 'only returns published articles' do
      @published.should_not be_empty
      @published.each do |article|
        article.should be_published
      end
    end
  end
end

RSpec will now be our guide.

$ rspec spec/models/article_spec.rb
F

Failures:

  1) Article.published only returns published articles
     Failure/Error: @published = Article.published
     NoMethodError:
       undefined method `published' for #<Class:0x007fee85f72440>
     # ./spec/models/article_spec.rb:9:in `block (3 levels) in <top
     # (required)>'

Finished in 0.03521 seconds
1 example, 1 failure

app/models/article.rb

class Article < ActiveRecord::Base
  def self.published
  end
end

$ rspec spec/models/article_spec.rb
F

Failures:

  1) Article.published only returns published articles
     Failure/Error: @published.should_not be_empty
     NoMethodError:
       undefined method `empty?' for nil:NilClass
     # ./spec/models/article_spec.rb:13:in `block (3 levels) in <top
     # (required)>'

Finished in 0.03338 seconds
1 example, 1 failure

app/models/article.rb

class Article < ActiveRecord::Base
  def self.published
    where :published => true
  end
end

$ rspec spec/models/article_spec.rb
.

Finished in 0.10455 seconds
1 example, 0 failures

With Article.published specified, we can return to Cucumber.

Jump Back Up to Cucumber

Cucumber is now passing and our story is complete.

$ cucumber features/api/v1/articles.feature
Using the default profile...
....

1 scenario (1 passed)
4 steps (4 passed)

The complete code for this example can be found on github.

Change Your Perspective

I use the above approach on every feature I write. At each layer, I find myself getting lazier and lazier, delaying the hard work until the very end. At that point, I’m in the domain model, the heart of the application, and where the majority of logic should be. By taking a client perspective at each layer, the resulting objects remain simple, have expressive interfaces, and logic naturally finds its home.

You can begin developing from the outside in at every one of your application’s interfaces. The example above demonstrated a JSON API. Traditional HTML interfaces can easily be tested using capybara. And if you’re developing a command line interface, perhaps for a Ruby gem, take a look at aruba.

Do I Need to Test at Every Layer?

The RSpec book suggests writing tests at each layer, i.e., view specs, controller specs, helper specs, and model specs. I’ve tried this approach several times but I usually feel all the lower level specs, except model specs, aren’t worth it. They do shorten the testing feedback loop, but their reliance on stubbing and mocking to achieve true isolation makes refactoring and maintenance difficult. I also keep the logic to such a minimum in these objects, e.g., controllers, that the additional fine-grained unit tests don’t provide that much benefit.

There is nothing wrong with not unit testing each part of your application. Don’t dogmatically insist that everything be unit tested. Oftentimes a higher-level integration test will sufficiently exercise (albeit indirectly) a particular piece of code. The tradeoff here is that your testing feedback loop will be large. You’ll need to execute a full-stack Cucumber test just to see if a change you made, perhaps in a controller or a view, passes your failing test. Occasionally, I’ll use a lower level view or controller test to handle an edge case but this is a pretty rare occurrence. This is just my personal style. I would recommend trying out testing at every level, especially view and controller tests, to see how it feels and if it’s beneficial for you and your team.

Give It A Try

Outside-in development often feels strange to newcomers. Most developers prefer to start with the “important” part of an application, i.e., the domain model, and work their way outwards. Thinking like a server and not a client can lead to overengineering by implementing more than you need. Your resulting objects and their interfaces will also be less than optimal, or at least take longer to get quite right.

Like most things in Rails, the tools for developing outside-in are easy to setup and configure. If Cucumber or RSpec aren’t your thing, adapt your favorite tool and give outside-in development a try.

Monkey-patching is extending or modifying the behavior of code at runtime without changing its original source code. You can monkey-patch any code, it doesn’t matter whether it’s your own code or not. This is distinctly different than traditional sub-classing because you are not creating a new class, instead, you are reopening an existing class and changing its behavior.

Monkey-patching is possible in Objective-C by using categories. In fact, the definition of a category practically matches that of monkey-patching:

"A category allows you to add methods to an existing class—even to one for which you do not have the source."

In this series of posts, we’ll use categories to add and change methods, to add new instance variables and properties, and introduce swizzling, a technique that allows us to extend and preserve existing functionality. TL;DR »

Category Basics

To modify an existing class specify the category in both its interface and implementation definitions:

Interface Definition

Implementation

Adding Simple Methods

The most basic usage of categories is to add a new method to an existing class.

Suppose in our application we want to output dates relative to the current time, e.g., “13 minutes ago”, “4 hours ago”, “just now”, etc. Traditional object-oriented solutions would have us introducing a new class that either extends NSDate (e.g., creating a RelativeDescriptionDate subclass with a timeAgoInWords instance method) or is a standalone helper/utility class (e.g., [NSDateHelper timeAgoInWordsFromDate:myDate]).

But with categories, we can reopen the NSDate class and simply add a new instance method:

NSDate+Formatting.h

NSDate+Formatting.m

Now every NSDate object will have the new method available to it. The following code:

Will print out the following on the console:

The Dangers of Simply Overriding Methods

We can take this a step further and instead of adding new behavior we’ll override existing behavior. Continuing with our example, what if we wanted the default description of a NSDate object to include the time ago in words? We could simply do the following:

However, this is strongly discouraged for two reasons.

1. Other frameworks may rely on the expected behavior of the original method. We now have to go through the trouble of re-implementing that behavior, in addition to the new functionality we wanted to introduce, or risk strange side effects and possibly even crashing out.
2. If multiple categories implement the same method, the last one loaded wins! The load order is consistent within an application, but it’s arbitrary, out of our hands, and fragile. For all we know, our implementation could itself be overwritten by an internal framework category!

Because of these reasons, this blunt approach to overriding methods should only be used for the simplest of cases. Later in this series, we’ll explore how swizzling allows us to override a method while preserving all implementations.

Including Your Monkey-Patches

Categories are not automatically “picked up” in a project. Any code that relies on the behavior will need to #import the necessary header files:

However, including the same set of headers over and over again is redundant. We should first create a single header file that imports all of our most frequently used categories:

We can then import this single header file into a prefix header that is added to all source files. XCode projects often have a .pch file in the Supporting Files group for this very purpose.

Next Up

While adding and overriding classes is straightforward, there is one very big caveat when using Categories; you cannot add new instance variables to a class. We’ll take a look at working around this limitation in the next post.

tl;dr

• Use Objective-C categories to add functionality to existing classes without subclassing.
• Avoid simple overrides with categories as it can cause problems with other frameworks.
• Use prefix headers to easily import your extensions.

I've been working on a post here for C5 and in order to make my points, I was referencing gists hosted by GitHub. When those gists were shown as embeds, the line numbers, and thus the clarity of my documentation, was lost. We use Markdown for the creation of the texts so I needed something I could write inside of a Markdown post that would be applied as CSS.

Thanks to these tips:

1. http://www.whyhat.com/2012/01/line-numbers-on-embedded-gists
2. http://stackoverflow.com/questions/524696/how-to-create-a-style-tag-with-javascript

I was able to come up with the following: