Download Impel

Version 0.7

Read the API

It’s simple

Download Impel Modules

Transparent Database Syncing

Read the FAQ

Yes, it runs on the iPhone

Class Impel.inTouch

Keep a local HTML5 SQL database in sync with one published by your server.

Impel.inTouch is used by the forthcoming HTML5 Javascript ORM, Impel, but you can use it separately without any trouble

Using Impel.inTouch

Impel.inTouch makes it simple to keep your client's HTML5 databases up-to-date. The first time it is used on a client's computer it will connect to your server, download the latest schema and data then import it into the local HTML5 database. Every other time the client connects to your site, or loads a cached version of it, Impel.inTouch will quickly verify that it has the latest schema and data then pass off to the rest of your web application. All you need to do to update the HTML5 databases on your client's machines is update the schema published by your server. All your client's will download the new data the very next time they fire up your web application.

It's all completely transparent to your clients and painless for you.

You do need to do a little bit of preparation though.

  • Setup a versions file on the server
  • Setup a table definition file for each table that should be imported/updated by the client
  • Include Impel.inTouch in an html file and instantiate it

Tables can be updated in one of two ways:

  1. Single Update: no matter what the current version of the table is it will be updated to the absolute latest version.
  2. Incremental Update: the table will be updated to the next most recent version then the next most recent, and so on until it is at the latest version.

Setup a versions file

The versions file contains a JSON encoded array of objects that define the tables and their versions. The array has to be enclosed in a function call to Impel.JsonP.callback. The callback name (Impel.JsonP.callback) will also be specified as part of the query string. By default the versions file is named versions.json.php, but you can change that when you instantiate an Impel.inTouch object.

If you want the table to be updated in a single request then its entry in the versions file must consist of a table key and a version key. The version key's value should simply be the most recent version number.

If you want the table to be updated incrementally then its entry in the versions file must consist of a table key and a versions key. The versions key's value should be an array of ALL the versions of the table.

versions.json.php

Impel.JsonP.callback([{ "table" : "card",         "version" : 1}, 
                         { "table" : "stack",        "version" : 1}, 
                         { "table" : "similar_card", "version" : 1}, 
                         { "table" : "card_score",   "version" : 1},
                         { "table" : "player",     "versions" : [1,2,3,4,5,6,7]},
                         ]);

Setup table definition file(s)

Every table that you want to have created/updated on your client's browser must have an associated definition file. The file must have the same name as the table in the versions file. By default the suffix for the table file should be .json.php, but you can specify a different suffix when you instantiate an Impel.inTouch object.

Important note If a table is to be updated incrementally rather than in a single update the name of the table and the suffix must be seperated by "_[table_version]" for each version of the table. So in the example above, where the player table has seven versions, we would need seven files: palyer_1.json.php, palyer_2.json.php, player_3.json.php, etc.,.

Each table definition file must contain a JSON encoded object as an argument to a call to Impel.JsonP.callback. The callback name (Impel.JsonP.callback) will also be specified as part of the request's query string. The object may include six key/value pairs; four of which (create, data, pre-create, and extra) are optional. The rest, (version, and table) are required, but for your update to have any effect you will need to define either create, or data

  • {String} table The name of the table
  • {Int} version The version of table and its data
  • {String[]} [pre-create] An array of SQL statements to execute before going on to the create string
  • {String} [create] An SQL statement used to create the table
  • {String[]} [extra] An array of SQL statements used to modify the table after it has been created, but before data has been loaded
  • {String[]} [data] Array of INSERT, UPDATE, or DELETE statements used to fill the table
card.json.php:

Impel.JsonP.callback({
  "version" : 1,
  "table": "card",
  "pre-create" : ["DROP TABLE IF EXISTS `card`"],
  "create": "CREATE TABLE IF NOT EXISTS `card` (`id` INTEGER PRIMARY KEY, `kanji` varchar(255) default NULL, `hatsuon` varchar(255) default NULL, `meaning` varchar(255) default NULL, `level` int(11) default NULL, `created_at` datetime default NULL, `updated_at` datetime default NULL);",
  
  "extra" : ["CREATE INDEX IF NOT EXISTS card_I_1 ON card(kanji);", 
             "CREATE INDEX IF NOT EXISTS card_I_2 ON card(hatsuon);"],
  
  "data" : ["INSERT INTO `card` VALUES(119, '席', 'せき', 'seat; ones place; meeting place; hall; meeting', 2, '2009-02-28 06:44:13', '2009-03-02 01:28:51');",
            "INSERT INTO `card` VALUES(120, '印', 'いん,じるし', 'mark; imprint; sign; seal; stamp', 2, '2009-02-28 06:44:14', '2009-02-28 06:44:14');"]
  }); 
player_6.json.php:

Impel.JsonP.callback({
  "version" : 6,
  "table": "player",
  "data" : ["INSERT INTO `player` VALUES(760, 'Bugssy Two-Tone', '2009-01-21 16:47:13');",
            "INSERT INTO `player` VALUES(761, 'Bill Brass-Knuckles Malone', '2009-01-22 13:22:56');"]
  }); 
player_7.json.php:

Impel.JsonP.callback({
  "version" : 7,
  "table": "player",
  "data" : ["INSERT INTO `player` VALUES(762, 'Johnny Good', '2009-02-28 06:44:13');",
            "INSERT INTO `player` VALUES(763, 'Tommy Big', '2009-02-28 11:24:06');"]
  }); 

Include and Instantiate Impel.inTouch

Impel requires Mootools 1.2+. Other than that all you need to do is include the Impel.inTouch library in a script tag, and instantiate an Impel.inTouch object with the baseURL option. The baseURL can be remote or a relative directory, so http://my.server.co.jp/inTouch/ will work as will inTouch/.

Instantiation is a two step process. First the object must determine which versions of the tables are currently setup on the client. Once that is done it will fire a 'ready' event. At that point all you have to do is call sync(). Once synchronization is finished it will fire a 'synced' event. Various events will be fired during the synchronization process to give you a better idea of what is going on and what errors (if any) occurred. Consult the API documentation for a full list.


   

Class Summary
Constructor Attributes Constructor Name and Description
 
Impel.inTouch(options, events)
Keep a local HTML5 SQL database in sync with one published by your server.
Field Summary
Field Attributes Field Name and Description
<static>  
Impel.inTouch.options.baseURL
The url where Impel.inTouch can find the versions and table definition files.
<static>  
Impel.inTouch.options.displayName
A human-friendly name for the database
<static>  
Impel.inTouch.options.maxSize
The maximum size that this database can grow to
<static>  
Impel.inTouch.options.name
The name of the local database to use
<static>  
Impel.inTouch.options.tableFileSuffix
The suffix of the files on the server that include the import/update data
<static>  
Impel.inTouch.options.versionsFile
The name of the file on the server that details the currently published tables and their versions
Method Summary
Method Attributes Method Name and Description
 
checkForUpdates(table_versions)
Check the server to see if the tables have been updated recently and call synchronize for any that have been updated.
 
getVersion(table)
Determine which version a particular local table is currently at.
 
importData(data)
Import a new version of a table into the local database.
 
loadVersions(s_callback)
Check the local database to determine the current versions of all local tables.
 
setVersion(table, version)
Record that a particular table is at a particular version, and persist the record into the database.
 
sync(list)
Synchronize the local tables with those published by the server.
Event Summary
Event Attributes Event Name and Description
 
onAborted(code)
The sync was aborted due to a network error
    Codes
  • 1 : The versions file could not be retrieved.
 
onCreated(table)
The portion of the update meant to create the local table succeeded
 
onCreateFailed(table, error)
The portion of the update meant to create the local table failed
 
The Impel.inTouch object has been initialized, you can now call sync or any other method.
 
The local database has been fully synchronized with the server
 
onSyncFailed(failed)
One or more of the local tables was not synchronized with the server
 
Synchronization has begun
 
onUpdated(table, old, now)
A particular table has been updated
 
onUpdateFailed(table, now, future)
A particular table was not updated
 
onUpdating(table)
A particular table is now being updated
Class Detail
Impel.inTouch(options, events)
Parameters:
{Object} options
  • {String} baseURL=null Required The url where Impel.inTouch can find the versions and table definition files. It does not have to be on the same server that provides the rest of your JavaScript.
  • {String} [versionsFile=versions.json.php] The name of the file on the server that details the currently published tables and their versions
  • {String} [tableFileSuffix=.json.php] The suffix of the files on the server that include the import/update data
  • {String} [name=Impel_inTouch] The name of the local database to use
  • {String} [displayName=Impel inTouch] A human-friendly name for the database
  • {Number} [maxSize=4096] The maximum size that this database can grow to
{Object} events
See:
http://mootools.net/
Field Detail
<static> {String} Impel.inTouch.options.baseURL
The url where Impel.inTouch can find the versions and table definition files. It does not have to be on the same server that provides the rest of your JavaScript

<static> {String} Impel.inTouch.options.displayName
A human-friendly name for the database
Default Value:
Impel inTouch

<static> {Number} Impel.inTouch.options.maxSize
The maximum size that this database can grow to
Default Value:
4096

<static> {String} Impel.inTouch.options.name
The name of the local database to use
Default Value:
Impel_inTouch

<static> {String} Impel.inTouch.options.tableFileSuffix
The suffix of the files on the server that include the import/update data
Default Value:
.json.php

<static> {String} Impel.inTouch.options.versionsFile
The name of the file on the server that details the currently published tables and their versions
Default Value:
versions.json.php
Method Detail
checkForUpdates(table_versions)
Check the server to see if the tables have been updated recently and call synchronize for any that have been updated.

If this method is called with no arguments it asynchronously retrieves a list of the tables and their current versions. When the list comes back this method is called again with that list as an argument. It then goes through the list checking for tables that have a version number greater than their local counterparts. Synchronize is then called for any tables that need to be updated.

 [
   { "table" : "card", "version": 3 }, 
   { "table" : "player", "versions" : [1,2,3,4,5,6] }
 ]
Parameters:
{Object[]} table_versions Optional
- A list of objects describing the current version, or all versions, of each published table

{Number} getVersion(table)
Determine which version a particular local table is currently at. The server will NOT be queried.

Important Note: This method should not be called before the 'ready' event has been fired.

Parameters:
{String} table
The name of the table to check
Returns:
{Number} The current version number for the specified table

importData(data)
Import a new version of a table into the local database.

If any portion of the import fails the entire transaction is rolled back.

Parameters:
{Object} data
- An Object containing the following keys:
  • {String} table The name of the table
  • {Int} version The version of table and its data
  • {String[]} [pre-create] An array of SQL statements to execute before going on to the create string
  • {String} [create] An SQL statement used to create the table
  • {String[]} [extra] An array of SQL statements used to modify the table after it has been created, but before data has been loaded
  • {String[]} [data] Array of INSERT, UPDATE, or DELETE statements used to fill the table

  • loadVersions(s_callback)
    Check the local database to determine the current versions of all local tables. The version information will be stored in memory to serve future requests to getVersion
    Parameters:
    {function} s_callback
    A function to call when the load is complete
    See:
    Impel.inTouch#getVersion
    Impel.inTouch#setVersion

    setVersion(table, version)
    Record that a particular table is at a particular version, and persist the record into the database.

    Important Note: This method should not be called before the 'ready' event has been fired.

    Parameters:
    {String} table
    The name of the table
    {Int} version
    The, now, current version for the table

    sync(list)
    Synchronize the local tables with those published by the server.

    If this method is called with no arguments it calls checkForUpdates, which will in turn call this method with a list of tables that need to be synchronized. Synchronize then asynchronously retrieves the update data from the server, which will be inserted into the local database via importData

    Tables can be updated in one of two ways:

    1. Single Update: no matter what the current version of the table is it will be updated to the absolute latest version.
    2. Incremental Update: the table will be updated to the next most recent version then the next most recent, and so on until it is at the latest version.

    If you want a table to be updated in a single request then setup your versions file with a "version" : latest_version_number attribute for the table. Then define the latest table version in a single file named [table_name].json.php (the suffix is configurable).

    If you want the table to be updated incrementally remove the "version" key from the tables entry in the versions file and replace it with a "versions" : array_of_all_versions attribute for the table. Then define a table definition file for each version. The files must be named: [table_name]_[version_number].json.php (the suffix is configurable).

    Once all tables have been updated the synced or syncFailed event will be fired.

    Important Note: This method should not be called before the 'ready' event has been fired.

    Parameters:
    {String|Object[]} list Optional
    - A list of tables that need to be updated. If null then it will check the server's published versions file. A table can be either a String, or an object that contains the following key/value pairs:
    • {String} table The name of the table to update in a single request
    • {Array} versions An ordered list of all the versions between the table's current version + 1 and the most recent version.
    Event Detail
    onAborted(code)
    The sync was aborted due to a network error
      Codes
    • 1 : The versions file could not be retrieved.
    Parameters:
    {Number} code

    onCreated(table)
    The portion of the update meant to create the local table succeeded
    Parameters:
    {String} table

    onCreateFailed(table, error)
    The portion of the update meant to create the local table failed
    Parameters:
    {String} table
    {String} error
    The error message

    onReady()
    The Impel.inTouch object has been initialized, you can now call sync or any other method.

    onSynced()
    The local database has been fully synchronized with the server

    onSyncFailed(failed)
    One or more of the local tables was not synchronized with the server
    Parameters:
    {String[]} failed
    The tables that were not synchronized successfully

    onSyncing()
    Synchronization has begun

    onUpdated(table, old, now)
    A particular table has been updated
    Parameters:
    {String} table
    {Number} old
    The table was at old version
    {Number} now
    The table is now at now version

    onUpdateFailed(table, now, future)
    A particular table was not updated
    Parameters:
    {String} table
    {Number} now
    The table remains at now version
    {Number} future
    The table was not updated to future version

    onUpdating(table)
    A particular table is now being updated
    Parameters:
    {String} table

    blog comments powered by Disqus

    Impel takes the pain out of working with HTML5 asynchronous databases.

    Statement callbacks? Transaction callbacks? One-to-many and many-to-many relationships? How the heck do I deal with all without my head exploding?

    Use Impel; create an object then call object.save(); Now get a cup of coffee.

    What’s an ORM

    Object Relational Mapping is a programming technique that turns your database, in effect, into a virtual object database.

    With an ORM you no longer need to worry about how to save a single object across multiple tables, you just call, "save" on the object.

     
    Contact Us | © 2009 Caleb Crane | License