joli.js is a simple ORM for Appcelerator Titanium mobile projects. It was built borrowing large parts of the code of JazzRecord, a more general and complex javascript ORM. Praise and kudos to them!
"joli" means in French "nice", "tiny". Just what joli.js tries to be.
Just grab joli.js (a single file), and include it in your Titanium project using
Titanium.include('joli.js');
The sources are available on GitHub.
There is one single required step in the configuration of joli.js: configuring the database name. This can be done in only one line, which has to be put before every call to joli.js's API:
joli.connection = new joli.Connection('your_database_name');
Prior inserting data and querying your models, you must declare these models. This is done by instantiating the class "joli.model":
var city = new joli.model({
table: 'city',
columns: {
id: 'INTEGER',
name: 'TEXT',
description: 'TEXT'
}
});
If your application uses a lot of models, I advice to bind all of these in a models variable, which will contain every models:
var models = (function() {
var m = {};
m.human = new joli.model({
table: 'human',
columns: {
id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
city_id: 'INTEGER',
first_name: 'TEXT',
last_name: 'TEXT'
},
methods: {
countIn: function(cityName) {
// search for the city id
var city = joli.models.get('city').findOneBy('name', cityName);
if (!city) {
throw 'Could not find a city with the name ' + cityName + '!';
} else {
return this.count({
where: {
'city_id = ?': city.id
}
});
}
}
},
objectMethods: {
move: function(newCityName) {
// search for the city id
var city = joli.models.get('city').findOneBy('name', newCityName);
if (!city) {
throw 'Could not find a city with the name ' + newCityName + '!';
} else {
this.set('city_id', city.id);
}
}
}
});
m.city = new joli.model({
table: 'city',
columns: {
id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
country_id: 'INTEGER',
name: 'TEXT',
description: 'TEXT'
}
});
m.country = new joli.model({
table: 'country',
columns: {
id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
name: 'TEXT'
}
});
return m;
})();
The parameters array, which allows to configure a model, may contain several keys:
table: the table name,columns: the name of the various columns proposed by the model. For each of them, it is required to specify their type (INTEGER,TEXTorFLOAT),methods: a table of class-level methods, in order to extend the model (see thecountInmethod upper). Note: these methods will be added to the model definition, not its instances,objectMethods: a table of object-level methods, which allow to extend the model instances (see themovemethod upper).
This section describes the way on how to use joli.js.
At the first launch of an application on a device, it is required to create the tables associated with the models, with the required fields. Of course, joli.js helps initialising the database: simple call the joli.models.initialize() method once the models have been defined:
var city = new joli.model({
table: 'city',
columns: {
id: 'INTEGER',
name: 'TEXT',
description: 'TEXT'
}
});
joli.models.initialize();
Would you like the "id" to get auto-incremented, just add the informations "PRIMARY KEY AUTOINCREMENT" to the column definition :
var city = new joli.model({
table: 'city',
columns: {
id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
name: 'TEXT',
description: 'TEXT'
}
});
Inserting data can be done using the newRecord() method of a model:
// create the record (not persisted)
var john = models.human.newRecord({
first_name: 'John',
last_name: 'Doe'
});
// move him to New York
john.move('New York');
// persist it
john.save();
You may also want to create a record using the instance class directly:
var john = new joli.record(models.human);
john.fromArray({
first_name: 'John',
last_name: 'Doe'
});
// move him to New York
john.move('New York');
// persist it
john.save();
The first method is however advised, as it performs some checks on the existence of the columns.
Retrieving data is often a pain. For all the models, joli.js implements some magic finders in the model classes:
findBy(field, value)allows to retrieve a list of the records having a specific value for one of its fieldsfindById(id)allows to retrieve a list of the records having a specific idfindOneBy(field, value)allows to retrieve one record having a specific value for one of its fields. If several records match the criteria, then only the first one will be returnedfindOneById(id)allows to retrieve one record having a specific id
But of course, you will want to perform more complex searches. This is where the query API enters in the dance. This query API allows to create joli.query objects, which are turned into real SQL queries by the ORM when executing the query.
This is particularly powerful when you want to add restrictions to the query in conditional statements:
var q = new joli.query()
.select('human.*')
.from('human')
.order(['last_name desc', 'first_name asc']);
if (win.city_id) {
q.where('city_id = ?', win.city_id);
}
if (win.last_name) {
q.where('last_name LIKE ?', '%' + win.last_name + '%');
}
if (win.city_name) {
q.where('city.name = ?', win.city_name);
q.join('city', 'city.id', 'human.city_id');
}
var humans = q.execute();
The Query API supports lots of things. Just have a check at the joli.query class!
In some cases however, you will find this way of querying your models just too long, and you will prefer an other alternative syntax (Criteria-style querying API):
var humans = models.human.all({
where: {
'city_id = ?': win.city_id
},
order: ['last_name desc', 'first_name asc']
});
When querying models in this fashion, using all() or the findBy methods, the resulting object is returned as a joli.record object, meaning the following syntax is totally cool:
var rows = models.human.findBy('first_name', 'John');
for(var j=rows.length, i=0; i<j; i++) {
var thisPerson = rows[i];
thisPerson.last_name = 'SuperDoe';
thisPerson.save();
}
This will change all Johns to have the last name SuperDoe.
joli.js is made of several classes:
joli, which is a convenience class for storing utilities,joli.Connection, which handles the real connection to the database,joli.model, which allows to perform some operations on a model,joli.Models, which acts as a hashmap of the models, and allows to initialise the database,joli.query, allows to write queries in a OOP style,- and, finally,
joli.recordrepresents a record and contains useful methods.
You may want to override some of these classes for your convenience (for instance, for implementing an automatic synchronisation with a REST web service)... Just feel free to contribute back your changes!
This section gives some clues about how to use joli.js. It will be updated when questions will be sent to me about joli.js.
Would you have a specific part of your code where your models can not be accessed using the models object, it is still possible to access it using the method joli.models.get(). In other words:
models.human == joli.models.get('human');
joli.js has been developed by Xavier Lacot and is licensed under the MIT license.
Please use GitHub in order to report bugs, but you may also ask for help on how to use joli.js by sending me a mail directly. My email address is [email protected].
- added object-level methods, and fixed the documentation accordingly
Initial public release. Features a simple ActiveRecord implementation, along with an OOP query API.