Live Query utilizes the power of jQuery selectors by binding events or firing callbacks for matched elements auto-magically, even after the page has been loaded and the DOM updated. [from Docs]

So, why would you need Live Query? In cases where you are dynamically adding elements to a page (i.e. DOM) using jQuery, you may want events attached to them. So, for example, I have a page that has been loaded. In response to user actions, I want to add a link that, when clicked on, triggers a “click” event. Because this link element has been generated dynamically, it won’t match any of the CSS declarations or have the same behaviours of elements which were there when the page loaded.

You can see a live (and very simple) example of this. The code behind the example is:

$(document).ready(function()
{
/*
Without Using Live Query:
*/
$('#add_new_box').click(function(){
$('#box_holder').append('<div class="new-box"><a id="add-again" href="#">Add Smaller</a></div>'); });
// a problem here - this doesn't fire as expected...
$('#add-again').click(function(){
$('#add_new_box').append('<div class="small-box"></div>');
});
/*
Using Live Query:
*/
$('#lq_add_new_box').click(function(){
$('#lq_box_holder').append('
<div class="lq-new-box"><a id="lq_add-again" href="#">Add Smaller</a></div>');
});
$('#lq_add-again').livequery('click', function(){
$('#lq_add_new_box').append('<div class="small-box"></div>');
});
});    // end document.ready(function)

In the example, the first link clicked adds a <div> with a link inside it. This new link, when clicked, should add a smaller yellow box. However, because the “Add Smaller” link was added dynamically, it does not have the click behaviour associated with it. It’s here that Live Query comes in.

In the second part of the example, Live Query is used to bind a click event to the link that was dynamically added. This ensures that the (my) expected behaviour of clicking the link in the red box and having a smaller yellow box appear goes to plan.

Having a web application be as responsive as possible is a target that should always be set. Doing so can be achieved in lots of ways, one of them being to minimise the number of page reloads the user needs to sit through. For what I am working on at the moment, Live Query just added a big lump of responsiveness to the interface. A great jQuery plugin.

In this section, I’ll show how to use the Gears WorkerPool to carry out operations without affecting the user interface. Also included is a simple example of using the Gears HTTPRequest object to retrieve data from the remote database.

Read the first part of the tutorial.

Using the WorkerPool

The Gears Workerpool allows JavaScript to run in the background without affecting the performance of browser window. This means that the user’s browser won’t slow down or lock up while there is processing going on behind the scenes. This gives the  opportunity to create more intensive scripts, and to have your web application process information while the user carries on with their other work.


// create a workerpool
var workerPool = google.gears.factory.create('beta.workerpool');
// handle messages from the worker
workerPool.onmessage = function(a, b, message) {
console.log('Received message from worker ' + message.sender + ': \n' + message.body);
};
// create a child worker from a URL
var childWorkerId = workerPool.createWorkerFromUrl('/scripts/gears/gears_db_load.js');
// send the child a message... (messageBody, Unique Worker ID)
workerPool.sendMessage("loadAllTreat", childWorkerId);


When the function is called it creates a Workerpool object (more details from the Gears Workerpool API). This is used to create individual Workers that can be set to do different jobs. The Workers do not have access to the Window object, which means that they must interact by sending messages to each other.  The “workerPool.onmessage” callback above is an example of how Workers accept messages from each other (in this case, the details of the message (the Worker that sent it, and the message body) are being written to the Firebug console window.

The line:

var childWorkerId = workerPool.createWorkerFromUrl('/scripts/gears/gears_db_load.js');

is creating a Worker from an external script – gears_db_load.js (more on that in a moment).  The createWorkerFromUrl method returns a unique id value for the Worker – it is using this that the destination of messages sent between Workers is known.

The final line above sends a message to the Worker; in this case, telling it what action to take. The second parameter is the id value of the Worker, which allows the message to be routed to the correct place.

My First Worker


// gears_db_load.js
/*
Workerpool JS to load remote data to local db after Setup
*/
(function(){
var wp = google.gears.workerPool;
var sender; // Parent Worker ID
// handle incoming messages:
wp.onmessage = function(a, b, message) {
try{
var msg = message.body; // what was the message
sender = message.sender; // Where did the message come from
var resp; // response to be returned to the Parent Worker
switch (msg)
{
case 'loadAllTreat':
getAllTreatments(); /* call a function to do something...*/
break;
default:
resp = 'Oops...no message sent!!';
wp.sendMessage(resp, sender);
break;
}
} // try
catch(ex)
{ // send back an error message if needed
wp.sendMessage('Error in worker: '+ err.message, sender);
}
} // onmessage


// handle any errors that come up...
wp.onerror = function( err ){
wp.sendMessage('Error in worker: '+ err.message, sender);
return true;
}

This is creating a new Worker, and uses the onmessage callback to check what message has been passed to it by the sender. A switch statement is used to decide what action is needed, based on the message passed in. In this example, if the message is “loadAllTreat" the function getAllTreatments() is called, otherwise, a message is passed back to the sender.

Also included is an onerror callback that is used to return an error message to the sender, should an error occur.

Gears HTTPRequest

The getAllTreatments() function uses the Gears HTTPRequest to get data from the server using AJAX. The code below demonstrates carrying out the request, and parsing the JSON response from the server. [Note: it stops short of doing anything with the data returned - this will depend on the application in question]

function getAllTreatments(){
var request = google.gears.factory.create('beta.httprequest');
// get Treatment & Treatment Category Data
request.open('GET', '/path/to/my/data/');
request.onreadystatechange = function() {
if (request.readyState == 4) {
try{
response = request.responseText;
var jsResp = json_parse(response); // using http://www.JSON.org/json_parse.js
//...
// do something with the json response, for example, insert it into local database..
//...
}// try
catch(ex){
wp.sendMessage("Worker Error: line - "+ ex.lineNumber + " Ex: "+ ex.message, sender);
} // catch
} // readystate
}; // onstatechange
request.send();
} // getAllTreatments()

The “var request” holds a Gears httpRequest object. It needs a place to request the data from, which is added using “request.open”, and supplying request type (“GET”) the path to the data (‘/path/to/my/data’). When the request completes, the if statement within the onreadystatechange callback is triggered. This parses the response (in this example, the server is supplying a JSON response) using json_parse (available from: http://www.JSON.org/json_parse.js.

The example above stops short of doing something with the response after it has been parsed. One example of what could be done with the data, is to insert it into the local database.

Other Alternatives

There are a number of options available for implementing offline web apps. Some examples include:

• Using a client side JavaScript database such as TaffyDB, although this doesn’t allow data to persist between sessions.
• Dojo Offline storage – View API
• Flash based storage options (used for in-browser storage)
• HTML 5 offline storage options

Related

• Internet-free Web Applications – Less technical perspective on offline web apps on my work blog.
• What’s New With Gears -Interesting YouTube Video (54mins long)

Offline access provides a way for a user to interact with the application when an Internet connection is unavailable, something “traditional” web applications cannot do. Gears also provides a means to improve the performance of apps by storing all the files necessary for them to operate on the user’s computer (meaning no need for downloads of images, script files, css, etc). An example of this is shown below.

Gears achieves this by providing a number of features through its API:

• A “Localserver” capable of serving files stored on the user’s machine, rather than relying on a remote web server;
• A local database (SqlLite) for storing information that can be queried & manipulated locally;
• Access to a “Workerpool” which allows multiple JavaScript processes to run simultaneously – something which allows scripts to run in the background without causing the user interface to slow down;
• Other APIs available include access to HttpRequest (for use in Workerpools using AJAX), the ability to create desktop shortcuts, and a Timer.

For Gears to be used, it must firstly be installed on the user’s machine. To protect users, they must opt-in to allow certain operations to be carried out (for example, installing a desktop shortcut, or creating a local database).

An Example

In an application under development, the user needs access to a set of data that is unique to them. The data changes infrequently, but is needed regularly as either a full set, or is queried based on different conditions. In a “traditional” web application, this means frequent calls to the server which takes time, bandwidth and server processing power.  However, Gears offers an alternative. By maintaining the data on the client side, and updating it as required, the burden is removed from the server. While using the Gears approach in this situation does allow for offline access, one of the main motivations was to increase the responsiveness of the application. So, how does it all work?

First off, you need to check Gears is installed and available:


<script src="gears_init.js"></script> <!-- This need to be included every time -->
<script type="text/javascript">
if (!window.google || !google.gears) {
location.href = "http://gears.google.com/?action=install&message=Please Install Gears ..." +"&return=http://www.example.com/setup/gears/installed/";
}
else{
var db;                // local database
var localServer;    // localServer
}// else

You can see that all the code is in JavaScript – this makes sense because it is all being run by the user’s browser, not a web server. The “gears_init.js” script makes sure Gears is installed (available from Gears documentation site).  If it’s not available, the user will be redirected to an install site, and then sent back to an address you specify (http://www.example.com/setup/gears/installed/). This script also creates a “Factory” object, which is used to create all other objects.

The next step is to create a database to use and add a table to it:
// Datbase Setup
db = google.gears.factory.create('beta.database');
db.open('treatmentDB');
db.execute('create table if not exists treatment ' + '(treatment_id int primary key, treatment_name text, treatment_price decimal, category_id int, timestamp int, toUpdate text)');
db.close();

This creates a database object, and opens the database “treatmentDB” (or creates it if it doesn’t exist). The “execute” command is used to run SQL commands (SqlLite version) against the database – in this case, if there is no table called treatment, create one. I also included two fields to ensure the database is up-to-date – a timestamp, and a toUpdate field (which holds true / false flag depending on whether a record has been added to the local database, but not yet updated in the remote database).

What’s Next?

In the second part of the tutorial, the database will be populated using data on the remote server. I’ll show an example of using a Workerpool to do this, so that the operation doesn’t affect the user interface. The data will then be queried and output.

Update: Part 2 of the Gears tutorial is now available