The MathJax Object-Oriented Programming Model

MathJax uses an object-oriented programming model for its main components, such as the Input jax, Output jax, and Element jax. The model is intended to be light-weight and is based on JavaScript’s prototype inheritance mechanism. Object classes are created by making subclasses of MathJax.Object or one of its subclasses, and are instantiated by calling the object class as you would a function.

For example:

MathJax.Object.Foo = MathJax.Object.Subclass({
  Init: function (x) {this.setX(x)},
  getX: function () {return this.x},
  setX: function (x) {this.x = x}
});
var foo = MathJax.Object.Foo("bar");
foo.getX();                // returns "bar"
foo.setX("foobar");
foo.getX();                // returns "foobar"

Object classes can have static properties and methods, which are accessed via the object class variable. E.g., MathJax.Object.Foo.SUPER or MathJax.Object.Foo.Augment() for the object in the example above. Static values are not inherited by subclasses.

Static Properties

SUPER: Pointer to the super class for this subclass. (It is a reference to MathJax.Object in the example above.)

Static Methods

Subclass(def[, static])

Creates a subclass of the given class using the contents of the def object to define new methods and properties of the object class, and the contents of the optional static object to define new static methods and properties.

Parameters:

def — object that defines the properties and methods
static — object that defines static properties and methods

Returns:

the new object class

Augment(def[, static])

Adds new properties and methods to the class prototype. All instances of the object already in existence will receive the new properties and methods automatically.

Parameters:

def — object that defines the properties and methods
static — object that defines static properties and methods

Returns:

the object class itself

Properties

constructor: Pointer to the constructor function for this class. E.g., foo.constructor would be a reference to MathJax.Object.Foo in the example above.

Methods

Init([data])

An optional function that is called when an instance of the class is created. When called, the this variable is set to the newly instantiated object, and the data is whatever was passed to the object constructor. For instance, in the example above, the variable foo is created by calling MathJax.Object.Foo("bar"), which calls the MathJax.Object.Foo object’s Init() method with data equal to "bar". If desired, the Init() method can create a different object, and return that, in which case this becomes the return value for the object constructor.

Parameters:

data — the data from the constructor call

Returns:

null or the object to be returned by the constructor

isa(class)

Returns true if the object is an instance of the given class, or of a subclass of the given class, and false otherwise. So using the foo value defined above,

foo.isa(MathJax.Object);      // returns true
foo.isa(MathJax.Object.Foo);  // returns true
foo.isa(MathJax.InputJax);    // returns false

can(method)

Checks if the object has the given method and returns true if so, otherwise returns false. This allows you to test if an object has a particular function available before trying to call it (i.e., if an object implements a particular feature). For example:

foo.can("getX");  // returns true
foo.can("bar");   // returns false

has(property)

Checks if the object has the given property and returns true if so, otherwise returns false. This allows you to test if an object has a particular property available before trying to use it. For example:

foo.has("getX");  // returns true
foo.has("x");     // returns true
foo.has("bar");   // returns false

Accessing the Super Class

If a subclass overrides a method of its parent class, it may want to call the original function as part of its replacement method. The semantics for this are a bit awkward, but work efficiently. Within a method, the value arguments.callee.SUPER refers to the super class, so you can access any method of the superclass using that. In order to have this refer to the current object when you call the super class, however, you need to use call() or apply() to access the given method.

For example, arguments.callee.SUPER.method.call(this,data) would call the superclass’ method and pass it data as its argument, properly passing the current object as this. Alternatively, you can use this.SUPER(arguments) in place of arguments.callee.SUPER. It is also possible to refer to the super class explicitly rather than through arguments.callee.SUPER, as in the following example:

MathJax.Class1 = MathJax.Object.Subclass({
  Init: function(x) {this.x = x},
  XandY: function(y) {return "Class1: x and y = " + this.x + " and " + y}
});

MathJax.Class2 = MathJax.Class1.Subclass({
  XandY: function (y) {return "Class2: "+arguments.callee.SUPER.XandY.call(this,y)}
});

MathJax.Class3 = MathJax.Class2.Subclass({
  XandY: function (y) {return "Class3: "+MathJax.Class2.prototype.XandY.call(this,y)}
});

MathJax.Class4 = MathJax.Class1.Subclass({
  XandY: function (y) {return "Class4: "+this.SUPER(arguments).XandY.call(this,y)}
});

var foo = MathJax.Class2("foo");
foo.XandY("bar");   // returns "Class2: Class1: x and y = foo and bar"
var bar = MathJax.Class3("bar");
bar.XandY("foo");   // returns "Class3: Class2: Class1: x and y = bar and foo"
var moo = MathJax.Class4("moo");
moo.XandY("cow");   // returns "Class4: Class1: x and y = moo and cow"

Since both of these mechanisms are rather awkward, MathJax provides an alternative syntax that is easier on the programmer, but at the cost of some inefficiency in creating the subclass and in calling methods that access the super class.

Since most calls to the super class are to the overridden method, not to some other method, the method name and the call() are essentially redundant. You can get a more convenient syntax by wrapping the def for the Subclass() call in a call to MathJax.Object.SimpleSUPER(), as in the following example:

MathJax.Class1 = MathJax.Object.Subclass({
  Init: function (x) {this.x = x},
  XandY: function (y) {return "Class1: x and y = " + this.x + " and " + y}
});

MathJax.Class2 = MathJax.Class1.Subclass(
  MathJax.Object.SimpleSUPER({
    XandY: function (y) {return "Class2: "+this.SUPER(y)},
    AnotherMethod: function () {return this.x}              // it's OK if a method doesn't use SUPER
  })
);

var foo = MathJax.Class2("foo");
foo.XandY("bar");     // returns "Class2: Class1: x and y = foo and bar"