Model layer

tetra.model

Documentation of the model layer interface of Tetra.js

Interface

• register([string] name, [object] implementation): register a new model class to tetra.
• destroy([string] name, [string] scope): destroy a previously registered model class.
• debug: debugging console. Specifications with the command tetra.model.debug.man.

tetra.model.register([string] name, [object] implementation)

Definition

This method allows you to register a model description object.

Main arguments

• name [string]: The name of the model. It must be the same of the file name.
• description [object]: This object describes models attributes, validation methods and routes. A more detailed definition follows.

Model description

{  
     req : {}, // #object  
     attr : {}, // #object  
     methods : {} // #object  
}

• req: For request settings : routes for accessing server-side objects.
• attr (mandatory): Object listing all attributes of the class with their default value. They are all private.
• methods: Contains custom and reserved methods.

Request settings req

{  
    save : {  
        params: {  
             action: 'addInterest'  
        }  
    },  
    fetch : {  
        url: '/path/to/{0}/{1}',  
        uriParams: ['test', 'var'],  
        method: 'POST',  
        params: {  
             action: 'getInterest'  
        },  
        parser: function(resp, col, cond) {  
              // parsing of resp  
              return col;  
        }  
    },  
    del : {  
        params: {  
              action: 'deleteInterest'  
        }  
    }  
}

This attribute is not mandatory if you use default settings.

There's simple call types for each actions :

• save: settings used when calling save() method through ORM.
• fetch: settings used when calling fetch() method through ORM.
• del: settings used when calling del() method through ORM.
• reset: settings used when calling reset() method through ORM.

Here are the settings you can set for each call type :

• url [string]: default pattern is "/javascript/coremvc/model/modelName/callType.json" but you can override it using this setting.
• uriParams [array]: name of a condition or an attribute of the object that must replace a var in the url pattern. For example: "/path/to/{0}/{1}" with uriParams = ['test', 'var'] will replace {0} by cond.test or attr.test and {1} with cond.var or attr.var.
• methods [string]: "GET" or "POST" (by default : fetch is set to "GET", save and del are set to “POST”).
• params [object]: a javascript object listing all constant parameters with their value used in a specific call type.
• parser [function]: if the response of a fetch call doesn’t fit the Standard JSON Format, you have to define this function. You receive in arguments the ajax response (resp), an empty object (col) and the request conditions (cond). With this information, you must fill the col object using a key/value structure. The key must be unique and the value is an object similar to the attr object of the model (same attribute names).

Methods methods

All model created vie core.model.register inherit of default methods that allow access to the underlying collection.

default methods (implemented in core)

• get(attrName): get an attribute
• getAll(): get all attributes
• set(attrName, value): set an attribute with a value
• update(attributes): set attributes with values listed in the passed object
• revert(): revert data to last saved state. Automatically called when a save call failed.
• save(): save the object on server
• remove(): remove the object locally and on server.

reserved methods (optional and implemented in class by you)

• init(): call when an object is constructed
• validate(): call before saving data on server

Sample code

tetra.model.register('likeObj', {  
  
    req : {  
        save : {  
            params: {  
                        action: 'addInterest'  
            }  
        },  
  
        del : {  
            params: {  
                        action: 'deleteInterest'  
            }  
        }  
    },  
  
    attr : {  
        id : '0020',  
        elementId : 0,  
        memberId : '0020',  
        type : '',  
        fullName: '',  
        isConnectedMember: false  
    },  
  
    methods : function(attr) { return {  
        validate : function(attr, errors){  
            if (attr.elementId == 0) errors.push('elementId');  
            if (attr.type == '') errors.push('type');  
            return errors;  
        }  
    };}  
  
});

Use case: form validation

As show above, the model integrate a validation function which is called before each save and on demand. You can customize this working to allow you to validate each attribute separately. For example, the methods section in the previous sample code could be replaced by this one:

methods : function(attr) { return {  
    validate : function(attr, errors){  
        if (!this.validElementId(attr)) errors.push('elementId');  
        if (!this.validType(attr)) errors.push('type');  
        return errors;  
    },  
  
    validElementId: function(attr) {  
        return !(attr.elementId == 0);  
    },  
  
    validType: function(attr) {  
        return !(attr.type == '');  
    }  
};}

For each attribute you have to validate, you define a function validX(...) that will return true when the value is valid.

In this case, we just move the conditions in the "if" of the validate function in new functions and prefix it by a not operator "!" to get the attended return. Conditions in the validate function can now be replaced by a call to these new functions to keep a consistent validation in all cases.