NAME
Class - A Lightweight JavaScript Class System
SYNOPSIS
Class('Foo.Bar', function() {
... your code here ...
});
DESCRIPTION
JavaScript has no standard way to define a "class". (Even though
JavaScript is prototype based OO, it is still easy to think of objects
in terms of classes).
Class.js defines a very minimal set of structure and helpers without
forcing you to change your coding style drastically. It's goal is to
work with many styles of coding but also to give a clear way to to the
basic best practices.
Class.js provides these simple, useful features:
* Insertion of your class (Foo.Bar.Baz) into the global namespace.
* A contained scope for your class.
* Single inheritance.
* Declaration of local class variables. Like '$' for jQuery.
* A way to define instance methods.
* A clean way to call 'super' methods.
* Strict evaluation of your code. New global variables raise an exception.
* A safe way to introduce global variables if you need to.
* A way to disable strict evaluation altogether.
* 'this' is a pointer to your class object within the scope of your class.
* 'this.global' is a portable replacement for 'window'.
* Class object contains helpful properties like: className & baseclassName.
AN EXAMPLE CLASS
Here is a more complete example with full explanation:
// - Class is a function that gets called during "compile time" and
// defines the class.
// - Class takes two arguments:
// - A Class Definition string
// - A Class Wrapper function
// - 'Foo.Bar' is the name of the class. This adds the global variable
// 'Foo', if necessary, and defines 'Bar' under that.
// - The 'Foo' in parentheses is the name of the parent class. This is the
// way to declare inheritance.
// - The remaining parameters are options that begin with a '-'.
// - '-strict' makes sure global variables aren't accidentally defined. It
// is described in detail below.
// - '-inc' is a list of variables that are passed to the wrapper function
// as a clean way to defined local class variables.
// - The function here is a class wrapper. It provides the lexical scope
// for the class. This function is called immediately after the class is
// created.
// - The '$' is the jQuery constructor, which was declared by -inc.
Class('Foo.Bar(Foo) -strict -inc=jQuery', function($) {
// - As a style convention, the first level under the wrapper function is
// not indented.
// - 'this' (in the wrapper function context) is a pointer to the new
// class object being defined.
// - Here we use it to define
this.version = '1.0.0';
// - Or define a class function.
this.cleanup = function() { ... };
// - 'this.global' is a pointer to the global namespace. It is more
// portable than 'global'.
var myClass = this.global.Foo.Bar;
// - Any functions you define in the class are automatically private to
// the scope of the class wrapper function. Yay!
function private1() {
}
// - Any variables declared with 'var' are lexical to the wrapper class.
// Yay!
var foo = 123;
// - Any variables declared without 'var' are accidentally global. Boo!
// But -strict will catch these for you. Yay!
bar = 456;
// - Sometimes you really want to add a global variable. No problem. Just
// declare your intent and -strict will be happy. Yay!
this.addGlobal().baz = 789;
// - 'this.extend' is a simple way to add methods and properties to your
// class. Technically they are added to your class prototype, so they
// become instance properties. 'extend' can be called more than once.
this.extend({
method1: function() { ... },
method2: function() { ... }
});
// - You can also add methods and properties directly, of course, doing
// something like this:
this.prototype.method3 = function() { ... };
// - Don't forget to close the wrapper function and the call to Class.
// You may want to add a comment so this line makes more sense to casual
// readers.
}); // END Foo.Bar
OPTIONS
This section describes the options available to a Class Definition
string.
-strict
-strict tells Class to count the number of global variables before
and after class creation. It throws an error if you add new globals
(without using the special this.addGlobal() function).
-strict is on by default. Use '-nostrict' to disable it.
-nostrict
Don't do -strict processing when creating a class.
-inc=value1,value2
This option defines a list of important variables that you want
passed into your class wrapper as lexical variables. This is mostly
sugar, but it puts all the important information about your class in
the first line:
For instance:
Class('Foo.Bar(Foo) -inc=jQuery,prototype,this', function($, proto, klass) { ...
Could be written completely in code like this:
Class('Foo.Bar', function() {
this.isa('Foo');
var $ = jQuery;
var proto = this.prototype;
var klass = this;
...
The -inc is a comma separated list of values. A couple of these
values are special:
- this: A pointer to the current class object.
- proto: A pointer to the surrent class prototype object.
Anything else is a global variable.
CLASS OBJECT PROPERTIES
Your class (pointed to by 'this' in your wrapper function) has a few
handy properties:
this.superFunc('methodName')
Return the super class method as a function reference. Typically call it
like this:
this.superFunc('method').apply(this, arguments);
this.className
The name of your class. ('Foo.Bar')
this.baseClassName
The name of your base class. ('Foo')
this.global
A pointer to the global namespace object. Usually 'window' in a browser
environment.
this.addGlobal()
A function that increments the expected global count for -strict, and
then returns the 'global' pointer.
this.isa(parentClassName)
Sets up inheritance manually.
AUTHOR
Ingy döt Net <ingy@cpan.org>
COPYRIGHT
Copyright (c) 2009. Ingy döt Net.
This program is free software.