---

• CritConstants
• Criteria
• Impel
• Impel.CritConstants
• Impel.Criteria
• Impel.Criterion
• Impel.inTouch
• Impel.ResultSet
• ImpelClass
• ImpelPeer
• ResultSet
• String

---

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
	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
	onSyncing() 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

---

Default Value:

Impel inTouch

---

Default Value:

4096

---

Default Value:

Impel_inTouch

---

Default Value:

.json.php

---

Default Value:

versions.json.php

 [
   { "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

---

Parameters:

{String} table

The name of the table to check

Returns:

{Number} The current version number for the specified table

---

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

---

Parameters:

{function} s_callback

A function to call when the load is complete

See:

Impel.inTouch#getVersion

Impel.inTouch#setVersion

---

Parameters:

{String} table

The name of the table

{Int} version

The, now, current version for the table

---

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.

Parameters:

{Number} code

---

Parameters:

{String} table

---

Parameters:

{String} table

{String} error

The error message

---

---

---

Parameters:

{String[]} failed

The tables that were not synchronized successfully

---

---

Parameters:

{String} table

{Number} old

The table was at old version

{Number} now

The table is now at now version

---

Parameters:

{String} table

{Number} now

The table remains at now version

{Number} future

The table was not updated to future version

---

Parameters:

{String} table

---