This JavaScript loads a document called index.html, and will not work without it. Before you proceed, copy the HTML file from Example 2.1, “The HTML document we’ll be styling.” into the same directory as android.html, and be sure to name it index.html. However, none of the links in it will work unless the targets of the links actually exist. You can create these files yourself or download the example code from the book's web site (see the section called “How to Contact Us”).

To give you a couple functioning links to play with, you can create about.html, blog.html, and consulting-clinic.html. To do so, just duplicate index.html a few times and change the filename of each copy to match the related link. For added effect, you can change the content of the <h2> tag in each file to match the filename. For example, the h2 in blog.html would be <h2>Blog</h2>.

At this point, you should have the following files in your working directory:

The JavaScript in android.js is where all the magic happens in this example. Create this file in the same directory as your android.html file. Please refer to Example 3.3, “This bit of JavaScript in android.js converts the links on the page to Ajax requests.” as I go through it line by line.

$(document).ready(function(){ 
    loadPage();
});
function loadPage(url) {
   if (url == undefined) {
      $('#container').load('index.html #header ul', hijackLinks);
   } else {
      $('#container').load(url + ' #content', hijackLinks);
   }
}
function hijackLinks() {
    $('#container a').click(function(e){
        e.preventDefault();
        loadPage(e.target.href);
    });
}
            

Click handlers do not run when the page first loads; they run when the user actually clicks a link. Assigning click handlers is like setting booby traps; you do some initial setup work for something that may or may not be triggered later.

Since we are not allowing the browser to navigate from page to page, the user will not see any indication of progress while data is loading. We need to provide some feedback to the user to let them know that something is, in fact, happening. Without this feedback, the user will wonder if they actually clicked the link or missed it, and will often start clicking all over the place in frustration. This can lead to increased server load and application instability (i.e. crashing).

sudo ipfw pipe 1 config bw 4KByte/s
sudo ipfw add 100 pipe 1 tcp from any to me 80

Thanks to jQuery, providing a progress indicator only takes two lines of code. We’ll just append a loading div to the body when loadPage() starts, and remove the loading div when hijackLinks() is done. Example 3.4, “Adding a simple progress indicator to the page.” shows a modified version of Example 3.3, “This bit of JavaScript in android.js converts the links on the page to Ajax requests.”. The lines you need to add to android.js are shown in bold.

$(document).ready(function(){
    loadPage();
});
function loadPage(url) {
    $('body').append('<div id="progress">Loading...</div>');
    if (url == undefined) {
        $('#container').load('index.html #header ul', hijackLinks);
    } else {
        $('#container').load(url + ' #content', hijackLinks);
    }
}
function hijackLinks() {
    $('#container a').click(function(e){
        e.preventDefault();
        loadPage(e.target.href);
    });
    $('#progress').remove();
}
            

See Example 3.5, “CSS added to android.css used to style the progress indicator.” for the CSS that needs to be added to android.css to style the progress div.

#progress {
    -webkit-border-radius: 10px;
    background-color: rgba(0,0,0,.7);
    color: white;
    font-size: 18px;
    font-weight: bold;
    height: 80px;
    left: 60px;
    line-height: 80px;
    margin: 0 auto;
    position: absolute;
    text-align: center;
    top: 120px;
    width: 200px;
}
            

Figure 3.1. Without a progress indicator of some kind, your app will seem unresponsive and your users will get frustrated.

My site happens to have a single h2 at the beginning of each page that would make a nice page title (see Figure 3.2, “Before moving the page heading to the toolbar...”). You can see this in the HTML source shown in Chapter 2, Basic Styling. To be more mobile friendly, I’m going to pull that title out of the content and put it in the header (see Figure 3.3, “...and after moving the page heading to the toolbar.”). Again, jQuery to the rescue: you can just add three lines to the hijackLinks() function to make it happen. Example 3.6, “Using the h2 from the target page as the toolbar title.” shows the hijackLinks function with these changes.

Figure 3.2. Before moving the page heading to the toolbar...

Figure 3.3. ...and after moving the page heading to the toolbar.

function hijackLinks() {
    $('#container a').click(function(e){
        e.preventDefault();
        loadPage(e.target.href);
    });
    var title = $('h2').html() || 'Hello!';
    $('h1').html(title);
    $('h2').remove();
    $('#progress').remove();
}
            

The double pipe (||) in the first line of inserted code (shown in bold) is the JavaScript logical operator OR. Translated into English, that line would read: “Set the title variable to the HTML contents of the h2 element, or to the string ‘Hello!’ if there is no h2 element.” This is important because the first page load won’t contain an h2 because we are just grabbing the nav uls.

Suppose I had a page on my site with a title too long to fit in the header bar (Figure 3.4, “Text wrapping in the toolbar is not very attractive...”). I could just let the text break onto more than one line, but that would not be very attractive. Rather, I can update the #header h1 styles such that long text will be truncated with a trailing ellipis (see Figure 3.5, “...but we can beautify it with a CSS ellipsis.” and Example 3.7, “Adding an ellipsis to text that is too long for its container.”). This might be my favorite little-known CSS trick.

Figure 3.4. Text wrapping in the toolbar is not very attractive...

Figure 3.5. ...but we can beautify it with a CSS ellipsis.

#header h1 {
    color: #222;
    font-size: 20px;
    font-weight: bold;
    margin: 0 auto;
    padding: 10px 0;
    text-align: center;
    text-shadow: 0px 1px 1px #fff;
    max-width: 160px;
    overflow: hidden;
    white-space: nowrap;
    text-overflow: ellipsis;
}
            

Here’s the rundown: max-width: 160px instructs the browser not to allow the h1 element to grow wider than 160px. Then, overflow: hidden instructs the browser to chop off any content that extends outside of the element borders. Next, white-space: nowrap prevents the browser from breaking the line into two. Without this line, the h1 would just get taller to accommodate the text at the defined width. Finally, text-overflow: ellipsis appends three dots to the end of any chopped off text to indicate to the user that she is not seeing the entire string.

Let’s say you have a page that is longer than the viewable area on the phone. The user visits the page, scrolls down to the bottom, and clicks on a link to an even longer page. In this case, the new page will show up "pre-scrolled" instead of at the top as you'd expect.

Technically, this makes sense because we are not actually leaving the current (scrolled) page, but it’s certainly a confusing situation for the user. To rectify the situation, I have added a scrollTo() command to the loadPage() function (see Example 3.8, “It’s a good idea to scroll back to the top when a user navigates to a new page.”).

Whenever a user clicks a link, the page will first jump to the top. This has the added benefit of ensuring that the loading graphic is visible if the user clicks a link at the bottom of a long page.

function loadPage(url) {
    $('body').append('<div id="progress">Loading...</div>');
    scrollTo(0,0);
    if (url == undefined) {
        $('#container').load('index.html #header ul', hijackLinks);
    } else {
        $('#container').load(url + ' #content', hijackLinks);
    }
}
            

Like most sites, mine has links to external pages (i.e. pages hosted on other domains). I don’t want to hijack these external links because it wouldn’t make sense to inject their HTML into my Android-specific layout. In Example 3.9, “You can allow external pages to load normally by checking the domain name of the url.”, I have added a conditional that checks the url for the existence of my domain name. If it’s found, the link is hijacked and the content is loaded into the current page; i.e. Ajax is in effect. If not, the browser will navigate to the url normally.

function hijackLinks() {
    $('#container a').click(function(e){
        var url = e.target.href;
        if (url.match(/jonathanstark.com/)) {
            e.preventDefault();
            loadPage(url);
        }
    });
    var title = $('h2').html() || 'Hello!';
    $('h1').html(title);
    $('h2').remove();
    $('#progress').remove();
}
            

The elephant in the room at this point is that the user has no way to navigate back to previous pages (remember that we've hijacked all the links, so the browser page history won’t work). Let’s address that by adding a back button to the top left corner of the screen. First, I’ll update the JavaScript, and then I’ll do the CSS.

Adding a standard toolbar back button to the app means keeping track of the user’s click history. To do this, we’ll have to A) store the url of the previous page so we know where to go back to, and B) store the title of the previous page, so we know what label to put on the back button.

Adding this feature touches on most of the JavaScript we’ve written so far in this chapter, so I’ll go over the entire new version of android.js line by line (see Example 3.10, “Expanding the existing JavaScript example to include support for a back button.”). The result will look like Figure 3.6, “It wouldn’t be an mobile app without a glossy, left-arrow back button.”.

Figure 3.6. It wouldn’t be an mobile app without a glossy, left-arrow back button.

 var hist = [];
 var startUrl = 'index.html';
 $(document).ready(function(){
     loadPage(startUrl);
 });
 function loadPage(url) {
    $('body').append('<div id="progress">Loading...</div>');
    scrollTo(0,0);
    if (url == startUrl) {
        var element = ' #header ul';
    } else {
        var element = ' #content';
    }
    $('#container').load(url + element, function(){
        var title = $('h2').html() || 'Hello!';
        $('h1').html(title);
        $('h2').remove();
        $('.leftButton').remove();
        hist.unshift({'url':url, 'title':title});
        if (hist.length > 1) {
            $('#header').append('<div class="leftButton">'+hist[1].title+'</div>');
            $('#header .leftButton').click(function(){
                var thisPage = hist.shift();
                var previousPage = hist.shift();
                loadPage(previousPage.url);
            });
        }
        $('#container a').click(function(e){
            var url = e.target.href;
            if (url.match(/jonathanstark.com/)) {
                e.preventDefault();
                loadPage(url);
            }
        });
        $('#progress').remove();
    });
}            
            

Now that we have our back button, all that remains is to purty it up with some CSS (see Example 3.11, “Add the following to android.css to beautify the back button with a border image.”). I start off by styling the text with font-weight, text-align, line-height, color, and text-shadow. I continue by placing the div precisely where I want it on the page with position, top, and left. Then, I make sure that long text on the button label will truncate with an ellipis using max-width, white-space, overflow, and text-overflow. Finally, I apply a graphic with border-width and -webkit-border-image. Unlike my earlier border image example, this image has a different width for the left and right borders because the image is made asymetrical by the arrowhead on the left side.

#header div.leftButton {
    font-weight: bold;
    text-align: center;
    line-height: 28px;
    color: white;
    text-shadow: 0px -1px 1px rgba(0,0,0,0.6);
    position: absolute;
    top: 7px;
    left: 6px;
    max-width: 50px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
    border-width: 0 8px 0 14px;
    -webkit-border-image: url(images/back_button.png) 0 8 0 14;
}
            

By default, Android displays an orange highlight to clickable objects that have been tapped (Figure 3.7, “By default, Android displays an orange highlight to clickable objects that have been tapped.”). This may appear only briefly, but removing it is easy and makes the app look much better. Fortunately, Android supports a CSS property called -webkit-tap-highlight-color that allows you to suppress this behavior, which I’ve done here by setting the tap highlight to a fully transparent color (see Example 3.12, “Add the following to android.css to remove the default tap highlight effect.”).

Figure 3.7. By default, Android displays an orange highlight to clickable objects that have been tapped.

#header div.leftButton {
    font-weight: bold;
    text-align: center;
    line-height: 28px;
    color: white;
    text-shadow: 0px -1px 1px rgba(0,0,0,0.6);
    position: absolute;
    top: 7px;
    left: 6px;
    max-width: 50px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
    border-width: 0 8px 0 14px;
    -webkit-border-image: url(images/back_button.png) 0 8 0 14;
    -webkit-tap-highlight-color: rgba(0,0,0,0);
}
            

In the case of the back button, there could be at least a second or two of delay before the content from the previous page appears. To avoid frustration, I want the button to look clicked the instant it’s tapped. In a desktop browser, this would be a simple process; you’d just add a declaration to your CSS using the :active psuedo class to specify an alternate style for the object that was clicked. I don't know if it’s a bug or a feature, but this approach does not work on Android; the :active style is ignored.

I toyed around with combinations of :active and :hover, which brought me some success with non-Ajax apps. However, with an Ajax app like the one we are using here, the :hover style is sticky (i.e. the button appears to remain “clicked” even after the finger is removed).

Fortunately, the fix is pretty simple. I use jQuery to add the class clicked to the button when the user taps it. I’ve opted to apply a darker version of the button image to the button in the example (see Figure 3.8, “It might be tough to tell in print, but the clicked back button is a bit darker than the default state.” and Example 3.13, “Add the following to android.css to make the back button looked clicked when the user taps it.”). You'll need to make sure you have a button image called back_button_clicked.png in the images subfolder. See the section called “Adding Basic Behavior with jQuery” for tips on finding or creating your own button images.

Figure 3.8. It might be tough to tell in print, but the clicked back button is a bit darker than the default state.

#header div.leftButton.clicked {
    -webkit-border-image: url(images/back_button_clicked.png) 0 8 0 14;
}
            

With the CSS in place, I can now update the portion of the android.js that assigns the click handler to the back button. First, I add a variable, e, to the anonymous function in order to capture the incoming click event. Then, I wrap the event target in a jQuery selector and call jQuery’s addClass() function to assign my clicked CSS class to the button:

$('#header .leftButton').click(function(e){
    $(e.target).addClass('clicked');
    var thisPage = hist.shift();
    var previousPage = hist.shift();
    loadPage(lastUrl.url);
});