Navigation Refactor - First Pass

[johnbender]

Goals

Ordered by priority.

Abstract pushstate/hashchange handling

I'd like to unify these two events into one internally ("navigate"). Additionally I was considering providing namespaced events "forward.navigate", and "back.navigate" where appropriate but that will require review since it's tightly coupled to our hashchange handling. Again, these events will initially be internal until we decide that the module is ready for general consumption.

This likely includes the following deliverables:

1. "navigate" triggered on window
2. HistoryManager
3. HistoryEntry
4. "back.navigate", "forward.navigate" triggered on window
5. Dependency only on jQuery

Container

I'd like to provide a container widget that manages its history and content transitions. The idea is to have this respond to navigation events and possibly delegate to changePage. This is important as we make a run at multiple container documents.

This likely includes the following deliverables:

1. ContentContainer
2. changePage alterations to account for a container
3. Dependency on jQuery and some change content function (eg, changePage )

[frequent]

@Wilto: if you want, I can share some stuff on what I did in multiview. The current version is tapping into JQM history (no container history mgt). In the previous version every container had it's own history. I eventually got both to work, although I'm finding container history inside JQM easier to manage. Let me know if you want some code samples with comments.

[johnbender]

@frequent

I'll definitely ping you for review, after I get the basic navigation event structure in place. I'm really looking forward to getting this cleaned up and I your help could be invaluable.

[frequent]

@johnbender:
I could do a quick write-up of the current navigation model I'm using (storing container transitions in JQM history). Although I'm still not happy with and it has it's bugs (spell multipe pages in the DOM each with containers), the logic is pretty simple, which... I like.

[johnbender]

@frequent

Let me sort out the navigate event first and think about page containers a bit, and then we'll talk. Fresh eyes :)

[frequent]

@johnbender - you have a point :-)

[toddparker]

This will be really great, especially the ability to surface a consistent way to track an action in the history stack because we already have dialogs and popups that need this and I can see the list of potential widgets that may need history support - hide/show panels, menus, etc.

[frequent]

aka "The history-dump"

[gabrielschulhof]

Make sure you take into account what happens should the user refresh the page at any point in history. Currently, we get all kinds of funky effects when the user refreshes mid-history. See #5122 for example. Also, it seems a refresh on a given location is not the same as starting with a deep link, because, if you refresh and then hit "Back", jqm is not reloaded, but the same pagestate is kept alive.

What I mean is this:

1. Open a URL containing jQM
2. Navigate using AJAX to another page
3. Refresh. At this point, jQM is re-instantiated with the second page as the starting URL.
4. Click "Back". At this point, the second instance of jQM becomes associated with the first URL.

[frequent]

@gabrielschulhof - do you know if double entries are allowed/possible/wanted in the URL history? After a transition, I'm running a cleanser, that clears out double entries in the URL history when they are last in stack, so:

page 1
page 2
page 3
page 3 refresh

would clear out the last page 3 entry, which "maintains" the user on the current page and entry.

[gabrielschulhof]

O_o ... how do you reach such a state? I'm talking about browser history, not $.mobile.urlHistory.

[frequent]

@gabrielschulhof: Can't do browser history, only $.mobile.urlHistory as well....

Hhaven't looked at this in a while...

var activePagefromUrl = $.mobile.urlHistory.stack[$.mobile.urlHistory.activeIndex].pageUrl;

for (var i = 0; i < $.mobile.urlHistory.stack.length; i++) {                        

    // last backwards transition on a panel (always overwritedata-url with full-url, no #page-thingies)
    if ( o._backFix == true ){
        if ( $.mobile.urlHistory.stack[i].url == data.toPage.attr('data-url') ) {
            $.mobile.urlHistory.stack.splice(i,1);
            $.mobile.urlHistory.activeIndex = $.mobile.urlHistory.activeIndex-1;

            // clear fwd
            $.mobile.urlHistory.clearForward();
            }
    // regular panel transitions
    } else if ( todo == "blockdoubles" ){                               

        // check if the current page is already in the history
        if ( i != 0 && i < $.mobile.urlHistory.stack.length-1 && $.mobile.urlHistory.stack[i].url == activePagefromUrl ) {
            $.mobile.urlHistory.stack.splice(i,1);
            $.mobile.urlHistory.activeIndex = $.mobile.urlHistory.activeIndex -1;

            // clear fwd
            $.mobile.urlHistory.clearForward();
            }
    }                       
} // end for -loop

[frequent]

@johnbender:
have a look here. Don't click documentation, the rest should stay in the containers/page boundaries. I could only test on iPad and PC but this sure is in sync with browser history.

In the source, the js file includes jquery, jqm and url.js (almost at the bottom - search for url.js v1.0.0 ). I haven't really looked into the code, but it performs nicely (probably a little to customized on the specific page content, but I guess this can be generalized). I can hook you up with the author if you like - sitting in the same room this week.

@johnbender:
repo can be found here

[johnbender]

Update:

Here's what I have so far, all event/method names are up for discussion.

First, I've wrapped both hashchange and popstate and created a new event navigate:

https://github.com/jquery/jquery-mobile/blob/simple-nav/js/navigation/events/navigate.js

This by itself isn't super exciting though it does normalize the "shape" of the data and API so that folks who want to build on it down the stack have a reduced set of concerns. Importantly, this by itself doesn't allow us to track history. The key to tracking history within jQuery Mobile is that new history states are created and controlled by the library.

Second, I've created the $.navigate method, which sets the hash, does the replaceState with the hash (necessary for ios 4 support), and tracks history.

https://github.com/jquery/jquery-mobile/blob/simple-nav/js/navigation/navigate.js

Along side the navigate method are two event bindings (hashchange and popstate) that live "before" the event bindings in the normalized navigate event. When those events are triggered from something other than a call to $.navigate they do our basic history calculation to attached the history entry to the event and attach directional information to the event.

All of this taken together means that if users are willing to use $.navigate along with the navigate event they can manage page state with either hashchange or popstate without having to care which one is being used.

Let's look at an example similar to something that jQuery Mobile does though we'll assume that the content associated with each page state can be loaded directly without concern for scripts, etc:

$( "a" ).click(function( event ){
  event.preventDefault();

  // Here we set the hash, call replaceState where supported
  // and also track a new history entry with our extra data from the 
  // anchor "data-foo"
  $.navigate( this.attr( "href" ), { foo: this.attr("data-foo") });

  // ostensibly this method call takes the href and loads the content from the server
  // altering the document to reflect the proper page state
  MyApp.loadContent( this.attr("href") );
});

Here we've done a link hijack that participates in our history tracking by using the $.navigate method to track state and do the url alteration in the application. Let's look at series of events and the result of something like this:

First some markup:

<a href="/dogs" data-foo="bar">Dogs</a>
<a href="/cats" data-foo="baz">Cats</a>

When the first link is clicked, navigate is called and the url is updated:

hashchange support:  / => /#/dogs
popstate support:    / => /#/dogs => /dogs

Assuming those links are still available and the second link is then clicked:

hashchange support:  /#/dogs => /#/cats
popstate support:    /dogs => /dogs#/cats => /cats

Now assuming an event binding like:

$( window ).on( "navigate", function( event, data ){

  // NOTE I need to address namespacing in the data so that it doesn't collide with the
  //      attached history information
  console.log( data.foo );
  console.log( data.url );
  console.log( data.direction );

  MyApp.loadContent( data.url );
});

Hitting the back button, or calling window.history.back() will result in the following output:

bar
/dogs
back

And with the call to loadContent provided the url the visual state of the application should change as well. Note the directional information which is useful for things like transitions.

If the user were to then hit the forward button the output would then be:

baz
/cats
forward

And the call to `loadContent with the url could handle the visual state of the application.

Hopefully this illustrates what I've come up with so far. There are a lot of details to sort, but I wanted to get some feedback before I proceed to rework the navigation internals based on this model. I think this will remove alot of the complexity from the core navigation code.