Richfaces component development: client side code template

The goal of that document is to provide points to standartize RichFaces client side component development.


It includes:



All RichFaces components should be inherited from RichFaces.BaseComponent class or class based on it.


Template of javascript file for RichFaces component:
// Template of javascript file for richfaces component
// Define and call function to create and register Class for our component
// As arguments we should pass all javascript library objects that we need to use
// in our component, and at last our parameters(if needed) to create class of out
// component
(function (jQuery, richfaces, params) {

     // Create (for example) ui container for our component class
     richfaces.ui = richfaces.ui || {};

     // Create constructor and register our component class from (for example) ui
     // tag library in richfaces object
     richfaces.ui.Component = function(componentId [,options]) {
          // call constructor of super class
          $, componentId [,options]);

          // Attach our component object to a dom element if we want to call it's
          // API methods from inside of component
          // Call protected method from BaseComponent
          this.attachToDom(this, componentId);

          // Here is additional constructor code 

     // Private functions definition
     var f = function () {};

     // Public functions definitions. It's fully the same as for private but public  
     // ones will be later returned from extend method.
     var f1 = function () {};

     // Making function protected. At first defining function as private
     var myPrivateMethod = function () {};

     // Extend component class and add protected methods from parent class to
     // our container. richfaces.BaseComponent should be used or class
     // inherited from BaseComponent class
     richfaces.BaseComponent.extend(richfaces.BaseComponent, richfaces.ui.Component);
     // define super class link for better usability
     var $super = richfaces.MyComponent.$super;

     // Add variable, properties and methods to our component class via extending
     // it's prototype and returning linsk to them
     jQuery.extend(richfaces.ui.Component.prototype, (function (params) {

          // Public properties and functions definition
          return {
               name: "Component",  // Shared property definition
               // define destroy method to clean up when ajax or page rerender happened
               // to avoid memory leaks 
               destroy: function () {$};
               f1: f1,             // Link to function that was defined as private
                                   // to make it public
               f2: function () {}, // Public function definition

               // If we need ability to use "chain" commands, function should
               // return object instance (this) 
               // This allows to attach multiple function calls together with one
               // line of code, for example:
               f3: function () {

                    // some function code

                    return this;
})(jQuery, RichFaces, {p1:"param1", p2:"param2"});


Benefits of the approach used in the template:

    • Better Portal support (Nick please clarify it more)
    • Possibility to define private methods and properties



How to create instance of component:
// Component instance creation
// NOTE: componentId must be valid id string
new RichFaces.ui.Component(componentId);

// Example of component instance creation and use "chain" commands
new RichFaces.ui.Component(componentId).f3().f3();



How to call private method from public method:
// f() - private method
// f1() - public method
function f1() { [, arguments]); // call private method with "this" as a context



How to call api functions of component
// Find component instance and call it's function

// Another way to find component instance using RichFaces.$
// NOTE: componentId must be valid id string
// NOTE: DOM element or jQuery object can be used instead of id string.