Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A content directed dispatcher for ajax page loading.
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Version 0.1

A content-directed dispatch library for ajax content loading.

This libraries goal is to simplify a messy problem I frequently encounter while building websites (not web apps): Handling ajax page loading with history support while not breaking static pages and clients without javascript enabled.

Content-directed means that the content of a request is used to determine what code to execute, not the URL or some other side channel information. URLs are opaque; the server implements the details and provides links to the client. This allows the server to change its url structure without requiring the client code change. As long as the client receives content it understands it will process it accordingly. The downside of this is that the library cannot make any decisions prior to receiving the response from the server; prefetch logic is unfortunately generic as a result. This may change as the History API gains better support.

Pitchfork tries to stay out of policy decisions. Where reasonable, it's internal operations are polymorphic and can easily be overridden.. This does mean that handling animation and transition is entirely out of its control.

Handling responses is achieved via simple, composable rules. These rules are simply functions that conform to a particular interface. The library provides a set of standard combinators and decorators to simplify the definition of a ruleset. This interface is heavily inspired by the Ring HTTP library for Clojure.


  • jQuery: Pitchfork has only been tested with 1.8+ though older versions may work. Actual jQuery usage is quite light, and this dependancy may disappear in future.
  • rsvp.js: This is a small, lightweight Promise/A implementation.
  • Moderinzr with history support: This includes useful shims for dealing with older IE, and checking for the existance of history api support.


The API is found in the namespace net.brehaut.pitchfork and its children. I prefer to alias it to PF with var PF = net.brehaut.pitchfork. Basic usage requires creating and registering a net.brehaut.pitchfork.Pitchfork instance populated with rules from the net.brehaut.pitchfork.rules namespace. For instance:

$(function () {
    var PF = net.brehaut.pitchfork;

    var pitchfork = new PF.Pitchfork({}, [
            function (data, signals) {
                var els = data.elements.clone().appendTo("body");

Pitchfork takes two arguments, the first is the options map, the second is the rules to run. You can either provide the rules as an array (as int the example), which will implicitly be wrapped in a net.brehaut.pitchfork.rules.ordered rule, or you can provide any rule function (more on this later).

Each rule in an ordered is tried in order. The particular rule used here hasElements expects HTML to have been generated by the fetcher (see below). hasElements looks for the provided css selector in the content, and if it exists the rule function provided is called. In this particular case, has_elements adds an elements member to the data object, that contains the elements matched by the selector. This rule simply appends the blog post to end of the page. Finally, signals.succeeded tells the rules engine that processing is complete.


Rules form the core of pitchfork. A rule is a function that takes some data, and a signals object. That's all. The rules namespace provides functions for creating and decorating rule functions, but these are not special.

Something went wrong with that request. Please try again.