Model

Initializes a model instance

Whenever a model is instantiated, init() is run to configure the instance.  First the init() in the Model base class is run, then the init() in app/models/global.sjs, and finally the init() in app/models/<name>_model.sjs

Functions typically called from init

• Associations: belongsTo, hasOne, hasMany, hasBridgeTo
• beanClass configuration: setDefault/setDefaults, setLabel/setLabels, addField/addFields, addValidator

applyBehavior:function applyBehavior( name )

loads a behavior and applies it to this object

Parameters

Detail

Loads a behavior by name from app/behaviors/models/ or framework/behaviors/models/, whichever is found first.  Behaviors are functions that are applied to the current object.  applyBehavior should be called from init

Example

//in some_model.sjs
function init(){
    this.applyBehavior([
        "SomeBehavior",
        "SomeOtherBehavior"
    ]);
}

addValidator:function addValidator( colname, validator, options )

adds a validation function to this Model’s validation object

Parameters

Validator Function

The validator function will be called with a parameters object with these properties obj - Object being validated property - Property being validated label - result of getLabel for property value - value being validated options - validator options.  Most validators define their own specific options, but all validators accept the options below

Validator Options

Returns

this validation instance

Examples

this.addValidator("first_name","length",{
    min:3,
    max:25
})

//only validate spouse_name when married is true
this.addValidator("spouse_name","required",{
    when:function(params){
        return params.obj.married
    }
})

function isBob(params){
    var vr = new Myna.ValidationResult();
    if (params.value != "Bob"){
        var msg = params.options.message || params.label + " is not Bob!"
        vr.addError(msg,colname)
    }
    return vr;
}

this.addValidator("first_name",isBob,{
    message:"Inferior name entered."
})

See

• Myna.Validation
• validation property
• addValidators
• beanClass.validate

create:function create( requiredFields )

Custom Model Override A model specific create function function.

Parameters

returns a beanClass instance of the bean created

Custom Models must implement this function.

Database models use ManagerObject.create

forceDelete:function forceDelete( id )

Custom Model Override A model specific delete function.

Parameters

Custom Models must implement this function.

Database models use ManagerObject.forceDelete

query:function query( pattern, options )

Custom Model Override A model specific search function.

Parameters

returns a Myna.DataSet of beanClass Objects

Custom Models must implement this function.

Database models use ManagerObject.query from <DataManager>

saveBeanField:function saveBeanField( bean, fieldName, oldval, newval )

Custom Model Override A model specific save function.

Parameters

returns a Myna.ValidationResult object

Custom Models must implement this function.

Database models do not use this function

find:function find( pattern, options )

returns an array of idField values that match a search

Parameters

Database models use ManagerObject.find which offers more options.  Custom Models may offer extra features as well.

See

• ManagerObject.find
• findBeans

findBeans:function findBeans( pattern, options )

returns a Myna.DataSet of <beanField> values that match a search

Parameters

Database models use ManagerObject.findBeans which offers more options.  Custom Models may offer extra features as well.

See

• ManagerObject.findBeans
• find

Generates a unique identifier for this Model

Database models use ManagerObject.genKey Custom Models should override this this function

See

• ManagerObject.genKey

getField:function getField( name )

returns metadata for a field

Returned Object Properties

getFields:function getFields()

returns array of field metadata objects

See

• getField

getType:function getType( name )

returns type of field

Parameters

Possible Types

• string
• numeric
• date
• binary

See

• addField

addField:function addField( def )

adds a field to this Model’s beanClass

Parameters

Field Definition

returns this model See:

• addFields

addFields:function addFields( fields )

adds multiple fields to this Model’s beanClass

Parameters

returns this model See:

• addField

getById:function getById( id )

returns the beanClass for a given ID, or throws an exception

Parameters

getDefault:function getDefault( name )

returns the default value for a given field name

Parameters

See

• getDefaults

getDefaults:function getDefaults()

returns a JS Object where the properties are field names and values are their default values

Parameters

See

• getDefault

remove:function remove( id )

removes a bean by id

Parameters

Note that database models support “soft” deletes via a softDelete Column See:

• ManagerObject.remove
• forceDelete

setDefault:function setDefault( name, value )

sets a default value for a field

Parameters

See

• setDefaults

setDefaults:function setDefaults( map )

sets a default values for multiple fields

Parameters

See

• setDefault

genLabel:function genLabel( colname )

generates a display label from a field name

The default implementation either uses one of the special replacements below, or replaces all underbars with spaces and calls String.titleCap on the result.  You can override this function in your models for custom behavior

Special Replacements

getLabel:function getLabel( name )

returns the label for a field name

Parameters

See

• setLabel

setLabel:function setLabel( name, label )

sets a label for a field name

Parameters

See

• setLabels
• getLabel

setLabels:function setLabels( map )

sets multiple labels

Parameters

See

• setLabel
• getLabel

get:function get( values )

returns either an instance of an existing bean or the result of getNew

Parameters

Detail

This function attempts to create a usable bean even if there is no matching record.  If values is provided with a valid primary key, then getById is called, beanClass.deferred is set to true, and beanClass.setFields is called with values.  Otherwise getNew is called with values.  Regardless, the resulting bean will be deferred and beanClass.save must be called to persist changes

Note

Any defaults set by setDefault will be applied before returning the bean object

Example

//in app/controllers/order_controler.sjs
//crate or update an order from form data:
function save(params){
    var order = this.model.get(params)
    var result = order.save();
    if (result.success) {
        ...
    } else{
        ...
    }
}

getNew:function getNew( initialValues )

Returns a beanClass representing a new row not yet inserted

Parameters

Note

Any defaults set by setDefault will be applied before returning the bean object

See

• beanClass.deferred
• beanClass.save

belongsTo:function belongsTo( name )

Sets a “belongsTo” relationship with another model.

This function has 3 parameter patterns

Model Name

Model Definition object

this.belongsTo({
    name:"Profile",
    conditions:{
        where:"public = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    }
})

Model definition object array

this.belongsTo([{
    name:"Profile",
    conditions:{
        where:"public = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    }]
},{
    name:"Employee"
}])

Detail

This maps a one-to-one relationship with the related Model to this one.  Once set, any beans returned by this manager will include a function with the same name as the related model that represents the result of <relatedModel>.get() for the related row in the related Model.  This is best shown by example

//Person Model
function init(){
    this.belongsTo("Profile")
}
//Person controller
function edit(params){
    this.set("person",this.Person.get({id:params.id}));
}
//person_edit view
Name: <input name="name" value:"<%=person.name%>"><br>
<!--
    this is the same as
    $FP.getModel("Profile").findBeans({person_id:person.id}).first().email
-->
Email: <input name="Profile.email" value:"<%=person.Profile().email%>"><br>

hasOne:function hasOne( name )

Sets a “hasOne” relationship with another Model.

This function has 3 parameter patterns

Model Name

Model Definition object

var Person = dm.getManager("Person")
Person.hasOne({
    name:"Profile",
    alias:"RecentPublicProfile",
    conditions:{
        where:"public = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    }
})

Model definition object array

var Person = dm.getManager("Person")
Person.hasOne([{
    name:"Profile",
    alias:"RecentPublicProfile",
    conditions:{
        where:"public = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    }]
},{
    name:"Profile"
}])

Detail

This maps a one-to-one relationship with the related Model to this one.  Once set, any beans returned by this manager will include a property with the same name as the related model that represents the result of <relatedModel>.get() for the related row in the related Model.  This is best shown by example

// --- from a FlightPath MVC app ---
//Person Model (a DataManager.Model)
function init(){
    this.hasOne("Profile")
}
//Person controller
function edit(params){
    this.set("person",this.Person.get({id:params.id}));
}
//person_edit view
Name: <input name="name" value:"<%=person.name%>"><br>
<!--
    this is the same as
    $FP.getModel("Profile").findBeans({person_id:person.id}).first().email
-->
Email: <input name="Profile.email" value:"<%=person.Profile().email%>"><br>

hasMany:function hasMany( name )

Sets a “hasMany” relationship with another Model.

This function has 3 parameter patterns

Model Name

//these are equivalent
var Person = dm.getManager("Person")
Person.hasMany("Posts")
Person.hasMany("posts")

Model Definition object

var Person = dm.getManager("Person")
Person.hasMany({
    name:"Posts",
    alias:"RecentPosts
    conditions:{
        where:"published = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    },
    orderBy:"category_title ASC, date_published DESC"
})

Model definition object array

var Person = dm.getManager("Person")
Person.hasMany([{
    name:"Posts",
    alias:"RecentPosts
    conditions:{
        where:"published = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    },
    orderBy:"category_title ASC, date_published DESC"
},{
    name:"Posts",
    orderBy:"category_title ASC, date_published DESC"
},{
    name:"Favorites"
}])

Detail

This maps a one-to-many relationship with the related Model to this one.  Once set, any beans returned by this manager will include a function with the same name as the related alias that represents the result of <relatedModel>.findBeans(), constrained by the foreign key relationship.  This is best shown by example

// --- from a FlightPath MVC app ---
//Person Model
function init(){
    this.hasMany("Posts")
}
//Person controller
function edit(params){
    this.set("person",this.Person.get({id:params.id}));
}
//person_edit view
Name: <input name="name" value:"<%=person.name%>"><br>
<!--
    person.Posts is the same as
    $FP.getModel("Post").findBeans({person_id:person.person_id})
-->
Posts:
<ul>
<@loop array="person.Posts()" element="post" index="i">
    <li> <%=post.title%>
</@loop>
</ul>

hasBridgeTo:function hasBridgeTo( name )

Sets a “many-to-many” relationship with another Model.

This function has 3 parameter patterns

Model Name

//these are equivalent
var Person = dm.getManager("Person")
Person.hasBridgeTo("Tags")
Person.hasBridgeTo("tags")

Model Definition object

var Person = dm.getManager("Person")
Person.hasBridgeTo({
    name:"Tags",
    alias:"RecentTags",
    conditions:{
        where:"published = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    },
    orderBy:"category_title ASC, date_published DESC"
})

Model definition object array

var Person = dm.getManager("Person")
Person.hasBridgeTo([{
    name:"Tags",
    alias:"RecentTags",
    conditions:{
        where:"published = 1 and modified > {oneYearAgo:date}",
        oneYearAgo:new Date().add(Date.YEAR,-1).clearTime()
    },
    orderBy:"category_title ASC, date_published DESC"
},{
    name:"Tags",
    orderBy:"category_title ASC, date_published DESC"
}])

Detail

This maps a many-to-many relationship with the related Model to this one.  This requires a “bridge” Model i.e a Model that maps the idField of both Models.  Once defined, any beans returned by this manager will include a function with the same name as the related alias that represents the result of <relatedModel>.findBeans(), constrained by the foreign key relationship.  This is best shown by example

// --- from a FlightPath MVC app ---
//Person Model
function init(){
    this.hasMany("Tags")
}
//Person controller
function edit(params){
    this.set("person",this.Person.get({id:params.id}));
}
//person_edit view
Name: <input name="name" value:"<%=person.name%>"><br>
<!--
    person.Posts is the same as
    $FP.getModel("Post").findBeans({person_id:person.person_id})
-->
Posts:
<ul>
<@loop array="person.Tags()" element="tag" index="i">
    <li> <%=tag.title%>
</@loop>
</ul>

Custom validator that validates a value is unique in a field

Parameters

Detail

This will search all instance of this model looking for any instances of this value, NOT associated with this idProperty.  If any are found this validator will add an error

Examples

this.addValidators({
    name:{
        required:{},

    },
    slug:{
        required:{},
        unique:{},//slug must be unique in the table, regardless of case
        regex:{
            pattern:/^[a-z0-9-]+$/,
            message:"Can only contain numbers, lowercase letters, '_' or '-'"
        }

    },
})
//OR
this.addValidator("slug","unique")

See

• addValidator

gets a value for <fieldName>

Detail

This function is generated for every column in the associated table.

sets a value for <fieldName>

Parameters

Returns

Myna.ValidationResult object representing the result of the set.

Detail

This function is generated for every column in the associated table, except for the primary key.

Sets multiple fields at once

Parameters

Returns

Myna.ValidationResult representing the result of this action.

Detail

This function will examine each non-function property of fields and call the corresponding “set” function, if available.  Properties that do not match a “set” function are ignored

Persists a value to its underlying row

Parameters

Returns

Myna.ValidationResult representing the result of this action.

Detail

This function is normally called from the “set” function, but may be useful when overriding the generated “set” function.  This will not actually persist its value if deferred is true

alias for Model.forceDelete, which passes this bean’s id

return a structure of this bean’s data

Parameters

Detail

This is a copy of the data, so it will not change when the object is modified

alias for Model.getLabel

alias for Model.remove, which passes this bean’s id

Saves a deferred bean and returns a Myna.ValidationResult object

If called against a deferred BeanObject, all values in data are persisted to the database.  Afterwards, this bean’s deferred status is set to the Model’s deferred status

Validates this bean.

Calls all of the validator functions added via Model.addValidator against this bean and returns the merged Myna.ValidationResult object

Parameters

• Model.addValidator
• Model.validation
• Myna.Validation