HiddenTao » Mobile

How to write a custom widget for jQuery Mobile

ram — Mon, 07 Nov 2011 10:28:06 +0000

I needed to write a custom widget for the jQuery Mobile library but couldn’t find any step-by-step documentation on how to do it in the official docs. A search on Google didn’t result in any better luck. In the end it turned out to be quite easy to do – I was able to figure it out by looking at the source code of jQuery Mobile and that of the excellent DateBox plugin. In this post I outline the essentials to adding your own custom widget to jQuery Mobile.

Ideally place all your widget code into its own file. Here is the basic code structure:

(function($){
  $.widget("mobile.mywidget", $.mobile.widget, {
    /** Available options for the widget are specified here, along with default values. */
    options: {
      inline: false,
      mode: "default",
      height: 200
    },
    /** Mandatory method - automatically called by jQuery Mobile to initialise the widget. */
    _create: function() {
      var inputElement = this.element;
      var opts = $.extend(this.options, inputElement.data("options"));
      $(document).trigger("mywidgetcreate");
      ...
      inputElement.after("");
      ...
    },
    /** Custom method to handle updates. */
    _update: function() {
      var inputElement = this.element;
      var opts = $.extend(this.options, inputElement.data("options"));
      $(document).trigger("mywidgetupdate");
      ...
      inputElement.siblings("button").text(inputElement.val());
      ...
    },
    /* Externally callable method to force a refresh of the widget. */
    refresh: function() {
      return this._update();
    }
  });
  /* Handler which initialises all widget instances during page creation. */
  $(document).bind("pagecreate", function(e) {
    $(document).trigger("mywidgetbeforecreate");
    return $(":jqmData(role='mywidget')", e.target).mywidget();
  });
})(jQuery);

In the HTML we can trigger use of the widget as follows:

In the example above our widget is known as a mywidget. We first define the widget and then follow it with a handler for the pagecreate event. This handler ensures that all HTML elements with the attribute data-role=”mywidget” are processed. Note that you should use the jqmData filter in case you’re not using the standard data- prefix for widget attributes.

Any number of options can be provided to your widget with no restrictions on option type. Per-widget-instance options can be specified as HTML attributes or as dictionary keys if initializing a widget directly in Javascript. Default values for options are provided within the widget itself (as you can see above).

The _create() method gets automatically called by jQuery Mobile when we call mywidget() from the pagecreate handler. This method is responsible for setting up the initial widget display. In the example above we simply add a button after the input element with its label set to the value within the text field.

There is also a refresh() method available for the widget which can be invoked through Javascript as follows:

$(":jqmData(role='mywidget')").mywidget("refresh");

This in turn calls the _update() method which in turn refreshes the button label with the current value of the text input field. You can add as many such methods as you like to the widget. For example, most of the standard jQuery Mobile widgets also come with enable() and disable() methods.

You’ll also notice that we trigger widget-specific events within the functions, e.g. mywidgetcreate. These aren’t strictly necessary but are useful to include, especially if you want the rest of your application to know when these events take place within the widget.

wuPlay – real-time multiplayer web gaming on your mobile

ram — Fri, 15 Jul 2011 16:14:56 +0000

Introducing wuPlay.com, an experiment in real-time multiplayer gaming on a mobile-friendly website. wuPlay is a web-based multiplayer implementation of the excellent Connect6 game that works well on desktops, tablets as well as on most good mobile devices (so far I’ve tested on Android 2.3 and iOS 4.2 devices).

I started working on wuPlay mainly as a way of learning Tornado. Tornado was still quite new then and I was very interested in the idea of a non-blocking event-driven server and what it could do. I was also learning about Websockets and AJAX long-polling and other techniques of simulating a “push” from server to client. At the same time I was also wanting to make a multiplayer game from my droid device and figured that it would be better to build it as a web app so that it straight away ran on all devices. Finally, I wanted to improve my Javascript skills so all the client-side code is written in an object-oriented fashion.

For the rest of this post I’m going to talk about the implementation behind wuPlay and some of the design decisions I took.

Overall architecture

wuPlay is served via a single Tornado instance sat behind nginx. I put nginx in front so that I could load balance in future if necessary. One of my main aims was to make wuPlay load very quickly and minimize both the size and number of assets which need to be downloaded for it. So all the Javascript and CSS assets are minified using Juicer and compressed at build time, and then served using the HttpGzipStaticModule module. So Tornado only serves the HTML.

I wanted it to be as fast as possible on mobile devices, even ones with a 2G connection. Browsing a site normally on a mobile is slow so I opted for a completely Javascript-driven client-side UI. The jQuery Mobile project was in development at the time but I found it to be too slow and heavyweight so I rolled my own Javascript UI kit (more on that below).

Websockets wasn’t fully supported in browsers when I started building this so I opted for AJAX long-polling. This restricted the kind of games I could build but my initial goal was simply Connect6, for which it was more than adequate. There’s no need to sign up for the site – you just enter a nickname and immediately join the game lobby where you can both send and receive “challenges” to and from other players in the lobby.

The app is resilient to sudden losses in your internet connection as well as temporary increases in latency. On desktops and on Wifi none of this is an issue but on 2.5/3G on a mobile device these sorts of things happen regularly. In order to be resilient the back-end has to be very quick and responsive. I opted for MongoDB as my datastore (for session data too) since most of the database activity involves high-speed writes.

Back-end database

In wuPlay the majority of the data consists of event notifications such as when a user leaves the lobby, enters the lobby, makes a move in the game, etc. They are stored in the db as a way of allowing other users to be notified of said events. In short wuPlay is based on a publish-subscribe model.

I needed a high speed database and it didn’t need to be relational since the data model is so simple. And I didn’t mind if data occasionally got lost. So I opted for MongoDB. This also gave me an opportunity to learn what it was about and how to use it. I’d only ever used relation data models before so this was certainly a new way of looking at things. Still, as I built the app I ended up writing a database abstraction layer which mimicked Mongo’s API but left it open for me to swap out the actual back-end from MongoDB to something else in future if and when such a time arises.

How clients receive updates from the server

MongoDB automatically creates unique ids for every row it inserts. These IDs are essentially based on a timestamp and I use these to keep track of which events a client hasn’t yet been notified of. Thus, when a client first enters a lobby this is what it (i.e. the Javascript code running in the browser) do:

It asks the server for the full state of the lobby (i.e. the full list of users along with their stats) as well as the timestamp of the last lobby event – it stores this as last_timestamp.
It then opens a persistent connection to the server and asks for events newer than last_timestamp. AJAX long-polling is used to query the server, thus ensuring that it only need to do something if the server returns with new data.
When new events are found it processes these (by updating the lobby display according to what happened) and sets last_timestamp to equal the timestamp of the newest event.
It then repeats from step 2 onwards.

If the internet connection drops then the client will go back to step 1 and start from there.

The event notification process described above is also used for when a client is in a game. In fact, it’s architected in such a way as to make it re-usable for any type of event we may want to do in future, e.g. instant messaging.

As outlined above, every client maintains a long-polling connection to the server in order to receive event updates. Thankfully, browsers allow for upto 2 simultaneous connections to a given domain name so the client can still send messages to the server.

Javascript-driven UI

The client UI is completely Javascript-driven. All the popup dialogs and message boxes are also re-usable Javascript “classes” which get used throughout. Once you load the initial wuPlay.com site from there on in all subsequent page changes are driven through Javascript. You’ll notice this by virtue of the loading graphic which shows for a moment or two whenever you click on a link. If something takes longer than a second or so to load you’ll see a “Waiting for server” message in the top right part of the page. All these notifications are coded in a re-usable fashion such that every AJAX request can be made with such progress notification if necessary.

There is a page loader which is responsible for loading a given page from the server. It passes the name of a page to the server and is given back a JSON object similar to the following representing meta data about the page:

{"html" : ..., "js" : ...., "css" : ...}

The html entry is the HTML to show for the page. The js entry is a list of scripts to load using the