Home

tekool edited this page Jan 8, 2012 · 40 revisions
Clone this wiki locally

Description

Objs is a lightweight Javascript library intended to help in using namespaces and class inheritance in JavaScript. The minified Objs JavaScript library only weight 711 chars.

The project exists since 2006. It was successfully used on large and complex projects, including a "PureMVC" JavaScript port and has proved to be efficient and robust. It has been completely refactored in 2011 to follow recent and popular libraries syntax like ExtJs, Mootools or Prototype.

Objs avoids any compatibility problem with existing libraries like jQuery as it uses the only Objs namespace. It also voluntary doesn't pollute DOM nor native JavaScript objects prototypes with unwanted code.

Basics

Class declaration

/**
 * Create a constructor for the "HelloWorld" class using the
 * "myclasspath.myapp" namespace.
 */
var HelloWorld = Objs("com.example.helloworld.HelloWorld",
{
    /**
     * Declare a "message" class property.
     *
     * @type {String}
     */
    message: null,      

    /**
     * Declare an "initialize" method that will automatically be called on
     * class construct with the same parameters passed to its constructor.
     *
     * @param {String} message
     *      Add a message parameter that will be passed from the "HelloWorld"
     *      constructor to this method on construct.
     */
    initialize: function( message )
    {
        this.message = message;
    },

    /**
     * Declare a public giveMeHello method.
     */
    sayHello: function()
    {
        alert(this.message);
    }
});

When two different classes are registered twice with the same classpath, only the last registered is used.

Class instanciation

    //Get a reference to the HelloWorld class constructor.
    var HelloWorld = Objs("com.example.helloworld.HelloWorld");

    //Build an HelloWord class instance using JavaScript native "new" keyword.
    var helloWorldInstance = new HelloWorld("Hello, World!");

    //Displays an "Hello, World!" message alert.
    helloWorldInstance.sayHello();

Live HelloWorld example

Inheritance

/**
 * This creates a constructor for the "HelloName" class using the
 * "com.example.helloworld.HelloName" namespace and subclassing
 * "com.example.helloworld.HelloWorld" class.
 */
var HelloName = Objs( "com.example.helloworld.HelloName", "com.example.helloworld.HelloWorld",
{
    /**
     * Add an override to the "initialize" method of the HelloWorld class 
     * that will automatically be called on class construct with the same
     * parameters passed to its constructor.
     *
     * @param {String} name
     *      Add a name parameter that will be passed from the "HelloName"
     *      constructor to this method on construct.
     */
    initialize: function( name )
    {
        /*
         * As we override our superclass initialize method it is necessary
         * to call it on construct. This is how its made.
         */
        HelloName.$super.initialize.call( this, "Hello, " + name + "!" );
    }
});

//Build an HelloName class instance using JavaScript native "new" keyword.
var helloNameInstance = new HelloName("Ricky");

//Displays an "Hello, World!" message alert.
helloNameInstance.sayHello();

Note that in this example, subclassing is done using the classpath of the superclass as a string, but passing its constructor reference as parameter would have also been valid as we have created an "HelloWorld" var which is a reference to the "com.example.helloworld.HelloWorld" class constructor:

    var HelloName = Objs( "com.example.helloworld.HelloName", HelloWorld, { ... } );

Live HelloName example

Class removal

If for any reason you need to remove a class registered with Objs, only pass a strict null as second parameter. If Objs detained the last reference to it, the associated class object will be available for Garbage Collection.

Note that when removing a class, if found, Objs returns a reference to the class. You can use it to check if removal was successful and it also makes the API consistent as Objs always return a class type.

Example:

//Register a class with Objs
var HelloWorld = Objs("com.example.helloworld.HelloWorld", {});

//Remove a registered class from Objs, the class object is now available for Garbage collection
Objs("com.example.helloworld.HelloWorld", null);

Static properties

Static properties are added to the constructor Function object of the class you are declaring like this is often the convention in JavaScript frameworks. As Objs return a method constructor, this offers a simple way to use this reference to access the static property from the class declaration body like follows:

/**
 * This creates a reference to the constructor for "MyClass". This is the
 * reference to use to declare static properties.
 */
var MyClass = Objs( "com.example.MyClass"
{
    /**
     * Does something using our static property.
     */
    foo: function()
    {
        alert(MyClass.MY_STATIC_PROPERTY);
    }
});

MyClass.MY_STATIC_PROPERTY = "I'm static!"

Showcase

Documentation

Methods

Objs is a self-contained Function object, the only method it exposes is itself.

Its signature can be expressed in one line with :

function Objs( classpath, superclass|superclasspath|protobject, [protobject] );

The same thing expressed with an expanded list of methods overload would be:

/**
 * Return a class constructor using its unique classpath.
 *
 * @param {String} classpath
 *  The classpath of the class to retrieve.
 *
 * @throws {Error}
 *  An error is thrown if the class hasn't been registered with Objs.
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath );
/**
 * Create a class constructor using a unique classpath and associate
 * it methods and properties through its prototype.
 *
 * @param {String} classpath
 *  The classpath of the class to create.
 * 
 * @param {Object} protobject
 *  The object used to add class methods and properties.
 *  If the class only need to be static, only an empty protobject is needed
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath, protobject );
/**
 * Create a class constructor using a unique classpath and let it inherits
 * from a superclass.
 *
 * @param {String} classpath
 *  The classpath of the class to create.
 * 
 * @param {Function} superclass
 *  A superclass constructor to inherit from.
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath, superclass );
/**
 * Create a class constructor using a unique classpath and let it inherits
 * from a superclass.
 *
 * @param {String} classpath
 *  The classpath of the class to create.
 * 
 * @param {String} superclasspath
 *  The superclass classpath to inherit from.
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath, superclasspath );
/**
 * Create a class constructor using a unique classpath and let it inherits
 * from a superclass.
 *
 * @param {String} classpath
 *  The classpath of the class to create.
 * 
 * @param {Function} superclass
 *  A superclass constructor to inherit from.
 *
 * @param {Object} protobject
 *  The object used to add class methods and properties.
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath, superclass, protobject );
/**
 * Create a class constructor using a unique classpath and let it inherits
 * from a superclass.
 *
 * @param {String} classpath
 *  The classpath of the class to create.
 * 
 * @param {String} superclasspath
 *  The superclass classpath to inherit from.
 *
 * @param {Object} protobject
 *  The object used to add class methods and properties.
 *
 * @return {Function}
 *  The constructor method of the class corresponding to the given classpath.
 */
function Objs( classpath, superclasspath, protobject );

Properties

Any class constructor created using Objs will expose a new $classpath property.

Example:

var MyClass = Objs( "myclasspath.MyClass", {} );

alert( MyClass.$classpath ) //=> myclasspath.MyClass

Also any class constructor created using Objs will expose two new $superclass and $super properties.

Example:

var MySuperClass = Objs( "myclasspath.MySuperClass", {} );
var MySubClass = Objs( "myclasspath.MySubClass ", "myclasspath.MySuperClass" );

alert( MySubClass.$superclass === MySuperClass ) //=> true
alert( MySubClass.$super === MySuperClass.prototype ) //=> true

Those properties will not pollute instances of classes created using Objs as they are only accessible on class constructor itself. Just be careful not to use static properties named against $classpath, $super or $superclass.

Error handling

Invalid classpath

The first Objs(classpath) parameter must always be a string representing a classpath. If anything else is passed as first parameter for the Objs method, an error will be thrown.

Unexistent class

An error will be thrown if an unregistered class try to be retrieved.

Unexistent superclass

An error will be thrown if a class try to inherit from an unexistent superclass or try to use an invalid superclass or superclasspath parameters.