Roadcrew.js - Page switching like a Boss.

When I started with mobile development I had only limited time available. The app should run on Android and iOS phones at the same time and therefore I looked into Apache Cordova and jQuery mobile. While the first one is enabling you to do mobile development with JavaScript and HTML5 in general (including hardware access), jQuery mobile is more or less a Widget factory and a framework to build your Apps. While jQuery mobile looked pretty nice it had one major drawback: it was slow as hell and way to complex to develop (for what it does). I need to add that I have used the versions before 1.0 and everything might be better meanwhile. But back than, it was like that.

There were two things I loved on jQuery mobile. One was it’s look. And the other thing was the “single page” approach. It meant, you have all your App HTML basically in one file, showing only the parts which are necessary.

When replacing jQuery mobile I used Twitter Bootstrap. Today I would probably look into Ratchet.

For the page switching I didn’t find anything, so I decided to write some code myself. Because I listened to “We are the Roadcrew” from the great Rock’n’Roll band Motörhead and “Roadcrew” is a pretty great name for mobile things, I simply named it like that: Roadcrew.

You can find more information on the official Roadcrew-Website. Or you start with cloning Roadcrew from Github.

How does it work?

It is pretty simple: include the Roadcrew.js files and make up your HTML, like for example:

<div class="page start" id="login">
...
</div>
<div class="page" id="content">
...
</div>

Every div which is a page, gets the “page” class. A page is basically the div which is shown on your mobile. You could also say “view” to it. Every page gets an ID. This is used to navigate between your pages. For example, if you want to show the “content” page, you would make up an link like:

<a href="#content">Leads to content</a>

To make this basic navigation work, you only need to make an instance of Roadcrew:

$(document).ready( function() {
   var roadcrew = new Roadcrew();
}

This is jQuery code. And in fact Roadcrew.js uses jQuery. I will try to reduce the dependencies to a minimum in future and hopefully I can make it work with Zepto.js. But for now you have to live with jQuery, which is said to be slower on mobiles than Zepto. Patches welcome!

Intercepting - show a loading page

On thing which really didn’t work well with jQuery mobile was to show a loading page. This is dead simple usually, but was forced to waste a lot of time to deal with it. In Roadcrew it’s pretty simple. You simply need to create an interceptor - something which is done before the actual target page is called.

It could look like that:

roadcrew.intercept('#interceptingPage', function(dispatch) {
   roadcrew.flip('#loadingPage');
   $.post('ajax/test.html', function(data) {
      dispatch();
   });
});

While the “flip” method just “flips” pages around, bypassing every potential interceptor, the dispatch() function argument is what you can think of “showing the actual target page”. With the code above you would show the loading page which is then visible until $.post is ready and calls the dispatch() function.

Call to arms: Error Handling

If your interceptor causes an error, you might want to have an error handler waiting for you. You can pass it on when registering your interceptor.

roadcrew.intercept('#troublePage', function(dispatch) {
   throw new RoadcrewError("I made trouble");
}, function(error) {
   $('#errorPage').find('.error').html(error.message);
   roadcrew.flip('#errorPage');
});

As you can see, I throw an error in my dispatcher. The second function is my error handler which will work with the error handler.

There is also a chance to define a global error handler, which deals with every error.

Dart port available

I ported Roadcrew to Dart. Dart is a great new language for the web. It is still a pretty young language and not so widely spread yet. Consider this port an experiment. If you want to compare JavaScript to Dart Code you might find this interesting too.

I will create a blog post on Roadcrew.dart and my experiences on the port when I find some time.

Future

The current implementation is pretty small and it gives me everything I need. But I have already seen some things which might be useful for others. For example, there is no transition animation so far. It should be pretty easy to implement such a thing, I just didn’t do it. If you want to help me, send me a patch.

As already mentioned I would like to support Zepto.js.

There is now way to load new divs by AJAX. Currently I am unsure if this would just blow up the code or if it is really useful.

And finally I need to say that there is always room to improve the current code itself.

That all said, I hope that you’ll find it useful. If you have some feedback, let me know - either by mail or - if appropriate as feature wish or issue in the issue tracker.