Gears demos

Simple demo and brief tutorial on how to use Gears to store data locally and create desktop shortcuts

Demo

Database API

Enter a message in the form below and it will be stored on your local machine. Every time you return to this page using the same browser and machine, the data will persist (no cookies!).

Existing messages

Desktop API

Create shortcut

Tutorial

To view this demo, first make sure you have Gears installed from http://gears.google.com/.

Prior to working with Gears, your Web application needs to initialize Gears using gears_init.js, which can be found at http://code.google.com/apis/gears/gears_init.js. Download this file and add the following line to your document after the HTML:

<script type="text/javascript" src="gears_init.js"></script>

There are actually three things happening on this page, and we'll step through each of them in turn:

  1. We write out the version of Gears,
  2. work with the Database API and
  3. use the Desktop API

Write out the version of Gears

After the script element that references gears_init.js, start another script element and add the following lines of code:

<script type="text/javascript">
if (window.google && google.gears) {
document.getElementById('info').innerHTML = 'Gears version ' + google.gears.factory.version;
google.gears.factory.getPermission('theMechanism');
} else {
document.getElementById('info').innerHTML = 'Please download Gears'
}
</script>

The first line checks to see if Gears is installed; it it's not, we prompt the user to install it.

If Gears is installed, we use the version property of the Factory class and let the user know which version of Gears they have installed.

We then manually call the getPermission method of the Factory class, which indicates if the site has permission to use Gears. If is does not, a dialog will pop up, requesting permission. This dialog is passed one of three optional parameters, which is the friendly name of the site requesting permission.

Read data using the Database API

After the line that checks permission, add the following code:

var db = google.gears.factory.create('beta.database');
db.open('themechanism'); db.execute('CREATE TABLE IF NOT EXISTS test (phrase TEXT, timestamp INT)');
var div = document.getElementById('messages');
var p = document.createElement('p');
p.id = 'msgContent';
var str = '';
var rs = db.execute('SELECT phrase, timestamp FROM test ORDER BY timestamp DESC');
while (rs.isValidRow()) {
str = str + rs.field(0) + '
';
rs.next();
}
rs.close();
p.innerHTML = str;
div.appendChild(p);

The first line uses the create method of the Factory class to instantiate the Database Module API (DB hereafter) as a global variable named db.

Now that we have a DB object, which provides browser-local relational data storage, we use the open method of the DB class to open the local database named "themechanism."

The next line calls the execute method of the DB class, which takes one required parameter: an SQL statement. For our demo, we create a table named "test" (if it does not already exist!) that has two columns: one to store the phrase and one to store a timestamp.

We then do a little DOM manipulation to write out our messages. First we grab the div element with the id "messages," create a new p element and assign it the id "msgContent". We also create a variable named str which is set to an empty string.

Next, we again call the execute method of the DB class, but this time with an SQL statement that returns a ResultSet class, which is stored in the rs variable.

Using the isValidRow method of the ResultSet class, which returns true if we can call the data extraction methods of the ResultSet class, we iterate through the records.

As we iterate through the records, we append the value of the "phrase"field and a br element to our str var. We then use the next method the ResultSet class to move to the next record.

After all the records have been iterated through, we use the close method of the ResultSet class to close the ResultSet. Note, we are currently required to call this method when we are finished with the result set.

Finally, we set the innerHTML property of our p element and append it to our div.

Write data using the Database API

Outside of our if statement that checks if Gears is installed, add the following code:

function storeData() {
if (window.google && google.gears) {
var strPhrase = document.getElementById('txtPhrase').value;
if (strPhrase.length > 0) {
db.execute('INSERT INTO test VALUES (?, ?)', [strPhrase, new Date().getTime()]);
document.getElementById('txtPhrase').value = '';
var div = document.getElementById('msgContent');
div.innerHTML = strPhrase + '<br />' + div.innerHTML;
}
}
return false;
}
document.getElementById('frmDb').onsubmit = storeData;

The storeData function again tests to see if Gears is installed. If it is, we grab the value of the text input and check to make sure there is a value. If there is, we again call the execute method of the DB class. Since we're using an insert statement, we use ? as a placeholder for bind parameters and also pass an optional array of bind parameters that will replace the ? marks. We does this because SQLite automatically quote-escapes bind parameters.

Next we clear the text input and append the new phrase to our list of existing phrases. To stop the actual form submitting, the last line in the storeData function returns false.

Finally, we attach the storeData function to the submit handler of our form.

Use the Desktop API

After our last line of JavaScript that attaches the storeData function to the submit handler of our form, add the following code:

function shortcut() {
if (window.google && google.gears) {
var desktop = google.gears.factory.create('beta.desktop');
desktop.createShortcut('theMechanism Gears demo',
'http://themechanism.com/barkode/demos-tutorials/gears.php',
{
'128x128': 'http://themechanism.com/barkode/demos-tutorials/images/icons/gears-128x128.png',
'48x48': 'http://themechanism.com/barkode/demos-tutorials/images/icons/gears-48x48.png',
'32x32': 'http://themechanism.com/barkode/demos-tutorials/images/icons/gears-32x32.png',
'16x16': 'http://themechanism.com/barkode/demos-tutorials/images/icons/gears-16x16.png'
},
'Gears demos at http://themechanism.com/barkode/demos-tutorials/gears.php'
);
}
}

This function was attached to the "Create shortcut" link using inline JavaScript (I know, bad!). After testing to make sure that Gears is installed, we use the create method of the Factory class to instantiate the Desktop API as a local variable named desktop.

We then call the createShortcut method of the Desktop class, which takes three required parameters and one required one:

  1. name—the user-visible name of the shortcut. It cannot contain any of these characters: "\/:*?<>|
  2. url—the address to launch when the user opens the shortcut. The URL must be in the same origin as the calling page.
  3. icons—an object containing one or more of these named properties: 128x128, 48x48, 32x32, 16x16. The value of each property must be the URL of a PNG-formatted image with dimensions matching the property name. A data URL containing base64-encoded PNG data can also be used.
  4. description—optional additional text to display in the confirmation dialog.

Gears documentation

Comment or ask a question

Last update—24 July 2008

barKode logo

Upcoming events

Recent Blog Posts

View all posts by Jeffrey

Feeds
Want to work with us yet? We’re ready when you are.