GIANT ROBOTS SMASHING INTO OTHER GIANT ROBOTS

Written by thoughtbot

WIP it ♪♪♫♪ WIP it good

Our development process calls for a design component up front. Design is typically one or two weeks ahead of development so that by the time a developer is ready to implement the feature, there’s a pretty good idea of how the interactions will work, and even better, part or all of the markup has already been written. This introduces a problem where at any point in time there will be Work In Progress functionality that hasn’t been wired to the backend. This creates frustration and confusion for the product owner, who gets oh so excited to see a feature corresponding to the story they have just recently created, only to find out that it’s only a placeholder.

Displaying work in progress UI elements is also sometimes not an option, especially on an iterative development process where each week the app is shown to real users to gather feedback. Hiding .wip elements using CSS, commiting and redeploying to prime the app for user testing, followed by reverting the CSS commit in order to continue with development soon became old and cumbersome. There’s a better way to support the process.

You should go here on a new tab and click play. Also, here’s a picture of Devo. I’ve included a unicorn with a shining star to keep them company. Don’t worry, it’s Work In Progress.

WIP it
good

What I present here is not ground breaking, but it is a well tested piece of code that you can drop into your app and will give your product owners the ability to view how the interface is shaping up. It still gives developers and designers the opportunity to continue implementing Work In Progress features on a live app without having to deal with too many feature branches, where keeping the markup and styles up to date with master at an early stage is an expensive moving target.

The idea is to have the ability to toggle visibility of Work In Progress elements of the app. For a developer or designer, it’s as simple as setting a CSS class of wip on any DOM element. For a user, pressing Ctrl-W reveals the WIP elements.

Let’s do this!

We practice Outside-In development, so let’s use Cucumber to specify this behavior:

Feature:
  As a product owner
  So that I can view what's work in progress
  I can press Control W

  @javascript
  Scenario:
    Given I visit the home page and the body is marked as wip
    When I press Control "w"
    Then the wip tags are visible
    When I press Control "a"
    Then the wip tags are visible
    When I press Control "w"
    Then the wip tags are not visible
    When I press Control "a"
    Then the wip tags are not visible

First, we use jQuery to set the wip class on the document’s body from within the step definition. Here’s the implementation:

Given /^I visit "([^"]*)" and the body is marked as wip$/ do |page_name|
  visit(path_to(page_name))
  page.execute_script("$('body').addClass('wip');")
  page.should have_css('body.wip')
end

Pressing Control W also evaluates javascript to trigger the event:

When /^I press Control "(\w)"/ do |character|
  code = case character
         when 'w'
           23
         when 'a'
           65
         end
  page.execute_script(<<-JS)
    var e = $.Event('keypress', { which: #{code}, ctrlKey: true });
    $('body').trigger(e)
  JS
end

Finally, checking whether the WIP elements are visible is a matter of checking the CSS classes:

Then /^the wip tags are visible/ do
  page.should have_css('.wip.visible')
end

Then /^the wip tags are not visible/ do
  page.should have_css('.wip')
  page.should have_no_css('.wip.visible')
end

I placed all of these steps definitions in features/step_definitions/wip_steps.rb

To make this pass, the jQuery implementation is simple:

$(document).ready(function() {
  $('html').keypress(function(e) {
    var codeForW = 23;
    if (e.ctrlKey && e.which === codeForW) {
      $('.wip').toggleClass('visible');
    }
  });
});

Here are some styles that handle WIP element visibility and give them a yellow outline:

.wip {
  outline: 1px solid #ff0 !important;
  visibility: hidden;
}

.wip.visible {
  visibility: visible;
}

When dropping this into your app, just remember that when a problem comes along, you must WIP it. Before the cream sets out too long, you must WIP it. When something’s goin' wrong, you must WIP it. To WIP it, well, WIP it good.