The first step in order to use Rhom is to create a model class with the required attributes. You can create models from JavaScript using the ORM.addModel method. What this method does is define a class reference for your model so it is available to the rest of your application. When your application pages load, you must execute the Rho.ORM.addModel function for every model that you wish to define in your application.
// Models MUST be defined when your HTML pages load // You can either set a global reference var userModel = Rho.ORM.addModel(function(model) { model.modelName('User'); model.property('name','string'); model.property('email','string'); // optionally enable sync for rhoconnect applications // model.enable('sync'); // optionally, define the model as fixed schema default is propertyBag // model.enable('fixedSchema'); }); // Or just define the model without a global reference Rho.ORM.addModel(function(model) { model.modelName('Product'); model.property('name','string'); model.property('qty','string'); });
Once created, models can be retrieved using the ORM.getModel method.
var productModel = Rho.ORM.getModel('Product');
It is advised that you either use the Ruby or JavaScript methods for handling model definition and access and not do this from both> languages.
Use the create method to create a new model object and save it to the database.
| This is the fastest way to insert a single item into the database. |
var user = userModel.create({ name: 'Alice', email: 'alice@example.com'});
You can also create the new model object without saving it automatically and then explicitly use the save method. This is useful when you want to update some of the object attributes before saving.
var user = userModel.make({name: 'Alice'}); // update the object user.email = 'alice@example.com'; user.save();
You can retrieve all objects for a model or only those matching given conditions using the find method.
var users = userModel.find('all');
var users = userModel.find( 'all', { conditions: {name: 'Alice'} } );
You can retrieve objects sorted by one or more attributes using the order and orderdir parameters.
// order by one attribute var users = userModel.find( 'all', { order: 'name', orderdir: 'DESC', conditions: {...} // JavaScript API requires conditions } ); // order by multiple attributes var users = userModel.find( 'all', { order: ['name', 'email'], orderdir: ['ASC', 'DESC'], conditions: {...} // JavaScript API requires conditions } );
You can also sort with an user defined function.
// order by one attribute var users = userModel.find( 'all', { orderFunction: function(a, b) { return a <= b } } ); // order by multiple attributes var users = userModel.find( 'all', { orderFunction: function(a, b) { return a.name <= b.name && a.email <= b.email } } );
Whenever possible, use
order instead of orderFunction. The database will sort objects faster than JavaScript code.
If, for a particular action, you do not need every attribute in an object, you can make your application faster by selecting only the specific attributes you need using the select parameter.
JavaScript syntax: :::javascript var users = userModel.find( ‘all’, { select: [‘name’], conditions: {…} // JavaScript API requires conditions } );
You can get only the first object matching given conditions using first instead of all when calling find.
var user = userModel.find( 'first', { conditions: {name: 'Alice'} } );
You can get the number of objects matching given conditions using the count parameter with find method.
JavaScript syntax: :::javascript var count = userModel.find( ‘count’, { conditions: {name: ‘Alice’} } );
You can update an object’s attributes and save it to the database using the updateAttributes method
| This is the fastest way to add or update item attributes. |
JavaScript syntax: :::javascript var user = userModel.find(‘first’, {conditions: {name: ‘Alice’}); user.updateAttributes({ name: ‘Bob’, email: ‘bob@example.com’});
To delete one model object use the destroy method on the object to be deleted.
JavaScript syntax: :::javascript var user = userModel.find(‘first’); user.destroy();
To delete all objects for a model, or only those matching given conditions, use the deleteAll method.
JavaScript syntax: :::javascript // delete all objects userModel.deleteAll();
// delete only objects matching :conditions
userModel.deleteAll({conditions: {name: 'Alice'}})
Use transactions to group together database operations that must either succeed or fail as a group, without leaving any partially completed operations. You can combine any set of object/model operations like insert/update/delete under a transaction.
// open 'app' partition var db = new Rho.Database(Rho.Application.databaseFilePath('app'),'app'); db.startTransaction(); try { // do multiple operations db.executeSql("update User set name=?, email=? where object=?",["Alice","alice@example.com","12345"]); db.executeSql("update User set name=?, email=? where object=?",["Bob","bob@example.com","67890"]); // no errors, so commit all the changes db.commitTransaction(); } catch { // on error rollback all changes db.rollbackTransaction(); } finally // always close every database connection you open { db.close(); }
You can execute SQL statements directly on the database by using Database.executeSql method.
JavaScript syntax: :::javascript try {
var db = new Rho.Database(Rho.Application.databaseFilePath('app'),'app');
var result = db.executeSql('SELECT * FROM User'); // result is an array of hashes, where each hash is a record
} finally {
db.close();
}
You can execute a series of SQL statements in a single method call by using Database.executeBatchSql method.
db.executeBatchSql("UPDATE User set valid=0; Update Account set active=0");
You can use the following method for recovering the database from a bad or corrupt state or if the RhoConnect server returns errors.
JavaScript syntax: :::javascript Rho.ORM.databaseFullResetEx({‘models’: [‘User’], ‘reset_client_info’: true, ‘reset_local_models’: true});