Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

ORM

This JavaScript API class allows you to interact with the local RHOM database and programatically add models or get references to models.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

If you are going to be using the JS ORM API, you’ll also need to include these lines in any files that will be using it:

<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-ORM.js"></script>
<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-ORMHelper.js"></script>
<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-Ruby-RunTime.js"></script>

Ruby Usage

For Ruby access to the RHOM database please see the Rhom Ruby API guide.

Methods

addModel( Anoynomous Function methods)

Creates an ORM model reference.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

Anoynomous Function methods :

modelName("value") : STRING

The name of your model.
enable("value") : STRING Optional

Enables Model Properties.

Possible Values :

sync

If set then model is set for RhoConnect Sync.

propertyBag

(Default) Model will be of type propertyBag.

fixedSchema

Model will be of type fixedSchema.
property("name","type") : STRING,STRING Optional

Used to create properties on your model.

name : STRING

The name of the property.
type : STRING

The type of property value: String, Float, integer, Varchar, Blob – String is default.

addIndex("name",[colArray]) : STRING, ARRAY Optional

Add an index to your fixedSchema model.

name : STRING

The name of the index.
colArray : ARRAY

Array of model column names to use in index, Ex: [‘name’,‘qty’]

addUniqueIndex("name",[colArray]) : STRING, ARRAY Optional

Add an index to your fixedSchema model.

name : STRING

The name of the index.
colArray : ARRAY

Array of model column names to use in index, Ex: [‘name’,‘qty’]

belongs_to("name") : STRING Optional

Add belongs_to association to another defined model, for sync models. Comma-separated String for more than one model.
set(property,value) : STRING,VALUE Optional

Set Behavior of this model. Possible property options and corresponding values.

partition : STRING

The partition to use for this model. Partitions can be used to segment the data and keep non-synched data separate from synched models. Possible values.

Possible Values :

local

This partition is used automatically if the model is not a sync model.

user

This partition is used automatically if the model is a sync model.
sync_type : STRING

Sets the type of sync it will be.

Possible Values :

none

If data model is not a sync model.

incremental

Used when the data model is a sync model. Just syncs changes.
sync_priority : INTEGER

Determines how frequently to check for changes. In seconds. Default is 1000.

Synchronous Return:

Model

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.addModel( Anoynomous Function methods)

databaseFullReset(BOOLEAN resetClientInfo, BOOLEAN resetLocalModels)

Deletes all records from the property bag and model tables.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

resetClientInfo : BOOLEAN Optional

True to clean the client_info table, false otherwise.

False on default.
resetLocalModels : BOOLEAN Optional

True to clean local (non-synced) models, false otherwise.

Reset all models.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.databaseFullReset(BOOLEAN resetClientInfo, BOOLEAN resetLocalModels)

databaseFullResetAndLogout()

Deletes all records from the property bag and model tables. Logout the user from RhoConnectClient. For examples, see Resetting the Database in Using the Local Database with ORM.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.databaseFullResetAndLogout()

databaseFullResetEx(HASH propertyMap)

Deletes all records from the property bag and model tables for the model names passed in parameters.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

propertyMap : HASH

Properties map.

models : ARRAY

Array of models names to reset.
reset_client_info : BOOLEAN Optional

If set to true, client_info table will be cleaned.

False on default.
reset_local_models : BOOLEAN Optional Default: false

If set to true, local(non-synced models) will be cleaned.

Reset all models.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.databaseFullResetEx(HASH propertyMap)

databaseFullclientResetAndLogout()

Deletes all records from the property bag and model tables. Logout the user from RhoConnectClient and erase all RhoConnectClient device information. Equivalent to ORM::ORM.databaseFullReset(true) followed by RhoConnectClient.logout.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.databaseFullclientResetAndLogout()

databaseLocalReset()

Reset only local (non-sync-enabled) models.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.databaseLocalReset()

export()

Deprecated

Export db.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

STRING

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.export()

getClientId()

Returns the current sync client id.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

STRING

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.getClientId()

getModel(String modelName)

Returns a model.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

modelName : String

Name of the model you want returned.

Synchronous Return:

Model

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.getModel(String modelName)

haveLocalChanges()

Returns true if any of the Rhodes model objects have local database changes that need to be synchronized, false otherwise.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

BOOLEAN

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.haveLocalChanges()

import(STRING zipName)

Deprecated

Import db.

JavaScript Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

zipName : STRING

The name of the zip file.

Synchronous Return:

BOOLEAN

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.ORM.import(STRING zipName)

Examples

Add ORM model, create ORM object

This example describes creating model and adding model object.

JavaScript

var productModel = Rho.ORM.addModel(function(model){
  model.modelName("Product");
  model.enable("sync");
  model.property("name","string");
  model.property("brand","string");
  model.property("price","float");
  model.set("partition","user");
});

// create model object and save it to database
var product = productModel.create({
  brand: 'Apple',
  name: 'iPhone5',
  price: 199.99});

// read product from database
var product = productModel.find('first');
product.get('brand'); // Apple
product.get('name'); // iPhone5

Get Model by name

Get a model.

JavaScript

// The model 'Product' must have been defined in JavaScript execution earlier 
// in order for 'getModel' to work properly. 

// The models generated in RhoStudio, are not accessible in JavaScript unless 
// the classes are defined via the  Rho.ORM.addModel api


// Get a model by its name after it has been added
var productModel = Rho.ORM.getModel("Product");

ORM databaseFullResetEx Method Examples

Delete all Rhodes model objects for a source, filtering by conditions.

JavaScript

Rho.ORM.databaseFullResetEx({'models' : ['Product', 'Customer'], 'reset_client_info' : true, 'reset_local_models' : true}

Remarks

Performance Findings Using Property Bag Vs Fixed Schema

In our testing, we have found that, overall, the Fixed Schema database model has much better performance that the same tests run using Property Bag, concerning complex data sets. We strongly recommend that enterprise-grade apps use the Fixed Schema model for their app databases as we have seen test results upwards of 10 times faster using the Fixed Schema model. The only current drawback to Fixed Schema is that it is more complex to initially setup. If your dataset is fairly simple in construction, Property Bag should prove sufficient.