The Applications

• Snowballs

  Snowballs is a video game that was mostly designed by my 7 year old daughter, Ada. She started with a drawing that contained a maze filled with dots, a player and some monsters, and she explained how you throw snowballs at the monsters and build walls to block them. I convinced her we could get roughly the same effect by freezing the monsters instead of blocking them, and then I began developing. We started iterating, and she continued to contribute ideas which, somewhat surprisingly, always made the game more fun. The arrow keys move the player, and the spacebar launches a snowball. It’s implemented as a single Canvas tag using a JavaScript interval as a run loop. The maze, players, monsters, and snowballs are all drawn with JS functions using the Canvas drawing API. Since this application uses the Canvas tag, it won’t run in Internet Explorer or older versions of other browsers.

• Flashcards

  I wrote Flashcards one evening when Ada’s teacher suggested using flash cards to help her memorize the words she shouldn’t need to sound out. The idea is that the parent clicks the spacebar when the child reads the word and they work together to reduce the time needed to read all the words. The application doesn’t need any graphics (other than some external images at the end), so it doesn’t use any HTML 5 features (browser compatibility is unknown).

• Timetest

  Like Flashcards, I wrote Timetest to help Ada with her schoolwork. In this case, she was getting frustrated with a lesson on analog clocks, so I wrote this application to make it more of a game. The goal is to answer as many questions as possible in the given time. The test turned out to be more difficult than it really needed to be, so I created an easier version (accessed by adding #easy to the URL). Since this application uses the Canvas tag, it won’t run in Internet Explorer or older versions of other browsers.

• Arithmetic

  Arithmetic is another educational application designed to drill addition that uses carrying. It provides spaces at the top, which you can click to mark a carry from the previous column. It doesn’t have any fancy HTML 5 features, but it does have a lot of stats.

• Surround

  My wife and I had designed a fireplace surround and mantel for our living room, but when it came to actually buying the materials and building the thing, we realized we didn’t know exactly how to scale it. Since the design was entirely composed of rectangles, I realized it would be possible to build a simple one-off CAD program to help us agree on some dimensions. The application makes use of the Canvas tag and the new HTML 5 slider inputs (which aren’t currently supported in Firefox). It translates between pixels and feet/inches constrained to an 8th of an inch, in order to make the measurements easier to use in the shop.

The goal of these exercises was to produce something simple and quick, but not entirely without polish. All the applications except Snowballs took only an evening or two. Each application (also excluding Snowballs) ended up under 300 lines of HTML, CSS, and JS combined.

Developing without a JavaScript framework

Limiting the applications to a single page means no importing jQuery or Prototype. This might seem like a big constraint in an application written entirely in JavaScript. But these frameworks really only help out with DOM traversal/manipulation, event handling, animation, Ajax, form validation. All the applications make do with a small amount of HTML, so it’s easy enough to grab elements by ID, and a few visits to Quirksmode gave me some reasonably cross-browser event-handling code. Animation isn’t really that hard in JS, and I needed it to be more custom than frameworks allow anyway. The rest I didn’t need. The truth is, I never miss having a framework (though I’m not about to stop using jQuery when working on client’s sites).

Advantages and disadvantages

• They’re quick to start. Since it’s a single page, there’s no setup and no integration.
• They’re easy to deploy. It’s only one relatively small file, so you can e-mail it to friends, and you can host it anywhere. If you want to spend a little time making it touch-screen compatible, you can get it on all the smarter smart phones without bothering with app stores. On the other hand, there is no way prevent people from stealing the application or the code if you were developing it commercially, since the source is always just a right-click away.
• HTML+CSS is a powerful display framework. Although it lacks built-in support for some of the fancier UI widgets, there is no GUI framework that I’m aware of (and I’ve developed with quite a few) that provides the same level of design control with the same ease of development as these technologies. Of course, I’ve been swimming in HTML/CSS for years, so this opinion is a bit biased.
• Canvas has a powerful vector graphics API. I had done a fair amount of Cocoa programming prior to these projects, so this didn’t come as a surprise. The real power of Canvas lies in its transformation functions. I’d like to find an application for some more advanced spline generation. The downside is that Canvas and HTML don’t really mix, so you can have great text layout in HTML and sophisticated text animations in Canvas, but not both at the same time.
• JavaScript is a capable if not optimal language. No one is going to make the case that JavaScript is the greatest language ever designed, but what it lacks in performance and language features, it partially makes up in powerful fundamentals and simplicity. JavaScript is neither a great functional language nor a great object-oriented one, but it is sufficiently powerful to develop in either of these paradigms. Snowballs, for example, acts a lot like a simulation and benefited from stateful objects. The other applications required less state and I found several uses for higher-order functions, though I wouldn’t consider any of them properly functional.
• Single-page applications are fun. These exercises have reminded me that, once the responsibilities of software engineering are stripped away, there is a joy to be found in coding for coding’s sake.

All of these applications are available on GitHub, but it’s probably easier to right-click on the page and choose view source.

I just discovered a neat hack in Douglas Crockford‘s popular json2 parser/serializer which obviates the need for any server side support. So simple, yet so effective. Check out the first line of  http://www.json.org/json2.js:

  alert('IMPORTANT: Remove this line from json2.js before deployment.');

Neat, eh?

First, in order to do this, you need to embed your video using the swfobject javascript library. Next, you have to create a div that has an id (swfobject requires you to pass an id string for its initialization) – this div will be replaced by swfobject with a video object. The convention we’re using is to use an id of video-XXX, where XXX is the id of the video in vimeo‘s system. Finally, the div needs to be given a size (using CSS) so that the embedded video will end up being the correct size.

The code is structured as a jQuery plugin, so of course you will need jQuery. However, there is not a strong dependency on jQuery so with a little restructuring, I’m sure the jQuery dependency could be dropped.

Here it is:

I was telling Ada how video games are made one night, and she ask me if I could make a game. I said yes, we could make one together, and she bugged me all night to get started. I told her to start by designing a game on paper. She drew something that looks surprisingly like pacman (given that she’s never played the game), but she told me the dots were snowballs and that you could throw them at the monsters and use them to build walls. I started programming it as an SPA using canvas. She came up with all the rules, with some suggestions from me.

It may be that I’ve just been doing a lot of JS lately, but building a game like this in JavaScript felt really comfortable and extremely rapid. I had a basic version working with about 200 lines of code, but the details have tripled that. I went through a couple of major refactors, neither of which were troublesome in textmate.

The game is completely un-optimized, but it runs fast enough on my macbook. I know lots of ways to speed it up if I had to. It’s a little rough in a lot of areas, but it’s getting close enough to present.

Play Snowballs

Instructions

Load in Firefox or Safari. The arrow keys move your character, the spacebar launches snowballs (which you have to collect). Hit a monster 5 times to freeze it, then touch it to collect it.

For those of you who caught it last week at the SDForum, here are the links people requested:

• Maven plugin for Javascript Unit Testing with Rhino/ScrewUnit (from C5)
• The current code for the “wizardize” example we walked through.
• Blue Ridge (Rails integration tool)
• ScrewUnit
• JResig’s Presentation on JS Testing
• The slides we used

To sign up for next Wednesday, go to the EBig site.

The teaser for it… Recent evolutions in JavaScript testing frameworks now allow creating test suites, test-driving development, and running tests on a continuous integration server. This allows us to support more complex JavaScript, have confidence in the implementation, and push more of the logic from the server into the browser, reducing the load on the server…

Hope to see you there.

<plugin>
    <executions>
        <execution>
            <goals><goal>javascript-test</goal></goals>
        </execution>
    </executions>
    <groupId>com.carbonfive.javascript-test</groupId>
    <artifactId>javascript-test-maven-plugin</artifactId>
    <version>1.0-beta1</version>
    <configuration>
        <includes>
            <include>src/test/javascript/suite*.html</include>
        </includes>
    </configuration>
</plugin>

You will probably also need to add Carbon Five’s public repository so that maven will know where to grab the plugin:

<pluginRepositories>
    <pluginRepository>
        <id>c5-public-repository</id>
        <name>Carbon Five Public Repository</name>
        <url>http://mvn.carbonfive.com/public</url>
    </pluginRepository>
</pluginRepositories>

The <configuration> section contains standard maven <include> and <exclude> tags to allow you to specify any Screw.Unit test suite html files you would like to include in your build.

Now when maven executes its test phase, it will include your javascript tests as well. Any test that fails will halt the build. When the test phase is complete the target directory will contain a ‘screw-unit’ directory that contains the test reports. There will be two files for every file included in the test execution The first is an XML file named TEST-dir1.dir2.dir3.filename.html.xml that contains the test results for that file in a reasonable approximation of JUnit’s xml format. The other file will be named dir1.dir2.dir3.filename.html and will contain a sort of snapshot of the test suite’s html at the time the tests completed (the javascript will be removed and the css will be baked in).

Like Blue Ridge, the javascript-test-maven-plugin relies on the excellent env.js project and the less-excellent Rhino project to emulate a browser in Java. Unfortunately this combination creates the possibility of discrepancies between the browser and build results, and the probability of relatively slow test execution. To keep the simulation as realistic as possible, javascript-test-maven-plugin recreates the test environment for each Screw.Unit html file, so the more tests you can cram into a single file the faster your builds will run.

There are a few directions for future work. I’d like for the plugin to handle other browser-based javascript testing frameworks. Screw.Unit is popular, but seems suboptimal in many respects. The only limiting factor here is the plugin’s ability to interpret the results. If env.js could run in javascript interpreters other than Rhino, I’d like to give the the plugin the capability to fork out to spidermonkey for better compatibility and performance. Modifying the plugin would be relatively easy, but env.js appears to have some significant dependencies on Java.

Check it out if you have a need for this kind of thing and let us know if you have any problems or suggestions.

There are a couple of different options for JS testing available at this point but Blue Ridge’s plugin is the first I have seen which made writing test driven code as easy as I have come to expect while still providing all the functionality I need. In particular;

• Running my tests in a browser is fast. Refreshing fixture pages to rerun tests is dramatically more efficient than waiting for selenium tests to cycle.
• I can debug my tests as they run against their fixtures pages and inspect or manipulate the DOM at any point.
• I have mock and fake objects available to test behavior and stub out dependencies.
• My JS tests run in continuous integration, just like all the other tests.

By writing fixtures pages and tests first I am immediately using all of my code in two locations and running it against slightly different DOMs. That has pushed me to encapsulate most of my code as jQuery plugins and think carefully about how much I depend on the page’s structure. I end up with terse selectors instead of using whatever attributes are readily available and a clear configuration point for my page’s behavior as I chain together plugin calls in $(document).ready().

We’d like to see what other developers have done and share what we have learned so far so Carbon Five is hosting an open discussion of JavaScript testing in our office this week.

Topic: Javascript Testing
When: Tuesday Nov 17
6pm: arrive/network
6:30 – 8 presentation and discussion
Where: Carbon Five office: 171 2nd Street, 4th Floor

Please RSVP if you would like to attend.

http://ndpsoftware.com/agile_methods/agile_methods.html

Hint: Try dragging around the boxes to see how practices are related to each other.

Warning: If it doesn’t draw anything interesting for you, refresh your browser… there’s a large component of “randomness” to the algorithm and it can get stuck easily.

Warning II: Don’t leave it running in your browser, as it’s somewhat sluggish Javascript… this was a demo thrown together in a couple hours.

app/
  views/
    home/
      index.html.rb
      index.css
      index.js

The convention is clear: to add page-specific CSS code, just create a new file with the same name as the view, in the same folder. Easy to add, edit and remove. The alternative (using the public folder), usually leads to a parallel hierarchy and the inconvenience of that.

I also thought, that this being Rails and all, the files should be included automatically. It turned out to be pretty easy.

The Implementation

Serving the Assets

To serve this file, we need a route and a controller.

First the route:

map.connect '/asset/:path',
    :controller => 'asset', :action => 'serve_asset', :path => /.*.(js|css)/

We need to be careful here, since we’re going to be serving files directly out of our view hierarchy– make sure the route only picks up the javascript and CSS files.

The corresponding controller:

class AssetController < ApplicationController
  def serve_asset
    path = params[:path]
    format = path.sub(/.*.(w+$)/, '1')
    respond_to do |format|
      format.js { render :file=>"#{RAILS_ROOT}/app/views/#{path}"}
      format.css { render(:file=>"#{RAILS_ROOT}/app/views/#{path}")}
    end
  end

Now the assets mentioned above are served as /assets/index.css and /assets/index.js.

Including the Assets

With this convention, we added code to our layout that includes these files automatically, but only if they exist. First, the additional controller code:

class AssetController < ApplicationController
  ...
  def self.include_asset(rel_path)
    return '' unless AssetController.asset_exists?(rel_path)
    case rel_path
      when /.js$/
        "<script src="/asset/#{rel_path}" type="text/javascript"><!--mce:0--></script>"
      when /.css$/
        "
"
    end
  end
 
  def self.asset_exists?(rel_path)
    FileTest.exists?(RAILS_ROOT + "/app/views/#{rel_path}")
  end

And the code needed in the (Erector) layout:

head do
  c = self.class
  rawtext AssetController.include_asset("#{c.name.underscore}.js")
  rawtext AssetController.include_asset("#{c.name.underscore}.css")
end

Actually, since it’s Erector, the views are Ruby classes, so there is a hierarchy. These assets may be specific to any one of these:

c = self.class
while c != Object
  rawtext AssetController.include_asset("#{c.name.underscore}.js")
  rawtext AssetController.include_asset("#{c.name.underscore}.css")
  c = c.superclass
end

Discussion

Although some people will bristle at the proliferation of files, I have used this technique repeatedly over the last five years (in Java and PHP projects). I find it leads to sound, modular development. With Ruby, it’ll be pretty straightforward to concat the assets together later on, to reduce requests, or even embed the code directly in the served HTML files, if it’s small enough. It’s also convenient to add page caching in the controller, when the time comes. Adding

  caches_page(:serve_asset)

copies all these files into public/assets (as they are accessed), which conveniently takes your mongrel (or whatever) out of the picture.

You might imagine this keeps you from organizing and structuring your CSS and Javascript; it doesn’t do that. It lowers the barier to using a “local” scope for the CSS and Javascript. It allows you to write page-specific CSS and Javascript, which if you’re developing code quickly, is a lifesaver. We have repeatedly opened a view-specific Javascript file, seen that it no longer applies to the code, and removed it– safely. It’s easy to edit scripts when you know they only effect one page. Without this, I tend to lump things together that don’t really belong, and it becomes hard to tease them apart later.

Thoughts?

Download Here

It can be used in the standard jQuery way, like so:

$('some-selector').absolutize()

Here’s the code:

jQuery.fn.absolutize = function()
{
  return this.each(function()
  {
    var element = jQuery(this);
    if (element.css('position') == 'absolute')
    {
      return element;
    }
 
    var offsets = element.offset();
    var top = offsets.top;
    var left = offsets.left;
    var width = element[0].clientWidth;
    var height = element[0].clientHeight;
 
    element._originalLeft = left - parseFloat(element.css("left") || 0);
    element._originalTop = top - parseFloat(element.css("top") || 0);
    element._originalWidth = element.css("width");
    element._originalHeight = element.css("height");
 
    element.css("position", "absolute");
    element.css("top", top + 'px');
    element.css("left", left + 'px');
    element.css("width", width + 'px');
    element.css("height", height + 'px');
    return element;
 
  });
}

We chose to use the Dojo Toolkit (version 0.4.2) for both the AJAX (ie: remote calls to the server) and the Widegtry side of the Web 2.0 style. It’s been working fairly well. Dojo has a lot of functionality, but also has a few areas that still need some refinement. The most interesting / infuriating to me so far has to do with Dojo drag-and-drop functionality within IE.

Dojo’s facility for drag-and-drop is essentially composed of three components:

• Drag-and-Drop Manager
• Drag Sources
• Drop Targets

It intuitively makes a lot of sense. You create drag sources and drop targets and out of the box they actually work pretty well. Dojo uses a form of JavaScript inheritance to allow you to create drag copy sources or drag move sources, each of which have different behaviors. You can also reassign specific functions on your drag sources or drop targets in order to customize their behaviors.

I developed and debugged the app in Firefox and Firebug, as we all do. But when it came time to check that everything works in IE, I ran in to one bug in particular that stumped me for two entire days, and frustrated me to no end. At a certain point in using the app, my ability to drop objects on their drop targets was broken. It only happened in IE (I was using IE 6 for Windows), and the error I got was the always helpful “Unexpected error”.

What I found was that the following code, which creates a drop target, also registers the drop target with the Drag and Drop Manager.

var imageTarget = new dojo.dnd.HtmlDropTarget(imageDiv, ['galleryImages']);
imageDiv.imageTarget = imageTarget;

As a matter of fact, the Drag and Drop Manager, which is a global singleton, keeps a registry of all drag sources and drop targets created. Later on in the flow of my application, some of these drop targets need to be re-rendered, and to do so I actually delete the DOM node and re-create it, using the following code:

dojo.dom.destroyNode(pageContainerDiv);

The destroyNode() function is supposed to be memory-leak-friendly. But after I have done that, and created a new drop target where that one once was, when I try to drop another drag source on to it, I get the “Unexpected error” exception in JavaScript. And again, this only happens in IE. Firefox works fine. I finally realized that, even though the drop targets are automatically (and outside my knowledge for a long time) being registered with the Drag and Drop Manager, they must be explicitly unregistered before they are destroyed, otherwise this error occurs. I added the following code to do so.

dojo.dnd.dragManager.unregisterDropTarget(imageDiv.imageTarget);

And now everything works perfectly!