Building Enterprise HTML5 Application

brite.registerView

Register the view with brite. Should be done only once per application. Typically these instructions are in the /js/[ViewName].js file. If brite.display([ViewName]...) is called before the corresponding view is registered, brite will attempt to load /js/[ViewName].js.

brite.registerView(viewName,viewDefinition)

brite.registerView(viewName,config,viewDefinition)

  • viewName {string}: The unique name of the view (i.e. "ProjectView")
  • config {object}: The default config parameters for this view. Can be "null" if not needed.
    • config.parent {element} : The default html element (or jQuery selector or jQuery Element) that this view will be appended to on display. This is usually overrided by brite.display
    • config.emptyParent {boolean} : Tell if the parent needs to be empty when this view is added. By default, this is false, meaning, the view will be added to the parent. This can be overrided by brite.display
    • config.loadTmpl {boolean} : Tell if brite should load the corresponding template file at /tmpl/[ViewName].tmpl. Template will be loaded only once at first brite.display call, and will be added to the body to enable any templating engine retrieval via $("#tmpl-[ViewName]") convention. By default, this is false.
    • config.loadCss {boolean} : Tell if brite should load the corresponding css file at /css/[ViewName].css (css will be loaded and added only once at first brite.display call). By default, this is false.
  • viewDefinition {object/function} : This is the factory object or function for the view interface. If it is an object, it will be cloned at each instantiation (i.e. brite.display), if it is a function, is must return a new instance when invoked. The View may implements the following:
    • create(data,config) {function} : This is the only required interface that a view must implement. It will be called just after the brite.display and must return the new HTMLElement for the View (or a Deferred Promise which must resolve with the new HTMLElement). The data argument is the data object from the brite.display call. config is the merged config object from the display call and the register default. Usually view code do not need this argument.
    • init(data,config) {function} : This will be called after create is called but before it is displayed to the user. This is a good place to do any UI layout/styling logic if really needed (try to do as much styling and layout in HTML/CSS as possible for performance reasons). If this method return a Deferred Promise, brite will wait that it resolved before going to next step. For most Views, this method is not necessary since most of the binding logic should be done in the follow postDisplay method.
    • postDisplay(data,config) {function} : This will be called after create and the eventual init. This is a good place to do any binding logic as this will happen after the user see the view.
    • destroy() {function} : Will be called when the View get destroy. Good place to unbind any Dao and parent HTML element binding.

In addition to the view lifecycle methods, a view can have events which will be bound and unbound on view instantiation and destroy.

  • viewDefinition.events {object} : This is a JS object where the keys string representing the binding rule with the following format "[event_type(s)]; [jQuery elector]" and the value a function or a method's name of the view. The View's events will be bound relative to the view.$el.
  • brite.registerView("MyView",
        {create: function(){...},
         
         // will be relative to the view.$el
         events: {
           "click; button.clickme" : function(event){
             // the "this" is the view instance
             var view = this;
             // the event is the DOM event for this binding
           }
         }
    });
    
  • viewDefinition.docEvents {object} : Similar to the .events but will be relative to the document. Note that all these events will be namespaced with the view.id and unbound when the view is detroyed. This is a good place to listen to application status change events, but should not be use to listen to this view events (.events should be use for this).
  • viewDefinition.winEvents {object} : Similar to the .docEvents but will be relative to the window. Similar to the .docEvents, those event binding are namespaced with the view.id and will be unbound on view destroy. This can be useful to listen to browser events that fire only on "window" (e.g., resize).
  • viewDefinition.daoEvents {object} : Similar concepts and the previous events properties but for the dao with the following key format: "[daoEventType]; [EntityType,];[actions,]".
  • brite.registerView("MyView",
        {create: function(){...},
         
         daoEvents: {
           
           // bind on dataChange dao event, on User and Task entity, for action "create" only
           "dataChange; User, Task; create" : function(event){
             // the "this" is the view instance
             var view = this;
             var daoEvent = event.daoEvent;
           },
           
           // bind on result (brite.dao.onResult) for Project 
           "result;Project" : function(event){
             // any dao calls on Project will pass by here. 
           }
           
           
         }
    });
    

Examples

js/MyView.js

// always wrap module code in an anonymous function to avoid context-bleed  
(function(){  

brite.registerView("MyView",
                 
     // config
     {parent:"body",
      emptyParent: true},
      
     // viewDefinition 
     {
       create: function(data,config){
         // Here: this.id is the unique instance id of this view 
         // for example, using jsrender
         return $("#tmpl-MyView").render(data);
       },
       
       init: function(data, config){
         // will be called after the create and before the postDisplay.
         // this.$el is the jQuery wrapped HTML Element for this view instance
         // this.id is the unique instance id for this view 
       }
       
       postDisplay: function(data,config){
         // will be called after the init and after the element has been added to the DOM
         // Good place to do binding here. 
         // same object, so same properties (i.e. this.$element, this.id).
         
         // best-practice: use the this.id for dao binding
         brite.dao.onDataChange("User",function(event){...},this.id); 
       },
       
       destroy: function(){
         // best-practice: good way to unbind any dao with this namespace. 
         brite.dao.offAny(this.id);
       }
       
       someCustomPublicMethod: function(any,argument,signature){
         // same object, so same properties (i.e. this.$element, this.id).
       }
     }
);
  
  // if controllerFactory is a JS Object (as above), then it will be cloned on each 
  // brite.display to allow the this.$element and this.id to be unique per instance. 
  
  // controllerFactory can also be a function which is responsible to return a new object instance.                 
})();

Ask, learn, share about brite.js

Go to brite.js G+ community