Refactor: Navigation Plan

Overview

Over the last few alphas, we've gotten feedback from the community regarding jQuery Mobile's current navigation implementation. Most of the feedback centers around a few key things:

• Allow for loading page content transmitted in a format other than HTML. (JSON, XML, etc)
• Allow developers to encode/decode what is stored in the hash.
• Allow developers to turn off hash management entirely so it can be managed manually by developer code.

For jQuery Mobile Beta 1, we are going to take steps towards addressing some of these issues by refactoring the page loading and navigation code so that it can be extended or overridden. Below, we discuss some of the planned changes in detail. Not all of them are going to make it into the Beta 1 release, but we are interested in hearing any ideas or concerns you have around some of these plans.

Refactor Navigation Code

We need to refactor the navigation code to allow for extensibility and hooks. As of version 1.0a4.1, the navigation code was largely implemented as a set of nested functions with the $.mobile.changePage() function in jquery.mobile.navigation.js. The problem with this current implementation is that these nested functions use and manipulate variables from their outer scope. This makes the code very hard to follow.

We need to refactor this code into the 3 operations that are being performed:

• loadPage()
  • Responsible for loading a page into the DOM of a specific page container and enhancing it.
• changePage()
  • Responsible for updating the internal bookkeeping for tracking what is the current page. This includes:
    • Managing the URL stack.
    • Managing the location hash.
    • Kicking off a transition.
• transitionPages()
  • Responsible for managing the transition between the current active page and the new page to be shown.

Partitioning the code in this way will make it easier for us to identify key points for adding extensibility hooks. It will also make the code easier to follow.

Status

DONE (Beta 1)

Fix Path Management

Add Hooks for Page Loading

Overriding loadPage()

Delegate Model

Content Type Model

Make Hash Management Optional

Decouple Hash Management

If hash management is optional, changePage() needs to be modified so that it can fire off the necessary notifications whenever the current page changes. The hash management code, when turned on, should listen for these notifications and update the hash accordingly.

Note that this same mechanism can be used to allow 3rd party developers to hook in and manage the URLs manually.

Potential Issues

Status

Not started yet.