Jackbone

Jackbone.js

Why use Jackbone?

Developing Backbone + JQuery Mobile javascript applications is possible, but it's a pain. Jackbone is here to make it as easy as it should.

Summary

Jackbone is a utility library that aims to structure the development of rich HTML5 applications using JQuery Mobile, by extending the Backbone framework. It heavily relies on Backbone, offering specialized classes for your views and router. Additionaly, it defines a controller interface, provide a view manager that handles life and death of the Views and Controllers of your application.

Licence

(c) 2013, Jean-Christophe Hoelt, Fovea.cc

Jackbone is available for use under the MIT software license.

Code for this library was initially extracted from a work for FlightWatching's Checklist application.

Documentation

Make sure you've read Backbone documentation first. This documentation will only cover the additions and differences between Jackbone and Backbone.

Jackbone.Listview

setLi will adjust the content of li DOM element according to the given JSON model.

newLi will create a new li element from given JSON model.

updateJSON Listview.updateJSON(ul, collectione updater, refresh)

Parameters:

ul: ul element

collection: JSON collection

updater: a ListviewUpdater (see above)

refresh: if true, calls jQM Listview's refresh method.

update Listview.update($ul, collection, updater)

Parameters:

$ul: a jQuery ul element

collection: Backbone collection

updater: a ListviewUpdater (see above)

Theming Options

Jackbone.DefaultHeader

Screens may include a default header, which will be instanciated using the Jackbone.DefaultHeader View (a class extending Jackbone.Header).

It can be disabled globally by setting this to null or per screen by passing the noHeader option to Router's openView() call.

Jackbone.DefaultFooter

Screens may include a default footer too, instanciated using the Jackbone.DefaultFooter View (a class extending Jackbone.Footer).

It can be disabled globally by setting this to null or per screen by passing the noFooter option to Router's openView() call.

Jackbone.Controller

For complex views that could be reused in different contexts it's better to create one (or many) controller. Views will only handle input/output, whereas controllers will handle logic and interactions with models.

Backbone doesn't provide a "Controller" interface, but Jackbone defines one. It's more than an interface, it's a also set of conventions that controllers have to follow.

Here is what Controllers do:

Load models and collections.

Create the view, send it the appropriate 'options'.

Provide "intelligence" to the view as a set of callbacks.

Interaction with the view

Controller should fill this.options in the initialize method.

In options, we add models and callbacks that the view will have to call. A very common callback is onRefresh(). onRefresh will be called by the view to refresh the models and collections, before it refreshes the interface.

Other things to know

A Controller will be kept in cache by the ViewManager, for a few minutes after its View was hidden.

Later on, controller's destroy() will be called by the garbage collector. This is where the Controller has to destroy structure it may have created.

A nice way for a controller to monitor his view is by providing callbacks in the options.

Interaction with the view manager

The View Manager will instanciate controllers.

Before rendering the View, it will call Controller's refresh() method, where he's supposed to load its Models and Collections. This method is meant to work asynchronously, with a callback to be called when refresh is done.

It will then look for this.view, an instanciated Jackbone.View

initialize object.initialize(options)

Initialize the controller. this.view has to be instanciated here.

destroy object.destroy()

Destroy the controller, its views and models.

Only useful when some heavy resource have to be freed.

bindEvents object.bindEvents()

Called whenever events binding is required.
Overload to bind your own callbacks to events.

unbindEvents object.unbindEvents()

Called whenever cleaning of events binding is required.
Overload to unbind your own callbacks to events.

Jackbone.Router

Jackbone Router provide a clean way to navigate through pages by disabling JQueryMobile's own navigation engine and relying only on JQueryMobile's lower-level changePage method.

Use goto method or set the route attribute to your HTML elements in order to navigate from view to view.

Override routes and call openView and openDialog in your own application's Router.

goto object.goto(page, args)

Navigate to a new page.

getPageName object.getPageName(page, args)

Name of the page as referenced by the page-name attribute in the DOM.

getPageHash object.getPageHash(page, args)

Name of the page as referenced on the hash tag.

openView object.openView(args, callback)

Create the view if not already cached, then open it.

args.name + args.options will identify the view in the cache, thus should be unique for each view.

args.extra are options, to heavy to be used as a key in the cache.

args.options and args.extra are options passed to the view.

args.Class has to be a Jackbone.View constructor.

callback(view) will be called when the view is ready.

Note: the openview event will be triggered on the Jackbone object, with the view as a parameter.

openDialog object.openDialog()

Same as openView, but open the view as a dialog.

openViewController object.openViewController(args, callback)

Create view with a controller if not already cached, then open it. Behaviour is identical to openView except that args.Class should be a Jackbone.Controller constructor.