Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

[Your-OrmModel]

RhoMobile applications provide automatic JavaScript CRUD methods for any models that you have defined to interact with the database. You must define a model class by using the ORM.addModel method before you can use the API’s referenced here. See Orm to learn about defining and adding a model.

All methods here are accessed from the model instance object that you have created. In places where you see [Your-OrmModel] on this page, you would use the instance object instead.

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

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.

Ruby Usage

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

Methods

canModify
()
Deprecated

Returns true if the Rhodes model object is not currently being synced (if it is being synced, you should disable editing of the object). Before displaying an edit page for an object, your application can check if the object is currently being accessed by the sync process. If it is, you should disable editing of the object. can_modify could return true, for example, on a new local record that was created and sent to the RhoConnect application, but no response has been received yet.

Synchronous Return:

  • BOOLEAN

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.canModify()
create
(HASH attributes)

Create a new Rhodes model object and save it to the database. This is the fastest way to insert a single item into the database.

Parameters

  • attributes : HASH

    List of attributes assigned to the new model object, such as {name : “ABC Inc.”,address: “555 5th St.”}.

Synchronous Return:

  • OBJECT

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.create(HASH attributes)
deleteAll
()

Delete all Rhodes model objects for a source.For JavaScript you cannot specify conditions.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.deleteAll()
destroy
()

Destroy a Rhodes model object and removes the record from the database.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.destroy()
find
(STRING queryType, HASH queryOptions)

Find model objects.

Parameters

  • queryType : STRING

    Possible Values :

    all

    returns all objects; can use optional :conditions.

    first

    returns first object matching :conditions.

    count

    returns the number of objects matching these :conditions.

  • queryOptions : HASH

    An object of selection options

    • conditions : HASH

      A name:value object that you want to find. Ex: conditions { name:‘Symbol’}.

      • propertyName :

      • propertyValue :

    • order : STRING Optional

      Attribute(s) to order the list. This cannot be used when using a select parameter and you must pass a conditions hash.

    • orderdir : STRING Optional

      Order direction. This cannot be used when using a select parameter and you must pass a conditions hash

      Possible Values :

      ASC

      Ascending order. (Default)

      DESC

      Descending Order

    • select : ARRAY Optional

      Array of string attributes to return with the object. Useful if your model has many attributes and your query only needs a few of them. This cannot be used in combination with order or orderdir.

Synchronous Return:

  • ARRAY

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.find(STRING queryType, HASH queryOptions)
get
(STRING propertyName)

Get the value of a property of the current model.Ex: myModel.get(‘name’); See also the vars() method.

Parameters

  • propertyName : STRING

    The name of the property you are trying to retrieve.

Synchronous Return:

  • STRING :

    Value of the specified property from the database.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.get(STRING propertyName)
has
(STRING propertyName)

Returns true or false if the model has the propertyName given.

Parameters

  • propertyName : STRING

    The name of the property you are checking for validity. See also the vars() method.

Synchronous Return:

  • BOOLEAN

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.has(STRING propertyName)
make
(HASH attributes)

Create a new Rhodes model object JavaScript reference but does not save it to the database. To save this reference to the database, you will need to execute the .save() method. See the ORM new example.

Parameters

  • attributes : HASH

    List of attributes assigned to the new model object, such as {name:“ABC Inc.”,address:“5555th St.”}.

Synchronous Return:

  • OBJECT

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.make(HASH attributes)
object
()

Returns the unique ID for the data record. Use this to identify records. You can also use this in a .find() method for retrieving a specific record.

Synchronous Return:

  • STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.object()
save
()

Saves the current Rhodes model object to the database.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.save()
set
(STRING propertyName, STRING propertyValue)

Sets the value of a property of the current model. Ex: myModel.set(‘name’,‘new name’); This does not save to the database until you execute a myModel.save().

Parameters

  • propertyName : STRING

    The name of the property you are trying to set.

  • propertyValue : STRING

    The value you are setting in the current model. After setting values you must issue a .save() in order for the data to be saved to the database.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.set(STRING propertyName, STRING propertyValue)
updateAttributes
(HASH attributes)

Updates the current Rho model object attributes and saves it to the database. This is the fastest way to add or update model attributes.

Parameters

  • attributes : HASH

    List of attributes and their updated values, such as {name : “ABC Inc.”,address: “555 5th St.”}.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.updateAttributes(HASH attributes)
vars
()

Returns an object containing all propertyName and values for the model. You can use myModel.vars().name instead of myModel.get(‘name’).

Synchronous Return:

  • HASH

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.vars()

Examples

ORM Make and Create Method Examples

Use method make for creating a new ORM object and assign given attributes. Make does not save to the database until you execute a .save. To insert a new record right away use the create method instead.

var account = Account.make({name: "ABC Inc.", address: "555 5th St."});
account.get("name") // "ABC Inc." 
                            

Use method Create for creating a new ORM object and save to the database.

var account = Account.create({name: "some new record", industry: "electronics"})  
                            
ORM DeleteAll Method Examples

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

Account.deleteAll();
                            
ORM Find Method Examples

Find all objects for specific ORM model

vat accounts = Account.find('all');
                            

Find all objects for specific ORM model with conditions

var accounts = Account.find(
    'all',
    {
      conditions: {industry: 'Technology'}
    }
  ) 
                            

Use select option for retrieves some attributes of object. You must pass “conditions” hash with Javascript implementation.

var accounts = Account.find(
    'all',
    {
      conditions: {name:'address'},
      select: ['name','address']
    }
  );
accounts[0].get("name");  // "A.G. Parr PLC 37862"
accounts[0].get("telephone"); // nil 
                            

Order option is used to sort objects by one or more attributes. You must pass a conditions hash to use ordering.

var accounts = Account.find(
    'all',
    {
      conditions: {"name":"industry"},
      order: 'name',
      orderdir: 'DESC'
    }
  ) 
                            

Order by multiple attributes. You must pass conditions hash.

var accounts = Account.find(
    'all',
    {
      conditions: {"name":"industry"},
      order: ['name', 'industry'],
      orderdir: ['ASC', 'DESC']
    }
  ); 
                            

Order by one attribute with an orderFunction.

var accounts = Account.find(
    'all',
    {
      order: 'name',
      orderFunction: function (a, b) { return a <= b }
    }
  ); 
                            

Order with a block.

var accounts = Account.find(
    'all',
    {
      orderFunction: function (item1, item2) { return item1.name <= item2.name }
    }
); 
                            
ORM Destroy Method Examples

Destroy a Rhodes model object from database.

var account = Account.find('first');
account.destroy();
                            
ORM UpdateAttributes Method Example

Update the current ORM object’s attributes and saves it to the database.

var account = Account.find("first", {conditions: {name: "ABC Inc."});
account.updateAttributes({name: "ABC Inc.", industry: "Technology"});
account.get("industry") // "Technology"
ORM Save Method Example

Saves the current ORM object to the database.

var account = Account.make({name: "some new record", industry: "electronics"});
account.save();