Inheritable constructor functions
JavaScript HTML

readme.md

can-construct

Build Status

Easily build constructor functions.

API

Construct.extend([name,] [staticProperties,] instanceProperties)

Extends Construct, or constructor functions derived from Construct, to create a new constructor function. Example:

var Animal = Construct.extend({
  sayHi: function(){
    console.log("hi")
  }
});

var animal = new Animal()
animal.sayHi();
  1. name {String}: Adds a name to the constructor function so it is nicely labeled in the developer tools. The following:

    Construct.extend("ConstructorName",{})
    

    returns a constructor function that will show up as ConstructorName in the developer tools. It also sets "ConstructorName" as shortName.

  2. staticProperties {Object}: Properties that are added the constructor function directly. For example:

    var Animal = Construct.extend({
      findAll: function(){
        return can.ajax({url: "/animals"})
      }
    },{}); // need to pass an empty instanceProperties object
    
    Animal.findAll().then(function(json){ ... })

    The static setup method can be used to specify inheritable behavior when a Constructor function is created.

  3. instanceProperties {Object}: Properties that belong to instances made with the constructor. These properties are added to the constructor's prototype object. Example:

    var Animal = Construct.extend({
    findAll: function() {
      return can.ajax({url: "/animals"});
    }
    },{
      init: function(name) {
        this.name = name;
      },
      sayHi: function() {
        console.log(this.name," says hai!");
      }
    })
    var pony = new Animal("Gertrude");
    pony.sayHi(); // "Gertrude says hai!"
    

    The init and setup properties are used for initialization.

  • returns {function}: The constructor function.

    var Animal = Construct.extend(...);
    var pony = new Animal(); // Animal is a constructor function

    constructorExtends {Boolean}

    Toggles the behavior of a constructor function called without the new keyword to extend the constructor function or create a new instance.

    var animal = Animal();
    // vs
    var animal = new Animal();

Boolean

Construct.newInstance([...args])

  1. args {*}: arguments that get passed to setup and init. Note that if setup returns an array, those arguments will be passed to init instead.

  • returns {class}: instance of the class

Construct.setup(base, fullName, staticProps, protoProps)

A static setup method provides inheritable setup functionality for a Constructor function. The following example creates a Group constructor function. Any constructor functions that inherit from Group will be added to Group.childGroups.

Group = Construct.extend({
  setup: function(Construct, fullName, staticProps, protoProps){
    this.childGroups = [];
    if(Construct !== Construct){
      this.childGroups.push(Construct)
    }
    Construct.setup.apply(this, arguments)
  }
},{})
var Flock = Group.extend(...)
Group.childGroups[0] //-> Flock
  1. base {}: The base constructor that is being inherited from.
  2. fullName {String}: The name of the new constructor.
  3. staticProps {Object}: The static properties of the new constructor.
  4. protoProps {Object}: The prototype properties of the new constructor.

shortName {String}

If you pass a name when creating a Construct, the shortName property will be set to the name.

String

constructor {Object}

A reference to the constructor function that created the instance. This allows you to access the constructor's static properties from an instance.

Object

construct.setup(...args)

A setup function for the instantiation of a constructor function.

  1. args {*}: The arguments passed to the constructor.

  • returns {Array|undefined}: If an array is returned, the array's items are passed as arguments to init. The following example always makes sure that init is called with a jQuery wrapped element:

    WidgetFactory = Construct.extend({
        setup: function(element){
            return [$(element)]
        }
    })
    
    MyWidget = WidgetFactory.extend({
        init: function($el){
            $el.html("My Widget!!")
        }
    })
    

    Otherwise, the arguments to the constructor are passed to init and the return value of setup is discarded.

construct.init(...args)

  1. args {*}: the arguments passed to the constructor (or the items of the array returned from setup)

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test