PhoneGap-SQLitePlugin-Android/README.md

Phonegap SQLitePlugin
=====================

This is Joe Noon's fork of Phonegap-SQLitePlugin

This fork lives at: https://github.com/joenoon/Phonegap-SQLitePlugin

The original lives at: https://github.com/davibe/Phonegap-SQLitePlugin

This fork has largely diverged from the original, and is not a drop-in
replacement.

DISCLAIMER: 
  
I'm brand new to objective-c, so there could be problems with my code!
Please tell me. joenoon@gmail.com

Added:

-  obj-c:
  -  batch execution support
  -  query parameter binding
  -  perform after delay so js-objc call doesn't need to wait for response
  -  callbacks moved out of instance and into options of each method call
  -  path just takes filename, and path is put in Documents folder
  -  added rowsAffected, insertId
  -  success callback response is { insertId: x, rowsAffected: y, rows: z }
  -  error callback response is { message: x }
  
-  js (coffeescript):
  -  new implementation
  -  first cut transaction support
  -  callbacks per-statement, even within transaction
  -  somewhat similar api to the webkit/phonegap default

Removed:

-  quota limit webkit html5 db patching
-  exit from app
-  (I don't think either of these would make it through the approval process)

Other notes:

I played with the idea of batching responses into larger sets of
writeJavascript on a timer, however there was only a barely noticeable
performance gain.  So I took it out, not worth it.  However there is a
massive performance gain by batching on the client-side to minimize
PhoneGap.exec calls using the transaction support.

Installing
==========

Drag .h and .m files into your project's Plugins folder (in xcode) -- I always
just have "Create references" as the option selected.

Compile the coffeescript file to javascript WITH the top-level function wrapper
option (default).

Use the resulting javascript file in your HTML.

Look for the following to your project's PhoneGap.plist:

    <key>Plugins</key>
    <dict>
      ...
    </dict>

Insert this in there:

    <key>PGSQLitePlugin</key>
    <string>PGSQLitePlugin</string>

General Usage
=============

(You're using Coffeescript right? Of course you are.)

    db = new PGSQLitePlugin("test_native.sqlite3")
    db.executeSql('DROP TABLE IF EXISTS test_table')
    db.executeSql('CREATE TABLE IF NOT EXISTS test_table (id integer primary key, data text, data_num integer)')

    db.transaction (tx) ->
  
      tx.executeSql [ "INSERT INTO test_table (data, data_num) VALUES (?,?)", "test", 100], (res) ->
    
        # success callback
    
        console.log "insertId: #{res.insertId} -- probably 1"
        console.log "rowsAffected: #{res.rowsAffected} -- should be 1"
    
        # check the count (not a part of the transaction)
        db.executeSql "select count(id) as cnt from test_table;", (res) ->
          console.log "rows.length: #{res.rows.length} -- should be 1"
          console.log "rows[0].cnt: #{res.rows[0].cnt} -- should be 1"
  
      , (e) ->
    
        # error callback
    
        console.log "ERROR: #{e.message}"