This gap is due to the fact that 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 style sheets. Now, the app will completely fill the window when launched (Figure 7.9, “The body height has been changed from 420px to 460px. Now the app takes up the whole screen.”) .

Figure 7.9. The body height has been changed from 420px to 460px. Now 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, “We need to change the default name and icon for the app.”).

Figure 7.10. We need to change the default name and icon for the 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, select PhoneGap→Config→Info.plist in the Groups & Files panel. The Info.plist file should be displayed in the bottom right panel of the window (Figure 7.11, “We need to change the bundle display name in Xcode from the default (i.e. PhoneGap) to the name of our app (i.e Kilo).”).

You should see that the Bundle display name says PhoneGap. Double-click PhoneGap and change it to Kilo (Figure 7.12, “The bundle display name in Xcode has been set to the name of our app (i.e Kilo)”). Then save the file, 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 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. We need to change the bundle display name in Xcode from the default (i.e. PhoneGap) to the name of our app (i.e Kilo).

Figure 7.12. The bundle display name in Xcode has been set to the name of our app (i.e Kilo)

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

Next we need to change the home screen icon from the PhoneGap default (Figure 7.10, “We need to change the default name and icon for the app.”) to our custom icon. The file format for both the app icon and the web clip icon is a 57px X 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” (see Figure 7.21, “The custom home screen icon is a chocolate frosted donut with jimmies on a pink background.”).

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 added 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 Adding Settings to Info.plist 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.

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.

The default PhoneGap home screen icon is named icon.png and 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 (Figure 7.21, “The custom home screen icon is a chocolate frosted donut with jimmies on a pink background.”), 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.13, “The new bundle display name now appears on the iPhone home screen.”).

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 x 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 graphic 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.

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

With PhoneGap, the startup screen has to be 320px x 480px regardless of what type of status bar is used. So, if you created a 320px x 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 (Figure 7.26, “The custom launch graphic says Kilo in gray text on a black background.”) as shown in Figure 7.27, “Replace Default.png in the iphone directory with your own custom 320px x 480px png graphic.”, clean the project, and click the Build and Run button. The iPhone Simulator should open and launch the app. You should see the custom graphic displayed as the app launches (Figure 7.28, “Our custom startup graphic now appears when the app is launched.”).

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

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

Figure 7.26. The custom launch graphic says Kilo in gray text on a black background.

Figure 7.27. Replace Default.png in the iphone directory with your own custom 320px x 480px png graphic.

Figure 7.28. Our custom startup graphic now appears when the app is launched.

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 them over their daily calorie budget. To do so, 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 4 parameters of the executeSql() method:

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

No comments yet

Add a comment

No comments yet

Add a comment

No comments yet

Add a comment

No comments yet

Add a comment

No comments yet

Add a comment

No comments yet

Add a comment

	It starts off by grabbing the current total from the first row of the result. Since we are just asking for the sum of a column, the database is only going to return one row (i.e. this query will always return one row). Remember that the records of the result set are accessed with the item() method of the rows property of the result object, and that the rows are 0 based (meaning that the first row is 0). No comments yet Add a comment
	Check to see if the current calorie total for the day is greater than the daily budget specified on the Settings panel. If so, the block that follows will be executed. No comments yet Add a comment
	Calculate how far the user is over his calorie budget. No comments yet Add a comment
	Compose a message to display to the user. No comments yet Add a comment
	This is a try/catch block that attempts to call the beep() and vibrate() methods of the navigator notification object. These methods only exist in PhoneGap, so if the user is running the app in a browser they will fail and execution will jump to the catch block. Since there is no browser-based equivalent to beep or vibrate, the catch block has been left empty. No comments yet Add a comment The PhoneGap beep() method plays a wav file when called. The file is named beep.wav and lives in the iphone directory (Figure 7.33, “The PhoneGap beep() method plays the beep.wav file from the iphone directory.”). The default file sounds sort of like a cricket and is probably fine for most situations. If you’d prefer your own beep sound, just create a wav file named beep.wav and replace the default file in the iphone directory. No comments yet Add a comment Figure 7.33. The PhoneGap beep() method plays the beep.wav file from the iphone directory. No comments yet Add a comment
	This is a try/catch block that attempts to call the alert() method of the navigator notification object. This method only exists in PhoneGap, so if the user is running the app in a browser it will fail and execution will jump to the catch block. The browser-based equivalent to alert is a standard JavaScript alert, which is called as a fallback. No comments yet Add a comment There are a couple of differences between the PhoneGap alert and the native JavaScript alert. For example, the PhoneGap alert allows you to control the title and the button name (Figure 7.34, “The PhoneGap alert allows you to specify the title and button label.”); the javascript alert does not (Figure 7.35, “A native JavaScript alert does not allow you to specify the title and button label.”). No comments yet Add a comment There is also a more subtle difference between the two alerts: The native JavaScript alert is modal and the PhoneGap alert is not. In other words, script execution will pause at the point you call a native alert, whereas execution will continue with the PhoneGap version. This may or may not be a big deal depending on the nature of your application, so keep this distinction in mind. 4 comments William Doane Posted 1 month, 4 days and 7 hours ago "between the two alert" ---> "between the two alerts" William Doane Posted 1 month, 4 days and 7 hours ago "asynchronous" ---> "modal" (which would require a little explanation, but is more accurate) Leon Cowle Posted 1 month, 2 days and 10 hours ago "asynchronous" --> "blocking" (instead of modal :-) ) Jonathan Stark Posted 28 days and 1 hour ago @William and @Leon - Thanks for the input, fixed. Add a comment Figure 7.34. The PhoneGap alert allows you to specify the title and button label. No comments yet Add a comment Figure 7.35. A native JavaScript alert does not allow you to specify the title and button label. 2 comments William Doane Posted 1 month, 4 days and 7 hours ago Note that this is generated when the site is viewed with Mobile Safari Jonathan Stark Posted 28 days and 1 hour ago @William - you can generate a native javascript alert from within phonegap, too. Add a comment

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 & Run.

Let’s update Kilo to save the location when entries are created. Once we have that infomation, 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 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 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 & 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 to 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 listening 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 popup (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 to Info.plist 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.