Base class for all models.

This is used through patio.addModel, NOT directly.

Extends Static Properties
PropertyTypeDefault ValueDescription
MANY_TO_MANYproperty"manyToMany"

String for to signify an association as many to many.

MANY_TO_ONEproperty"manyToOne"

String for to signify an association as many to one.

ONE_TO_MANYproperty"oneToMany"

String for to signify an association as one to many.

ONE_TO_ONEproperty"oneToOne"

String for to signify an association as one to one.

camelize{Boolean} false

Set to true if this models column names should be use the "underscore" method when sending keys to the database and to "camelize" method on columns returned from the database. If set to false see patio.Model#underscore.

columnsString[]

A list of columns this models table contains.

datasetpatio.Dataset

A dataset to use to retrieve instances of this {@link patio.Model{ from the database. The dataset has the {@link patio.Dataset#rowCb} set to create instances of this model.

dbpatio.Database

The database all instances of this patio.Model use.

emitOnAssociationAddpropertytrue

Set to false to prevent an event from being emitted when an association is added to the model

emitOnColumnSetpropertytrue

Set to false to prevent the emitting of an event on the setting of a column value

emitOnLoadpropertytrue

Set to false to prevent the emitting of an event on load

emitOnRemovepropertytrue

Set to false to prevent the emitting on an event when a model is removed.

emitOnSavepropertytrue

Set to false to prevent the emitting on an event when a model is saved.

emitOnUpdatepropertytrue

Set to false to prevent the emitting on an event when a model is updated.

fetchTypepropertyfetch
identifierInputMethodpropertynull

See patio.Dataset#identifierInputMethod

identifierOutputMethodpropertynull

See patio.Dataset#identifierOutputMethod

isRestrictedPrimaryKeypropertyfalse

Set to false to allow the setting of primary keys.

patiofunction

A reference to the global patio.

primaryKeyfunction

The primaryKey column/s of this patio.Model

raiseOnTypecastErrorpropertytrue

Set to false to prevent errors thrown while type casting a value from being propogated.

reloadOnSavepropertytrue

Set to false to prevent the reload of a model after saving.

reloadOnUpdatepropertytrue

Set to false to prevent the reload of a model after updating.

restrictedColumnspropertynull

Columns that should be restriced when setting values through the patio.Model#set method.

schemaObject

The schema of this patio.Model's table. See patio.Database#schema for details on the schema object.

tablepropertynull

The table that this Model represents. READ ONLY

tableNameString

The name of the table all instances of the this patio.Model use.

typecastEmptyStringToNullpropertytrue

Set to false to prevent empty strings from being type casted to null

typecastOnAssignmentpropertytrue

Set to false to prevent properties from being type casted when manually set. See patio.Database#typecastValue

typecastOnLoadpropertytrue

Set to false to prevent properties from being type casted when loaded from the database. See patio.Database#typecastValue

underscore{Boolean} false

Set to true if this models column names should be use the "camelize" method when sending keys to the database and to "underscore" method on columns returned from the database. If set to false see patio.Model#underscore.

useTransactionspropertytrue

Set to false to prevent models from using transactions when saving, deleting, or updating. This applies to the model associations also.

Instance Properties
PropertyTypeDefault ValueDescription
__isChangedpropertyfalse

Signifies if the model has changed

__isNewpropertytrue

Whether or not this model is new

associationsfunction

List of associations on the patio.Model

columnsString[]

a list of columns this models table contains.

datasetpatio.Dataset

a dataset to use to retrieve models from the database. The dataset has the patio.Dataset#rowCb set to create instances of this model.

hasAssociationsfunction

Returns true if this patio.Model has associations.

isChangedBoolean

true if the model has been changed and not saved.

isNewBoolean

true if this model is new and does not exist in the database.

patiopationull

patio - read only

primaryKeyValue*

the value of this models primaryKey

schemaObject

the schema of this models table.

tableNameString

the table name of this models table.

typeStringnull

The database type such as mysql

Constructor

Defined model.js Source
function (options,fromDb){
   if (this.synced) {
       this.__emitter = new EventEmitter();
       this._super(arguments);
       this.patio = patio || require("./index");
       fromDb = isBoolean(fromDb) ? fromDb : false;
       this.__changed = {};
       this.__values = {};
       if (fromDb) {
           this._hook("pre", "load");
           this.__isNew = false;
           this.__setFromDb(options, true);
           if (this._static.emitOnLoad) {
               this.emit("load", this);
               this._static.emit("load", this);
           }
       } else {
           this.__isNew = true;
           this.__set(options);
       }
   } else {
       throw new ModelError("Model " + this.tableName + " has not been synced");
   }
           
}
            

associate Static Function Public


Defined plugins/association.js

Associates a related model with the current model. The following types are supported:

Arguments Source
function (type,name,options,filter){
   if (comb.isFunction(options)) {
       filter = options;
       options = {};
   }
   this.__associations = this.__associations || {manyToMany: {}, oneToMany: {}, manyToOne: {}, oneToOne: {}};
   var assoc = new associations[type](comb.merge({model: name}, options), this.patio, filter);
   assoc.inject(this, name);
   this.__associations[type][name] = assoc;
   this.emit("associate", type, this);
   return this;
           
}
    

create Static Function Public


Defined model.js

Create a new model initialized with the specified values.

Arguments Returns Source
function (values){
   //load an object from an object
   var Self = this;
   return new Self(values, false);
           
}
    

find Static Function Public


Defined plugins/query.js

Finds a single model according to the supplied filter. See patio.Dataset#filter for filter options.

Arguments Source
function (id){
   return this.filter.apply(this, arguments).first();
           
}
    

findById Static Function Public


Defined plugins/query.js

Retrieves a record by the primaryKey/s of a table.

Example
var User = patio.getModel("user");

User.findById(1).chain(function(userOne){

});

//assume the primary key is a compostie of first_name and last_name
User.findById(["greg", "yukon"]).chain(function(userOne){

});
        
Arguments Returns Source
function (id){
   var pk = this.primaryKey;
   pk = pk.length === 1 ? pk[0] : pk;
   var q = {};
   if (isArray(id) && isArray(pk)) {
       if (id.length === pk.length) {
           pk.forEach(function (k, i) {
               q[k] = id[i];
           });
       } else {
           throw new ModelError("findById : ids length does not equal the primaryKeys length.");
       }
   } else {
       q[pk] = id;
   }
   return this.filter(q).one();
           
}
    

findOrCreate Static Function Public


Defined plugins/query.js

Finds a single model according to the supplied filter. See patio.Dataset#filter for filter options. If the model does not exist then a new one is created as passed back.

Arguments Source
function (q){
   var self = this;
   return this.find(q).chain(function (res) {
       return res || self.create(q);
   });
           
}
    

inherits Static Function Public


Defined model.js

Stub for plugins to notified of model inheritance

Arguments Source
function (model){
   
}
    

manyToMany Static Function Public


Defined plugins/association.js

Creates a MANY_TO_MANY relationship between models. See patio.plugins.AssociationPlugin.associate for options.

Example
patio.addModel("class", {
     static:{
         init:function(){
             this._super("arguments");
             this.manyToMany("students", {fetchType:this.fetchType.EAGER, order : [sql.firstName.desc(), sql.lastName.desc()]});
         }
     }
});
patio.addModel("student", {
     instance:{
         enroll:function(clas){
             if (comb.isArray(clas)) {
                 return this.addClasses(clas);
             } else {
                 return this.addClass(clas);
             }
         }
     },
     static:{
         init:function(){
             this._super("arguments");
             this.manyToMany("classes", {fetchType:this.fetchType.EAGER, order : sql.name.desc()});
         }
     }
         });
        
Arguments Source
function (name,options,filter){
   return this.associate(this.MANY_TO_MANY, name, options, filter);
           
}
    

manyToOne Static Function Public


Defined plugins/association.js

Creates a MANY_TO_ONE association. See patio.plugins.AssociationPlugin.oneToMany. See patio.plugins.AssociationPlugin.associate

Arguments Source
function (name,options,filter){
   return this.associate(this.MANY_TO_ONE, name, options, filter);
           
}
    

oneToMany Static Function Public


Defined plugins/association.js

Creates a ONE_TO_MANY association. See patio.plugins.AssociationPlugin.associate for options.

Example
//define the BiologicalFather model
 patio.addModel("biologicalFather", {
     static:{
         init:function () {
             this._super("arguments");
             this.oneToMany("children");
         }
     }
});


//define Child  model
patio.addModel("child", {
     static:{
         init:function () {
             this._super("arguments");
             this.manyToOne("biologicalFather");
         }
    }
});
        
Arguments Source
function (name,options,filter){
   return this.associate(this.ONE_TO_MANY, name, options, filter);
           
}
    

oneToOne Static Function Public


Defined plugins/association.js

Creates a ONE_TO_ONE relationship between models. See patio.plugins.AssociationPlugin.associate for options.

Example
patio.addModel("state", {
     static:{
         init:function () {
             this._super("arguments");
             this.oneToOne("capital");
         }
    }
});

patio.addModel("capital", {
     static:{
       init:function () {
         this._super("arguments");
         this.manyToOne("state");
       }
     }
});
        
Arguments Source
function (name,options,filter){
   return this.associate(this.ONE_TO_ONE, name, options, filter);
           
}
    

remove Static Function Public


Defined plugins/query.js

Remove(delete) models. This can be used to do a mass delete of models.

Example
var User = patio.getModel("user");

//remove all users
User.remove();

//remove all users who's names start with a.
User.remove({name : /A%/i});

//remove all users who's names start with a, without a transaction.
User.remove({name : /A%/i}, {transaction : false});
        
Arguments Returns Source
function (q,options){
   options = options || {};
   var loadEach = isBoolean(options.load) ? options.load : true;
   //first find all records so we call alert the middleware for each model
   var ds = this.dataset.filter(q);
   return this._checkTransaction(options, function () {
       if (loadEach) {
           return ds.map(function (r) {
               //todo this sucks find a better way!
               return r.remove(options);
           });
       } else {
           return ds.remove();
       }
   });
           
}
    

removeById Static Function Public


Defined plugins/query.js

Similar to remove but takes an id or an array for a composite key.

Example
User.removeById(1);
        
Arguments Returns Source
function (id,options){
   var self = this;
   return this._checkTransaction(options, function () {
       return self.findById(id).chain(function (model) {
           return model ? model.remove(options) : null;
       });
   });
           
}
    

save Static Function Public


Defined plugins/query.js

Save either a new model or list of models to the database.

Example
var Student = patio.getModel("student");
Student.save([
     {
         firstName:"Bob",
         lastName:"Yukon",
         gpa:3.689,
         classYear:"Senior"
     },
     {
         firstName:"Greg",
         lastName:"Horn",
         gpa:3.689,
         classYear:"Sohpmore"
     },
     {
         firstName:"Sara",
         lastName:"Malloc",
         gpa:4.0,
         classYear:"Junior"
     },
     {
         firstName:"John",
         lastName:"Favre",
         gpa:2.867,
         classYear:"Junior"
     },
     {
         firstName:"Kim",
         lastName:"Bim",
         gpa:2.24,
         classYear:"Senior"
     },
     {
         firstName:"Alex",
         lastName:"Young",
         gpa:1.9,
         classYear:"Freshman"
     }
]).chain(function(users){
    //work with the users
});

Save a single record
MyModel.save(m1);
        
Arguments Returns Source
function (items,options){
   options = options || {};
   var isArr = isArray(items), Self = this;
   return this._checkTransaction(options, function () {
       return asyncArray(items)
           .map(function (o) {
               if (!isInstanceOf(o, Self)) {
                   o = new Self(o);
               }
               return o.save(null, options);
           })
           .chain(function (res) {
               return isArr ? res : res[0];
           });
   });
           
}
    

update Static Function Public


Defined plugins/query.js

Update multiple rows with a set of values.

Example
var User = patio.getModel("user");

//BEGIN
//UPDATE `user` SET `password` = NULL WHERE (`last_accessed` <= '2011-01-27')
//COMMIT
User.update({password : null}, function(){
 return this.lastAccessed.lte(comb.date.add(new Date(), "year", -1));
});
//same as
User.update({password : null}, {lastAccess : {lte : comb.date.add(new Date(), "year", -1)}});

//UPDATE `user` SET `password` = NULL WHERE (`last_accessed` <= '2011-01-27')
User.update({password : null}, function(){
 return this.lastAccessed.lte(comb.date.add(new Date(), "year", -1));
}, {transaction : false});
        
Arguments Returns Source
function (vals,/*?object*/query,options){
   options = options || {};
   var dataset = this.dataset;
   return this._checkTransaction(options, function () {
       if (!isUndefined(query)) {
           dataset = dataset.filter(query);
       }
       return dataset.update(vals);
   });
           
}
    

useTransaction Static Function Private


Defined model.js

Arguments Source
function (opts){
   opts = opts || {};
   return isBoolean(opts.transaction) ? opts.transaction === true : this.useTransactions === true;
           
}
    

__reload Function Private


Defined plugins/query.js

Forces the reload of the data for a particular model instance. The Promise returned is resolved with the model.

Example
myModel.reload().chain(function(model){
   //model === myModel
});
        
Returns Source
function (){
   if (!this.__isNew) {
       var self = this;
       return this.dataset.naked().filter(this._getPrimaryKeyQuery()).one().chain(function (values) {
           self.__setFromDb(values, true);
           return self;
       });
   } else {
       return when(this);
   }
           
}
    

_saveReload Function Private


Defined plugins/query.js

Arguments Source
function (options){
   options || (options = {});
   var reload = isBoolean(options.reload) ? options.reload : this._static.reloadOnSave;
   return reload ? this.__reload() : when(this);
           
}
    

_updateReload Function Private


Defined plugins/query.js

Arguments Source
function (options){
   options = options || {};
   options || (options = {});
   var reload = isBoolean(options.reload) ? options.reload : this._static.reloadOnUpdate;
   return reload ? this.__reload() : when(this);
           
}
    

remove Function Public


Defined plugins/query.js

This method removes the instance of the model. If the model patio.Model#isNew then the promise is resolved with a 0 indicating no rows were affected. Otherwise the model is removed, primary keys are cleared and the model's isNew flag is set to true.

Example
myModel.remove().chain(function(){
    //model is deleted
    assert.isTrue(myModel.isNew);
});

//dont use a transaction to remove this model
myModel.remove({transaction : false}).chain(function(){
    //model is deleted
    assert.isTrue(myModel.isNew);
});
        
Arguments Returns Source
function (options){
   if (this.synced) {
       if (!this.__isNew) {
           var self = this;
           return this._checkTransaction(options, function () {
               return self.__callHooks("remove", [options], function () {
                   return self._remove(options);
               })
                   .chain(function () {
                       self._clearPrimaryKeys();
                       self.__isNew = true;
                       if (self._static.emitOnRemove) {
                           self.emit("remove", this);
                           self._static.emit("remove", this);
                       }
                   })
                   .chain(function () {
                       return self;
                   });
           });
       } else {
           return when(0);
       }
   } else {
       throw new ModelError("Model " + this.tableName + " has not been synced");
   }
           
}
    

save Function Public


Defined plugins/query.js

Saves a model. This action checks if the model is new and values have changed. If the model is not new then the patio.Model#update action is called.

When saving a model you can pass values you want set as the first argument.



someModel.save({
     myVal1 : "newValue1",
     myVal2 : "newValue2",
     myVal3 : "newValue3"
}).chain(function(){
     //do something
}, errorHandler);


Or you can set values on the model directly



someModel.myVal1 = "newValue1";
someModel.myVal2 = "newValue2";
someModel.myVal3 = "newValue3";

//update model with current values
someModel.save().chain(function(){
    //do something
});


Save also accepts an options object as the second argument allowing the overriding of default behavior.

To override useTransactions you can set the transaction option.


someModel.save(null, {transaction : false});

You can also override the reloadOnSave property by setting the reload option.


someModel.save(null, {reload : false});

Arguments Returns Source
function (vals,options){
   if (this.synced) {
       if (this.__isNew) {
           var self = this;
           return this._checkTransaction(options, function () {
               if (isHash(vals)) {
                   self.__set(vals);
               }
               return self.__callHooks("save", [options], function () {
                   return self._save(options);
               })
                   .chain(function () {
                       return self._saveReload(options);
                   })
                   .chain(function () {
                       if (self._static.emitOnSave) {
                           self.emit("save", self);
                           self._static.emit("save", self);
                       }
                   })
                   .chain(function () {
                       return self;
                   });
           });
       } else {
           return this.update(vals, options);
       }
   } else {
       throw new ModelError("Model " + this.tableName + " has not been synced");
   }
           
}
    

setValues Function Public


Defined model.js

Set multiple values at once. Useful if you have a hash of properties that you want to set.

NOTE: This method will use the static restrictedColumns property of the model.

Example
myModel.setValues({firstName : "Bob", lastName : "yukon"});

//this will throw an error by default, assuming id is a pk.
myModel.setValues({id : 1, firstName : "Bob", lastName : "yukon"});
        
Arguments Returns Source
function (values){
   this.__set(values, false);
   return this;
           
}
    

toJSON Function Public


Defined model.js

Convert this model to JSON, containing column, value pairs.

Returns Source
function (){
   return this.toObject();
           
}
    

toObject Function Public


Defined model.js

Convert this model to an object, containing column, value pairs.

Returns Source
function (){
   return this._toObject(false);
           
}
    

toString Function Public


Defined model.js

Convert this model to a string, containing column, value pairs.

Returns Source
function (){
   return JSON.stringify(this.toObject(), null, 4);
           
}
    

update Function Public


Defined plugins/query.js

Updates a model. This action checks if the model is not new and values have changed. If the model is new then the patio.Model#save action is called.

When updating a model you can pass values you want set as the first argument.



someModel.update({
     myVal1 : "newValue1",
     myVal2 : "newValue2",
     myVal3 : "newValue3"
}).chain(function(){
     //do something
}, errorHandler);


Or you can set values on the model directly



someModel.myVal1 = "newValue1";
someModel.myVal2 = "newValue2";
someModel.myVal3 = "newValue3";

//update model with current values
someModel.update().chain(function(){
    //do something
});


Update also accepts an options object as the second argument allowing the overriding of default behavior.

To override useTransactions you can set the transaction option.


someModel.update(null, {transaction : false});

You can also override the reloadOnUpdate property by setting the reload option.


someModel.update(null, {reload : false});

Arguments Returns Source
function (vals,options){
   if (this.synced) {
       if (!this.__isNew) {
           var self = this;
           return this._checkTransaction(options, function () {
               if (isHash(vals)) {
                   self.__set(vals);
               }
               var saveChange = !isEmpty(self.__changed);
               return self.__callHooks("update", [options], function () {
                   return saveChange ? self._update(options) : null;
               })
                   .chain(function () {
                       return self._updateReload(options);
                   })
                   .chain(function () {
                       if (self._static.emitOnUpdate) {
                           self.emit("update", self);
                           self._static.emit("update", self);
                       }
                   })
                   .chain(function () {
                       return self;
                   });
           });
       } else if (this.__isNew && this.__isChanged) {
           return this.save(vals, options);
       } else {
           return when(this);
       }
   } else {
       throw new ModelError("Model " + this.tableName + " has not been synced");
   }
           
}
    

valueOf Function Public


Defined model.js

Convert this model to a string, containing column, value pairs.

Returns Source
function (){
   return this.toObject();
           
}
    

Documentation generated using coddoc.