Skip to content
This repository
Newer
Older
100644 144 lines (112 sloc) 5.255 kb
cd6c915d »
2010-02-03 Simple prefetching works.
1 persistence.js
2 ==============
14f8aacb »
2010-02-05 Working on the readme
3 `persistence.js` is a simple asynchronous Javascript object-relational
4 mapper library. It works with the in-browser HTML5 SQLite database as
5 well as Google Gears' database. It has no dependencies on any other
6 frameworks, other than the Google Gears
7 [initialization script](http://code.google.com/apis/gears/gears_init.js),
8 in case you want to enable Gears support.
cd6c915d »
2010-02-03 Simple prefetching works.
9
14f8aacb »
2010-02-05 Working on the readme
10 Browser support
11 ---------------
12
13 * Modern webkit browsers (Google Chrome and Safari)
14 * Firefox (through Google Gears)
cd6c915d »
2010-02-03 Simple prefetching works.
15
14f8aacb »
2010-02-05 Working on the readme
16 Internet Explorer is likely not supported (untested) because it
17 lacks `__defineGetter__` and `__defineSetter__` support that
18 `persistence.js` uses heavily). This may change in IE 8.
19
20 Connecting to the database
21 -------------------------
22
23 Currently there is one global database connection, which is
24 initialized with a `persistence.connect` call. Its first argument is
25 the database name, the second a database description and third the
26 maximum database size (in bytes):
cd6c915d »
2010-02-03 Simple prefetching works.
27
28 persistence.connect('testdb', 'My test db', 5 * 1024 * 1024);
14f8aacb »
2010-02-05 Working on the readme
29
30 Schema definition
31 -----------------
32
33 A data model is declared using `persistence.define`. The following two
34 definitions define a `Task` and `Category` entity with a few simple
35 properties. The property types are [SQLite types](http://www.sqlite.org/datatype3.html).
cd6c915d »
2010-02-03 Simple prefetching works.
36
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
37 var Task = persistence.define('Task', {
cd6c915d »
2010-02-03 Simple prefetching works.
38 name: "TEXT",
39 description: "TEXT",
40 done: "BOOL"
41 });
42
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
43 var Category = persistence.define('Category', {
cd6c915d »
2010-02-03 Simple prefetching works.
44 name: "TEXT"
45 });
46
14f8aacb »
2010-02-05 Working on the readme
47 The returned values are constructor functions and can be used to
48 create new instances of these entities later:
cd6c915d »
2010-02-03 Simple prefetching works.
49
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
50 var task = new Task();
51 var category = new Category({name: "My category"});
cd6c915d »
2010-02-03 Simple prefetching works.
52
14f8aacb »
2010-02-05 Working on the readme
53 Relationships between entities are defined using the constructor
54 function's `hasMany` call:
cd6c915d »
2010-02-03 Simple prefetching works.
55
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
56 Category.hasMany('tasks', Task, 'category');
cd6c915d »
2010-02-03 Simple prefetching works.
57
14f8aacb »
2010-02-05 Working on the readme
58 This defines a `tasks` relationship on category objects containing a
59 `QueryCollection` (see the section on query collections later) of
60 `Task`s, it also defines an inverse relationship on `Task` objects
61 with the name `category`.
cd6c915d »
2010-02-03 Simple prefetching works.
62
14f8aacb »
2010-02-05 Working on the readme
63 The defined entity definitions are synchronized (activated) with the
64 database using a `persistence.schemaSync` call, which takes a callback
65 function (with the used transaction as an argument), that is called
66 when the schema synchronization has completed, the callback is
67 optional.
cd6c915d »
2010-02-03 Simple prefetching works.
68
69 persistence.schemaSync();
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
70 // or
14f8aacb »
2010-02-05 Working on the readme
71 persistence.schemaSync(function(tx) {
72 // tx is the transaction object of the transaction that was
73 // automatically started
74 });
cd6c915d »
2010-02-03 Simple prefetching works.
75
76 Persisting objects
77 ------------------
78
14f8aacb »
2010-02-05 Working on the readme
79 Similar to [hibernate](http://www.hibernate.org), `persistence.js`
80 uses a tracking mechanism to determine which objects' changes have to
81 be persisted to the datase. All objects retrieved from the database
82 are automatically tracked for changes. New entities can be tracked to
83 be persisted by using the `persistence.add` function:
cd6c915d »
2010-02-03 Simple prefetching works.
84
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
85 var c = new Category({name: "Main category"});
cd6c915d »
2010-02-03 Simple prefetching works.
86 persistence.add(c);
87 for ( var i = 0; i < 5; i++) {
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
88 var t = new Task();
cd6c915d »
2010-02-03 Simple prefetching works.
89 t.name = 'Task ' + i;
90 t.done = i % 2 == 0;
91 t.category = c;
92 persistence.add(t);
93 }
94
14f8aacb »
2010-02-05 Working on the readme
95 All changes made to tracked objects can be flushed to the database by
96 using `persistence.flush`, which takes a transaction object and callback function as
97 arguments. A new transaction can be started using
cd6c915d »
2010-02-03 Simple prefetching works.
98 `persistence.transaction`:
99
100 persistence.transaction(function(tx) {
14f8aacb »
2010-02-05 Working on the readme
101 persistence.flush(tx, function() {
102 alert('Done flushing!');
103 });
cd6c915d »
2010-02-03 Simple prefetching works.
104 });
14f8aacb »
2010-02-05 Working on the readme
105
106 For convenience, it is also possible to not specify a transaction or callback, in that
107 case a new transaction will be started automatically. For instance:
108
109 persistence.flush();
110 // or, with callback
111 persistence.flush(null, function() {
112 alert('Done flushing');
113 });
114
115 Note that when no callback is defined, the flushing still happens asynchronously.
116
117 Query collections
118 -----------------
119
120 A core concept of `persistence.js` is `QueryCollection`. A
121 `QueryCollection` represents a (sometimes) virtual collection that can
122 be filtered, ordered or paginated. `QueryCollection`s are somewhate inspired
123 by [Google AppEngine's Query class](http://code.google.com/appengine/docs/python/datastore/queryclass.html).
124 A `QueryCollection` has the following methods:
125
126 * `filter(property, operator, value)` returns a new `QueryCollection`
127 that adds a filter, filtering a certain property based on an operator and value. Supported operators
128 are '=', '!=', '<', '<=', '>' and '>='. Example: `.filter('done', '=', true)`
129 * `order(property, ascending)` returns a new `QueryCollection` that will order its results by the property
130 specified in either an ascending (ascending === true) or descending (ascending === false) order.
131 * `list(tx, callback)` fetches the actual result set.
132
cd6c915d »
2010-02-03 Simple prefetching works.
133
73724ff7 »
2010-02-03 Added .add and .remove methods to QueryCollections.
134 var allTasks = Task.all().filter("done", '=', true).prefetch("category").order("name", false);
cd6c915d »
2010-02-03 Simple prefetching works.
135
136 persistence.transaction(function(tx) {
137 allTasks.list(tx, function (results) {
138 results.forEach(function (r) {
139 console.log(r.name)
140 window.task = r;
141 });
142 });
143 });
Something went wrong with that request. Please try again.