THIS PAGE IS COMPLETELY OUT OF DATE AND WILL BE DELETED SOON

See CoreJS

This page describes some of the fundamental Echo3 APIs and JavaScript standards and conventions that should be used in client side scripting. Any Echo-library code referenced in this document is contained in the Core.js module.

The standards and libraries discussed in this document are applicable for any client-side Echo3 JavaScript coding work, be it creating a component synchronization peer, writing a FreeClient application, or any other use.

JSDoc

JSDoc comments should be used in API specifications. See http://jsdoc.sourceforge.net.

Namespaces

All JavaScript objects should be namespaced. To create a namespace, simply declare a function and declare other functions as member objects, for example:

SuperWidgetPack = function() { };

SuperWidgetPack.WackyWidget = function() {
    // constructor code.
};

SuperWidgetPack.WackyWidget.prototype.doSomething = function() {
    // instance method code.
};

The core framework libraries exist in namespaces which begin with the "Echo" prefix, e.g. EchoCore, EchoWebCore, EchoApp, or EchoRender. The "Echo" prefix should only be used by the core framework.

Private Objects

Private classes, methods, and objects should be prefaced with an underscore. Such variables should not be referenced outside of the file that defined them.

Deriving Objects

EchoCore.derive() has been deprecated and replaced with EchoCore.extend(). This documentation is out of date and should NOT be used. It will be updated soon.

The EchoCore.derive() method provides a convenient means of "safely" extending an object.

The traditional method for extending a JavaScript object is as follows:

TextLabel = function() {
   this.text = "Hello";
};

TextAndIconLabel = function() {
   this.icon = "Hello.png";
};

TextAndIconLabel.prototype = new TextLabel();

This method however has a notable issue: the instance variables of "TextLabel" will become static variables of "TextAndIconLabel".

Echo3 thus provides an EchoCore.derive() method which will eliminate any such static variables from the prototype of the derived class. The following example demonstrates the use of EchoCore.derive().

TextLabel = function() {
   this.text = "Hello";
};

TextAndIconLabel = function() {
   this.icon = "Hello.png";
};

TextAndIconLabel.prototype = EchoCore.derive(TextLabel);

The above code is not yet complete though (see next section, "Invoking super()").

Invoking super() Constructors/Methods

The function.call() method present in JavaScript can be used to invoke the super-implementation of a method or constructor. The following code adapts the previous example to properly call a superconstructor, such that our "TextAndIconLabel" will have its text appropriately set.

TextLabel = function() {
   this.text = "Hello";
};

TextAndIconLabel = function() {
   TextLabel.call(this);
   this.icon = "Hello.png";
};

TextAndIconLabel.prototype = EchoCore.derive(TextLabel);

Were TextAndIconLabel to take additional parameters, they could be added to the call method as well. The call() method may be used equally well to call overridden methods:

TextLabel.prototype.doXyz = function(x, y, z) {
   // Do some work.
};

TextAndIconLabel.prototype.doXyz = function(x, y, z) {
   // Call super implementation:
   TextLabel.prototype.doXyz.call(this, x, y, z);

   // Perform custom operations here.
};

Array Manipulation / Collections

The EchoCore.Arrays namespace provides convenience methods for manipulating arrays. Several methods allow the use of ".equals()" if it is present for determining equality, e.g., the remove() and indexOf() methods. Methods such as "removeDuplicates()" enable Java "Set" like behavior.

Between JavaScript's built-in indexed arrays, associative arrays, and the EchoCore.Arrays namespace methods, we have a fair amount of the fundamental capabilities of the Java Set/Map/List collections API.

Additionally the core provides a "LargeMap" object which works around performance issues in Internet Explorer's scripting engine. LargeMaps should be used when large numbers of items will be frequently added to and removed from a map that will exist for a long period of time. LargeMap's Internet-Explorer specific features are automatically disabled on other browsers. For more information on LargeMaps, see Echo3ClientScriptCoreLargeMap.

Method References

Method references may be used to create object-oriented callbacks. Such callbacks may be used when registering event listeners using other Echo API methods, or when using the "Scheduler" to run code in a new JavaScript context or at specified intervals. This removes the limitation of typical JavaScript event-listener callbacks which execute methods staticly, regardless of whether they are instance methods of a specific object.

Event Handlers

Echo provides a base event type and an event listener list object. If JavaScript methods are added as listeners in a listener list, they will be fired staticly. If Echo Method References are added, they will be invoked with the "this" pointer referencing the appropriate object instance.

Scheduler

The scheduler API should be used in place of window.setTimeout and window.setInterval() for creating background threads or threads which execute once the current script context has completed. This functionality is found in the EchoCore.Scheduler namespace. The scheduler API provides the capability to use method references.

Debugging Tools

The EchoCore.Debug namespace provides debugging and profiling tools. The most important method is likely EchoCore.Debug.consoleWrite(), which provides the capability to write arbitrary messages to a built-in debug console without interrupting the program flow. The debug console may be raised by pressing Ctrl+Alt+C (assuming the application has not been configured to disallow it).