Continuing with Part 4 of building WinRT applications with HTML and JavaScript.  You can find earlier installments at their respective links: Part 1 – Part 2 -  Part 3If you are interested in the source code for the TweetScan application, you can get it off of GitHub.

Watch the Part 4 video

Let’s switch back to a WinJS application and take a look at what happens when a page is loaded.  Open package.appxmanifest and switch the Start Page back to default.html.

If you remember from Part 1, we created this application as a single-page style application.  This means that default.html gets loaded once, and different pieces of HTML content are then loaded “into” default.html for rendering and execution.  If we look at default.html, we see two important things.

First, we see that default.html loads the core script files for the WinJS framework and then the default.js script file (where we put our code), and also navigator.js, which helps navigate from page to page (with page really being HTML content being loaded into default.html).  The second thing to notice is that default.html contains a single div that is marked as a PageControlNavigator control.  It is this div that serves as the content host for the rest of the content.

Take a look at default.js.  It is comprised of a self-calling function that sets up the WinJS infrastructure.  The first three lines are the heart of getting the WinJS Application up and running.

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;
    var nav = WinJS.Navigation;

First, a WinJS Application namespace is acquired. This Application namespace provides application-level functionality. For right now, we are most interested in the various application-level events that are fired as the application runs.  We will explore Activation and Navigation as we get deeper into the application.

Events

Understanding the order of events in a WinJS application is important.  Knowing when events fire and in what order is critical to determining the best place to put your application  code.  In a single-page application, you have three categories of events available to you: traditional browser events, WinJS application events, and page events.

Browser Events

Traditional browser events are exactly what they sound like.  Since HTML/JS apps in WinRT are actually leveraging the IE10 rendering a JavaScript engines, it makes sense that these events are available.  This means that you can detect and handle events like the Window object’s onload event and the Document object’s DOMContentLoaded event.  This is especially useful when moving an existing, browser-based application to Windows 8.  You would wire these events up inside default.js. 

Application Events

The new events that are part of the WinJS environment are those provided by the Application and by Pages being loaded for display.  There are three main Application events.  The most common is the activated event, and this is the event that is wired automatically for you in default.js.  In the event handler you will find boilerplate startup code for determining how your application was started (tap on the Start tile = launch, targeted for a Search from the Search Charm = search, etc.), the previous execution state of the application (terminated by the user, suspended by the OS), and a call to WinJS.UI.processAll().  The processAll() call walks the DOM and finds all of the HTML elements that have been marked as WinJS UI controls, like the div marked as a PageControlNavigator we looked at earlier.  Prior to the activated event, the loaded event is fired.  Once the application has been activated, and all other Page events (to be discussed shortly) fire, the Application fires the ready event.

Page Events

When working with a single-page navigation model, each new piece of content or view is constructed as its own Html page (typically).  As these pages are loaded and rendered in the default.html’s PageControlNavigator, the new html page can load additional JavaScript files.  If you look at home.js, you will see the usual implementation for single-page applications.  Home.js makes a call to WinJS.UI.Pages.define(). This function defines the page that is being loaded, and as a result, exposes a series of events that you can hook into.  The default implantation shows only the ready event:

    WinJS.UI.Pages.define("/pages/home/home.html", {
        ready: function (element, options) {
            // TODO: Initialize the page here.
        }
    });

There are two other events you can define in the same way ready is defined: init and processed.  Both of these events occur prior to the ready event.  Init fires before any of the content of the new page has been set.  Processed will fire once the content has been set, but before any remaining processing has been completed.

Event Order

The complete order of all of these events is shown below

• Default.js self-calling function
• Application Loaded event
• Document DOMContentLoaded
• Application activated event
• Window loaded event
• Home.js self-calling function
• Page init event
• Page processed event
• Page ready event
• Application ready event

The documentation says that Application loaded follows DOMContentLoaded. However, in all of my testing so far, I have always seen DOMContentLoaded follow Application loaded.  I am not sure if the documentation is wrong, or if it is some strange artifact in the debug environment.  As some point, I will get around to logging the events so I can read them without having to be in debug mode.   Just something to keep in the back of your head.

Until next time…