Controller layer

tetra.controller

Documentation of the controller layer interface of Tetra.js

Interface

• register([string] name, [object] implementation): register a new controller class to tetra.
• destroy([string] name, [string] scope): destroy a previously registered controller class.
• notify([string] message, [mixed] data, [string] scope): send an event with data to controllers in the specified scope. This method must be called in view classes through app.notify or in controller classes through page.notify.
• modelNotify([string] modelName, [string] type, [mixed] args): send an event with data from the model modelName to all controllers. This method is called internally by tetra to notify controllers of model changes.
• exec([string] actionName, [string] ctrlName(optional), [object] data, [function] callback, [string] scope, [string] uid, [string] cid): call the internal templating system of tetra. This method must be called in view classes through app.exec. More details at Templating system.
• debug: debugging console. Specifications with the command tetra.controller.debug.man.

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

Definition

This method allows you to register a view controller description object.

Main arguments

• name [string]: The name of the controller. It must be the same of the file name. For example: if you call your controller likeCtrl, the file will be called likeCtrl.ctrl.js�.
• implementation [object]: This object describes view and models’ listeners and notifiers. A more detailed definition follows.

Controller description

{  
     scope : 'scope name', // #string  
     use : ['event', 'like', ...], // #array of models' names dependencies  
     constr : behaviors // #function  
}

Context parameters

• scope [string]: this is the visibility scope of message sent by the controller to view. Actually this is the application scope and it must be the application name. For example: for the like feature, the scope must be likeApp�.
• use [array]: the list of model require by the controller to work properly. This list is mandatory when the controller is loaded using the bootstrap. If the nested model is a global one, prefix its name with g/ (example: use: ['g/name']).

Constructor

constr : function(me, app, page, orm) { return {  
   events : {...},  
   methods : {...}  
};}

constr is a function returning controller's behaviors in the following context :

• me: this variable gives you access to all datas of the controller object generated : scope, events, methods and all other attributes you can attach to.
• app: the communication pipe to all views in the scope.
• page: the communication pipe to all controllers.
• orm: object relational model of the core framework. it allows you to create, retrieve, update or delete data objects and synchronize data with the server. It is a total abstraction of ajax calls. A deeper explanation will be done in another section.

Events

events : {  
     model : {  
          'like' : {  // model name  
               'append' : function(obj){...},  
               'save' : function(obj){...},  
               'saved' : function(obj){...},  
               ...  
          },  
          ...  // other models treatment  
     },  
     view : {  
          'message' : function(data){...},  
          ...  
     },  
     controller : {  
          'message from page.notify' : function(data){...},  
          ...  
     } 
}

events is a description of callbacks executed as a consequence of view demand or model change.

Here is the list of all models change messages :

• call: operations done before each ajax call.
• complete: operations done after each ajax call.
• create: Operations done at the creation of an object. Receives the created object in parameter.
• fetch: Operations done before a fetch call. Receives the conditions of the request.
• append: Callback of a succeed fetch call. Receives the collection of results in parameter.
• save: Operations done before a save call. Receives the updated object in parameter.
• saved: Callback of a succeeded save call. Receives the updated object in parameter.
• delete: Operations done before a delete call. Receives the updated object in parameter.
• deleted: Callback of a succeed delete call. Receives the updated object in parameter.
• reset: Operations done before a reset. Receives the collection of all objects in parameter.
• reseted: Callback of a succeed reset call. Receives the name of the model in parameter.
• invalid: Operations done when updated attributes of an object are not valid. Receive the list of incorrect attr and the obj� instance in parameter.
• alert: Callback of successful call (200) with alerts. Receives alert type (save, fetch, ...), alerts object, conditions of the call or object.
• error: Callback of every failed call (!=200). Receives error type (save, fetch, ...), error code (500, 404, ...), errors object, conditions of the call or object.

Methods

methods object has the same specification as for a view description object. See core.view.register.

Sample Code

tetra.controller.register('likeCtrl', {  
  
    scope : 'likeApp',  
    use : ['likeObj'],  
  
    constr : function(me, app, page, orm) { return {  
  
        events : {  
  
            model: {  
                'likeObj' : {  
                    'call' : function(data){},  
                    'complete' : function(data){},  
                    'append' : function(col){  
                        app.notify('do this', col);  
                    },  
                    'create' : function(obj){  
                        app.notify('do that', obj);  
                    },  
                    'update' : function(obj){  
                        app.notify('do that', obj);  
                    },  
                    'stored' : function(obj){  
                        app.notify('do this', obj);  
                    },  
                    'remove' : function(obj){},  
                    'deleted' : function(obj){  
                        app.notify('do this', obj);  
                        app.notify('do that', obj);  
                    },  
                    'error' : function(error){  
                        if(error.type == 'save') {  
                            console.log('save error');  
                        } else if(error.type == 'delete') {  
                            console.log('delete error');  
                        }  
                    }  
                }  
            },  
  
            view: {  
                'ask this' : function(data) {  
                    app.notify('do this', data);  
                },  
                // [...]  
                'ask that' : function(data){  
                    data = me.methods.prepareThat(data);  
                    app.notify('do that', data);  
                }  
            }  
  
        },     
  
        methods : {  
            init: function() {  
                me.myCtrlVar = 'smthg';  
                // Initialization of the controller  
            },  
            //[...]  
            prepareThat: function(data){  
                // Common function use in the controller  
                return data;  
            }  
        }  
    };}  
  
});