You’ll notice that there is a 40px gap at the bottom of the window (Figure 7.8, “You’ll notice a 40px gap at the bottom of the screen”). This occurs because jQTouch does not realize that we are running in full screen mode, so it’s allowing room for the Safari toolbar. This makes sense from jQTouch’s perspective, because the app technically isn’t running as a full-screen web app. But it is running as a native app, and therefore has access to the whole screen. Fortunately, the fix is easy. Just open kilo.js and add the following code to the document ready function:

if (typeof(PhoneGap) != 'undefined') {
    $('body > *').css({minHeight: '460px !important'});
}

This code uses the typeof operator to make sure the PhoneGap object has been defined. If the code is running inside of PhoneGap, this conditional will evaluate to true. If the code is launched as a web app, the PhoneGap object will be undefined and the conditional will evaluate to false.

When the app is launched with PhoneGap, the immediate children of the HTML body element will be given a minimum height of 460px. To make sure that the declaration takes effect, I’ve added the !important directive to override any conflicting instructions elsewhere in the stylesheets. Now the app will completely fill the window when launched (Figure 7.9, “After the body height is changed from 420px to 460px, the app takes up the whole screen”).

Figure 7.9. After the body height is changed from 420px to 460px, the app takes up the whole screen

Next, we need to change the default name and icon for the app. By default, PhoneGap apps are called “PhoneGap” and have a blue icon with a ladder on it (Figure 7.10, “The default name and icon for our app”).

Figure 7.10. The default name and icon for our app

To change the app name on the home screen, open the project in Xcode by double-clicking the PhoneGap.xcodeproj file in the Finder. Once it’s open, go to PhoneGap→Config→Info.plist in the Groups & Files panel. The Info.plist file should be displayed in the bottom-right panel of the window.

You should see that the bundle display name is set to PhoneGap (Figure 7.11, “The bundle display name in Xcode is PhoneGap”). Double-click PhoneGap and change it to Kilo (Figure 7.12, “The bundle display name is now set to the name of our app (Kilo)”). Then save the file, clean the project (by clicking Build→Clean), and click the Build and Run button. The iPhone Simulator should open and launch the app. Click the home button in the simulator to return to the home screen and note that the app name has been updated from PhoneGap to Kilo (Figure 7.13, “The new bundle display name now appears on the iPhone home screen”).

Figure 7.11. The bundle display name in Xcode is PhoneGap

Next, we need to change the home screen icon from the PhoneGap default (the ladder, pictured in Figure 7.10, “The default name and icon for our app”) to our custom icon. The file format for both the app icon and the Web Clip icon is a 57px × 57px PNG, so you can use the exact same web app icon that you created for the home screen icon in the section called “Adding an Icon to the Home Screen”.

Figure 7.12. The bundle display name is now set to the name of our app (Kilo)

Figure 7.13. The new bundle display name now appears on the iPhone home screen

The only difference is that with the Web Clip icon, we can prevent the iPhone from adding gloss to the graphic by toggling the addGlossToIcon setting in jQTouch; this setting will have no effect in PhoneGap. To prevent adding gloss to your icon in PhoneGap, select Config/Info.plist in the Groups & Files panel of the main Xcode window and check the box next to UIPrerenderedIcon in Info.plist (you may need to add this to Info.plist; see next for instructions).

Figure 7.14. Select Config/Info.plist in the Groups & Files panel of the main Xcode window

Figure 7.15. Select Add Row from the contextual menu

Figure 7.16. Type UIPrerenderedIcon in the key field

The default PhoneGap home screen icon is named icon.png and is located in PhoneGap’s iphone directory (Figure 7.20, “The default home screen icon is a white ladder on a blue background”). Replace the default icon file with your custom file (Figures 7.21 and 7.22), clean the project (click Build→Clean), and click the Build and Run button. The iPhone Simulator should open and launch the app. Click the home button in the simulator to return to the home screen, and note that the app icon has been updated to a chocolate frosted donut with jimmies on a pink background (Figure 7.23, “Our custom app icon now appears on the iPhone home screen”).

Figure 7.17. Press the Enter key to save your entry in the key field

Figure 7.18. Select Boolean from the Value Type submenu

Figure 7.19. Check the checkbox to tell Xcode not to add gloss to your icon

Figure 7.20. The default home screen icon is a white ladder on a blue background

Figure 7.21. The custom home screen icon is a chocolate frosted donut with jimmies on a pink background

Figure 7.22. Replace icon.png in iphone directory with your own custom 57px × 57px png graphic

Figure 7.23. Our custom app icon now appears on the iPhone home screen

Next we need to change the startup screen from the PhoneGap default (Figure 7.24, “We need to change the default startup graphic for the app”) to our custom startup screen. Back in the section called “Providing a Custom Startup Graphic”, you created a PNG file to serve as the startup screen when the web app is launched in full screen mode from a Web Clip icon on the home screen.

Figure 7.24. We need to change the default startup graphic for the app

For full-screen web apps that use a gray or black status bar, this graphic needs to be 320px × 460px, and for apps that use a black-translucent status bar, it must be 320px × 480px (20 pixels taller).

With PhoneGap, the startup screen has to be 320px × 480px regardless of what type of status bar is used. So if you created a 320px × 460px full-screen graphic, add 20px to the height.

The default PhoneGap startup graphic is named Default.png and is located in PhoneGap’s iphone directory (Figure 7.25, “The default launch graphic says PhoneGap in gray text on a white background”). Replace the default startup graphic with your custom graphic (as shown in Figures 7.26 and 7.27) as shown in Figure 7.27, “Replace Default.png in the iphone directory with the custom 320px × 480px PNG graphic”, clean the project, and click the Build and Run button. The iPhone Simulator should open and launch the app, and you should see the custom graphic displayed (Figure 7.28, “Our custom startup graphic now appears when the app is launched”).

Figure 7.25. The default launch graphic says PhoneGap in gray text on a white background

PhoneGap makes beep, vibrate, and alert functions so simple that I’m going to lump them together into one example. Specifically, we’ll set up the app to beep, vibrate, and display a custom alert when the user creates an entry that puts her over her daily calorie budget. To do this, add the following function to the end of kilo.js:

function checkBudget() {
    var currentDate = sessionStorage.currentDate;
    var dailyBudget = localStorage.budget;
    db.transaction(
        function(transaction) {
            transaction.executeSql(
                'SELECT SUM(calories) AS currentTotal FROM entries WHERE date = ?;', 
                [currentDate], 
                function (transaction, result) {
                    var currentTotal = result.rows.item(0).currentTotal;
                    if (currentTotal > dailyBudget) {
                        var overage = currentTotal - dailyBudget;
                        var message = 'You are '+overage
                        + ' calories over your daily budget. 
                        + ' Better start jogging!';
                        try {
                            navigator.notification.beep();
                            navigator.notification.vibrate();
                        } catch(e){
                            // No equivalent in web app
                        }
                        try {
                            navigator.notification.alert(message, 
                                'Over Budget', 'Dang!');
                        } catch(e) {
                            alert(message);
                        }
                    }
                }, 
                errorHandler
            );
        }
    );
}

Here’s the blow-by-blow description:

Let’s break down the four parameters of the executeSql() method:

And here is what’s going on in the anonymous function that was passed in as the third parameter:

With our checkBudget() function complete, we can now call it by adding a single line to the success callback of our createEntry() function:

function createEntry() {
    var date = sessionStorage.currentDate;
    var calories = $('#calories').val();
    var food = $('#food').val();
    db.transaction(
        function(transaction) {
            transaction.executeSql(
                'INSERT INTO entries (date, calories, food) VALUES (?, ?, ?);', 
                [date, calories, food], 
                function(){
                  refreshEntries();
                  checkBudget();
                  jQT.goBack();
                }, 
                errorHandler
            );
        }
    );
    return false;
}

After you’ve made these changes, save the kilo.js file, clean the project (Build→Clean), and click Build and Run.

Figure 7.33. The PhoneGap beep() method plays the beep.wav file from the iphone directory

Figure 7.34. The PhoneGap alert allows you to specify the title and button label

Figure 7.35. A native JavaScript alert does not allow you to specify the title and button label

Let’s update Kilo to save the location where entries are created. Once we have that information, we’ll add a “Map Location” button that will open the built-in Maps application and drop a pin at the point where the entry was created.

The first step is to add latitude and longitude columns to the database to store the information. To do so, replace the CREATE TABLE statement in kilo.js with the following:

db.transaction(
    function(transaction) {
        transaction.executeSql(
            'CREATE TABLE IF NOT EXISTS entries ' +
            '   (id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, ' +
            '    date DATE NOT NULL, food TEXT NOT NULL, ' +
            '    calories INTEGER NOT NULL, ' +
            '    longitude TEXT NOT NULL, latitude TEXT NOT NULL);'
        );
    }
);

Next, we’ll rewrite the createEntry() function that we first saw in the section called “Inserting Rows” to use the geolocation feature of the phone to determine the current latitude and longitude. Replace the existing createEntry() function in kilo.js with this:

function createEntry() {
    try {
        navigator.geolocation.getCurrentPosition(
            function(position){
                var latitude = position.coords.latitude;
                var longitude = position.coords.longitude;
                insertEntry(latitude, longitude);
            },
            function(){
                insertEntry();
            } 
        );
    } catch(e) {
        insertEntry();
    }
    return false;
}

Wondering where the SQL INSERT statement got to? Let’s take a look at the insertEntry() function. This new function is what creates the entry in the database. Add the following to kilo.js:

function insertEntry(latitude, longitude) {
    var date = sessionStorage.currentDate;
    var calories = $('#calories').val();
    var food = $('#food').val();
    db.transaction(
        function(transaction) {
            transaction.executeSql(
                'INSERT INTO entries (date, calories, food, latitude, longitude) ' + 
                    'VALUES (?, ?, ?, ?, ?);',
                [date, calories, food, latitude, longitude],
                function(){
                    refreshEntries();
                    checkBudget();
                    jQT.goBack();
                }, 
                errorHandler
            );
        }
    );
}

In order to confirm that Kilo is actually saving these location values, we’ll want to display them somewhere in the interface. Let’s add an Inspect Entry panel to display the stored values. We’ll include a Map Location button on the panel that will display where the entry was created. Add the following to index.html, right before the closing body tag (</body>):

<div id="inspectEntry">
    <div class="toolbar">
        <h1>Inspect Entry</h1>
        <a class="button cancel" href="#">Cancel</a>
    </div>
    <form method="post">
        <ul class="rounded">
            <li><input type="text" placeholder="Food" name="food" value="" /></li>
            <li><input type="tel" placeholder="Calories" name="calories" 
                value="" /></li>
            <li><input type="submit" value="Save Changes" /></li>
        </ul>
        <ul class="rounded">
            <li><input type="text" name="latitude" value="" /></li>
            <li><input type="text" name="longitude" value="" /></li>
            <li><p class="whiteButton" id="mapLocation">Map Location</p></li>
        </ul>
    </form>
</div>

This should look very similar to the New Entry panel that we first saw in Example 4.5, “The HTML for the New Entry panel”, so I’ll just call out a couple of things.

Now we need to give the user a way to navigate to this Inspect Entry panel, so we’ll modify the behavior of the Date panel such that when the user taps an entry in the list, the Inspect Entry panel will slide up from the bottom of the screen.

The first step is to wire up the click event handler (which we’ll create next), and also to modify the way clicks on the Delete button are processed. Add the three highlighted changes below to the refreshEntries() function in kilo.js:

function refreshEntries() {
    var currentDate = sessionStorage.currentDate;
    $('#date h1').text(currentDate);
    $('#date ul li:gt(0)').remove();
    db.transaction(
        function(transaction) {
            transaction.executeSql(
                'SELECT * FROM entries WHERE date = ? ORDER BY food;', 
                [currentDate], 
                function (transaction, result) {
                    for (var i=0; i < result.rows.length; i++) {
                        var row = result.rows.item(i);
                        var newEntryRow = $('#entryTemplate').clone();
                        newEntryRow.removeAttr('id');
                        newEntryRow.removeAttr('style');
                        newEntryRow.data('entryId', row.id);
                        newEntryRow.appendTo('#date ul');
                        newEntryRow.find('.label').text(row.food);
                        newEntryRow.find('.calories').text(row.calories);
                        newEntryRow.find('.delete').click(function(e){
                            var clickedEntry = $(this).parent();
                            var clickedEntryId = clickedEntry.data('entryId');
                            deleteEntryById(clickedEntryId);
                            clickedEntry.slideUp();
                            e.stopPropagation();
                        });
                        newEntryRow.click(entryClickHandler);
                    }
                }, 
                errorHandler
            );
        }
    );
}

Now let’s add the entryClickHandler() function to kilo.js:

function entryClickHandler(e){
    sessionStorage.entryId = $(this).data('entryId');
    db.transaction(
        function(transaction) {
            transaction.executeSql(
                'SELECT * FROM entries WHERE id = ?;', 
                [sessionStorage.entryId], 
                function (transaction, result) {
                    var row = result.rows.item(0);
                    var food = row.food;
                    var calories = row.calories;
                    var latitude = row.latitude;
                    var longitude = row.longitude;
                    $('#inspectEntry input[name="food"]').val(food);
                    $('#inspectEntry input[name="calories"]').val(calories);
                    $('#inspectEntry input[name="latitude"]').val(latitude);
                    $('#inspectEntry input[name="longitude"]').val(longitude);
                    $('#mapLocation').click(function(){
                        window.location = 'http://maps.google.com/maps?z=15&q='+
                            food+'@'+latitude+','+longitude;
                    });
                    jQT.goTo('#inspectEntry', 'slideup');
                }, 
                errorHandler
            );
        }
    );
}

Before you try running the app, be sure to delete it from the phone (or the simulator). That’s because the database won’t be created if it already exists, and an easy way to remove the database is to remove the app. To remove the app, tap and hold on its home screen icon until the icons start wobbling, then click the X to remove it. Press the home button to stop the wobbling. Then, clean the project (Build→Clean) and click “Build and Run” to try it out.

Next, let’s set up Kilo to duplicate the last entry in the list by shaking the phone. Add the following function to the end of kilo.js:

function dupeEntryById(entryId) {
    if (entryId == undefined) {
        alert('You have to have at least one entry in the list to shake a dupe.');
    } else {
        db.transaction(
            function(transaction) {
                transaction.executeSql(
                    ' INSERT INTO entries (date, food, calories, latitude, longitude)'
                    + ' SELECT date, food, calories, latitude, longitude'
                    + ' FROM entries WHERE id = ?;', 
                    [entryId], 
                    function() {
                        refreshEntries();
                    }, 
                    errorHandler
                );
            }
        );
    }
}

Now we need to tell the application when to start and stop watching the accelerometer. We’ll set it up to start watching when the Date panel finishes sliding into view, and to stop when it starts sliding out. To do this, we just need to add the following lines to the document ready function in kilo.js:

$('#date').bind('pageAnimationEnd', function(e, info){
    if (info.direction == 'in') {
        startWatchingShake();
    }
});
$('#date').bind('pageAnimationStart', function(e, info){
    if (info.direction == 'out') {
        stopWatchingShake();
    }
});

$('#date').bind('pageAnimationEnd', function(e, info){
    if (info.direction == 'in') {
        startWatchingShake();
    } else {
        stopWatchingShake();
    }
});

All that’s left for us to do is write the startWatchingShake() and stopWatchingShake() functions. Add the following functions to the end of kilo.js:

function startWatchingShake() {
    var success = function(coords){
        var max = 2;
        if (Math.abs(coords.x) > max 
        || Math.abs(coords.y) > max 
        || Math.abs(coords.z) > max) {
            var entryId = $('#date ul li:last').data('entryId');
            dupeEntryById(entryId);
        }
    };
    var error = function(){};
    var options = {};
    options.frequency = 100;
    sessionStorage.watchId = navigator.accelerometer.watchAcceleration(success, 
        error, options);
}
function stopWatchingShake() {
    navigator.accelerometer.clearWatch(sessionStorage.watchId);
}

And with that, we are ready to test. Save all your files, clean all targets, and build and run Kilo on your device. Navigate to the Date panel, add an entry if none exists, and shake the phone. You should see the page reload with an additional entry. Unfortunately, you’ll probably also see an Undo confirmation dialog (Figure 7.36, “We need to deactivate the undo manager to watch the accelerometer in peace”). To disable the undo manager so we can watch the accelerometer without being interrupted, we need to add a setting to Info.plist. Follow the steps described in Adding Settings to Info.plist to add a setting for UIApplicationSupportsShakeToEdit, and set it to false (Figure 7.37, “Add the UIApplicationSupportsShakeToEdit setting to Info.plist and leave it unchecked to disable “shake to undo” in your app”).

Figure 7.36. We need to deactivate the undo manager to watch the accelerometer in peace

Figure 7.37. Add the UIApplicationSupportsShakeToEdit setting to Info.plist and leave it unchecked to disable “shake to undo” in your app