quirkey / jquery-cloudkit Goto Github PK

jquery.cloudkit.js
------------------
An in-browser query-able JSON store for CloudKit.

This jQuery plugin produces in-browser collections of JSON data that map to a
remote CloudKit service. CloudKit is a schema-free auto-versioned RESTful JSON
store with OpenID and OAuth built in.

Using your in-browser database automatically updates the remote store. Querying
is accomplished via JSONQuery. JSONQuery is a superset of JSONPath. See "Usage"
for examples.

See also:

  CloudKit, An Open Web JSON Appliance:
    http://getcloudkit.com

  JSONPath:
    http://goessner.net/articles/JsonPath/

  JSONQuery introduction on the SitePen blog (in the context of Dojo):
    http://www.sitepen.com/blog/2008/07/16/jsonquery-data-querying-beyond-jsonpath/

Usage
-----

On the server:

1) Mount two RESTful resource collections -- one for "notes" and another for
   "things" -- in a file called "config.ru" (a rackup file):

   require 'cloudkit'
   expose :notes, :things

   (This will mount the CloudKit REST API: http://getcloudkit.com/rest-api.html
   for "notes" and "things.")

2) Start the server:

   rackup config.ru

3) In an HTML file, include the library. (Instructions for building the library
   are included below in the "Building" section.):

   <script type="text/javascript" src="jquery.cloudkit.min.js"></script>

4) In your JavaScript code:

var store = $.cloudkit;

store.boot({

  // booting the store reads the metadata on the server, loads existing data,
  // and configures the local store for use

  success: function() {

    // the local store is now ready

    // create a 'thing'
    store.collection('things').create({name:"box"}, {

      success: function(thing) {

        // the 'thing' resource has now been created locally and posted
        // to the server

        alert(thing.json().name); // this will display "box"

        // update the 'thing'
        thing.update({name:"book"} {

          success: function() {

            // the updated 'thing' resource has been mirrored on the server
            // and is ready for use again

            alert(thing.json().name); // this is now "book"

            // delete the 'thing'
            thing.destroy({

              success: function() {
                // the 'thing' has now been deleted
              }
            }
          }
        })
      }
    });

    // create a 'note'
    store.collection('notes').create({foo:"bar"}, {
      success: function(note) {
        // do something with the note
      }
    });

    // find all 'note' resources
    var notes = store.collection('notes').all();

    // get a specific note
    var note = store.collection('notes').get(some_random_note.id());

    // find all things having a name of 'book'
    var matches = store.collection('things').query("?name='book'");
  }
});

Building
--------

To build development and minified versions of the plugin:

  $ rake dist

The jsmin gem is required for building the minified version. To install:

  $ gem install jsmin

Running the Tests
-----------------

The CloudKit gem (0.10.0 or greater) is required for testing. To install:

  $ gem install cloudkit

If you are running an older version of CloudKit, you can upgrade like this:

  $ gem update cloudkit

To test:

  $ rake

Note: You may need to refresh your browser if it launches before rack finishes
starting the test app.

Copyright (c) 2008, 2009 Jon Crosby http://joncrosby.me

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.