RichFaces Client-Side Code: Base component classes usage

Table of Contents

Overview

Almost all RichFaces components have been inherited from RichFaces.BaseComponent class or class based on it.
There are three base classes for client side development:

• RichFaces.BaseComponent - core base component class.
• RichFaces.ui.Base - base class for ui components. Inherited from RichFaces.BaseComponent. Created to minimize component’s class definition. Contains: extended constructor,  empty __bindEventHandlers method and extended destroy method. This class doesn't have extendClass method for easy extending. Now used only by message component. All other ui components use RichFaces.BaseComponent as base.
• RichFaces.BaseNonVisualComponent - core base component class for non visual components definition. Now used only by DnD component. The same as RichFaces.BaseComponent without getEventElement and invokeEvent methods and with modified attachToDom method. (TO REVIEW for future optimization: Make sense to inherit this class from RichFaces.BaseComponent and just override attachToDom method. Also we should compare with RichFaces.BaseComponent and RichFaces.BaseNonVisualComponent classes when instanceof is used to determine if the object is an instance of RichFaces component)

Due to the fact that components classes inherited from RichFaces.BaseComponent we can extend the components with more common functionality(by just addition to base class) and determine that object is RichFaces component using instanceof.

RichFaces.BaseComponent description

RichFaces.BaseComponent contains folowing methods:

• BaseComponent(componentId) - construnctor. Stores componentId to this.id and create this.options hash for component initialization properties.
• extend (child, h) - Method extends child class prototype with parent prototype and return the object with parent's protected methods. Used by extendClass method.
• extendClass(methods) - Easy way to extend child class. Hash with methods should be passed as a parameter. In this case constructor should be defined as the function with init name in that hash. See template based on Richfaces.BaseComponent.
• toString() - return String representation of the class
• getValue() - returns undefined. Should be overridden by other class and should return component value.
• getEventElement() - Method returns element's id for event handlers binding. Event API calls this method when event binding by component object is used. In BaseComponent returns component id (this.id).
• attachToDom(source) - Attach component object to DOM element. Returns the element to which attached. Its required for the client side API calls and to clean up after ajax request or document unload by calling destroy method.
  • source {string || JQuery object || DOM element} - component id, DOM element or jQuery object. If source not defined this.id as source will be used.
• detach(source) - removes reference to component object from DOM elsement.
  • source - the same as for the attachToDom method.
• invokeEvent(eventType, element, event, data) - fires event using RichFaces Event API and calls event handlers from this.option if they are defined.
  • eventType {string} - type of event
  • element {Dom Element} - element that will be passed as a context for event handlers from this.options.
  • event {Event object} - original Event object will be passed to a handler.
  • data {any} - aditional data, will be passed to a handler.
• destroy() - destructor. Called when component would be removed from DOM. See more about RichFaces cleanup.

RichFaces.ui.Base description

RichFaces.ui.Base inherits from RichFaces.BaseComponent and contains following methods:

• Base(componentId, options, defaultOptions) - Constructor. Makes following actions:
  • Creates this.namespace property for event bindings according jQuery event namespaces;
  • calls super class constructor;
  • extends this.options property by defaultOptions and then by options;
  • attaches javascript object to DOM element by componentId;
  • calls _bindEventHandlers() method;
• __bindEventHandlers() - empty method. Should be overrided to bind component’s event handlers if needed;
• destroy() - destructor. Just make event handlers unbinding.

Client side code template based on RichFaces.ui.Base

This template uses RichFaces.ui.Base class as base. The template has been developed according functionality of the last release of RichFaces (4.0.Final). This template is preferable for visual components with attachment to DOM element by componentId(passed to constructor).

Note: RichFaces.BaseComponent template should be used instead If component needs to be attached to DOM element with another id(to element that inside or ouside of component’s parent DOM element).

(function ($, rf) {
           // Create (for example) ui container for our component class
           rf.ui = rf.ui || {};
          // Default options definition if needed for the component
          var defaultOptions = {};

          // Create constructor and register our component class
          rf.ui.MyClass = function (componentId, options) {
// call constructor of parent class
$super.constructor.call(this, componentId, options, defaultOptions);
// ...
};

// Extending component class
rf.ui.Base.extend(rf.ui.MyClass);

// define super class reference - reference to the parent prototype
          var $super = rf.ui.MyClass.$super;

          // Add new properties and methods via extending MyClass.prototype
$.extend(rf.ui.MyClass.prototype, {
// class name
name:"MyClass",
// private functions definition
// names of private methods should start with '__' (2 underscore symbols)
__privateFunction: function () {
          // ...
},
// $super can be used to call method from the parent class
__overrideFunction: function () {
          $super.__overrideFunction.call(this/*[, arguments]*/)
          // ...
},
// public API
publicFunction: function () {
          // ...
},
// destructor definition
destroy: function () {
          // define destructor if additional cleaning is needed but
          // in most cases its not nessesary.
          // call parent’s destructor
          $super.destroy.call(this);
}
});
})(jQuery, RichFaces);

Client side code template based on Richfaces.BaseComponent

This template uses RichFaces.BaseComponent class as base and extendClass for extending.
The template has been developed according functionality of the last release of RichFaces.

(function ($, rf) {
           // Create (for example) ui container for our component class
           rf.ui = rf.ui || {};
          // Default options definition if needed for the component
          var defaultOptions = {};


// Extending component class with new properties and methods using extendClass
// $super - reference to the parent prototype, will be available inside those methods
rf.ui.MyClass = rf.BaseComponent.extendClass({
// class name
name:"MyClass",
init: function (componentId, options) {
          // call constructor of parent class if needed
          $super.constructor.call(this, componentId);
          // attach component object to DOM element for 
// future cleaning and for client side API calls
this.attachToDom(this.id);
          // ...
},
// private functions definition
// names of private methods should start with '__' (2 underscore symbols)
__privateFunction: function () {
          // ...
},
// $super can be used to call method from the parent class
__overrideFunction: function () {
          $super.__overrideFunction.call(this/*[, arguments]*/)
          // ...
},
// public API
publicFunction: function () {
          // ...
},
// destructor definition
destroy: function () {
          // define destructor if additional cleaning is needed but
          // in most cases its not nessesary.
          // call parent’s destructor
          $super.destroy.call(this);
}
});

// define super class reference - reference to the parent prototype
          var $super = rf.ui.MyClass.$super;

})(jQuery, RichFaces);