include() & namespace()

Matt Karl edited this page Jul 22, 2015 · 2 revisions

SpringRoll has two global functions for getting and setting class definitions (include() and namespace(), respectively). These methods are used throughout SpringRoll's codebase and are completely optional, but it's strongly recommended to use them in your own code.

##include()

Arguments

  • qualifiedClassName string The name of the class, including the full namespace.
  • required=true (optional) boolean If set to false, the function will not throw an error if it fails. This can be useful for including classes of optional modules or external components.

Returns

  • object|function Reference to the class definition or function.

External dependencies are defined at the top of a JavaScript classes for two important reasons: 1). It’s easier to identify the external dependencies without searching through the entire class (more maintainable) and 2). for classes that are used more than once, help improves minified size (better optimization). Consider the following example:

// Get the class using include()
var Loader = include(‘springroll.Loader’);

// Get the class using direct object reference
var Loader = springroll.Loader;

Both of these do the same thing, the difference is what happens when they fail. If the first one fails, it’s throws an error that says Unable to include ‘springroll.Loader’ because the code is not included or the class needs to loaded sooner. Whereas, the latter will set Loader to be undefined (assuming there’s a global springroll object). When you eventually call Loader.load() in your code, it’ll give you a method load is undefined error. A lot less helpful in fixing an issue that usually has to do with missing dependencies or build order.

Also, include() can be used to load an optional class by setting the second parameter to false.

// Won’t throw an error if the class isn’t found
var Loader = include(‘springroll.Loader’, false);

if (Loader)
{
	Loader.load(‘data.json’, function(result){
		// file loaded
	});
}

##namespace()

Arguments

  • qualifiedNamespace string The full path to the namespace. Don't include the window object as part of the namespace.

Returns

  • object Reference to the global object representing namespace string. If the object doesn't exist, it will be created.

namespace() is a convenience method for assigning classes to the global namespace on the window object. The advantage of using namespace() is that all the namespace objects are created so you don't have always worry if the namespace has been created or not. Compare the following examples:

// Assigning using the window
window.springroll = window.springroll || {};
window.springroll.createjs = window.springroll.createjs || {};
window.springroll.createjs.SomeObject = SomeObject;

// Or assigning using namespace
namespace('springroll.createjs').SomeObject = SomeObject;

##extend() Arguments

  • childClass function The class that should be extending the older class.
  • parentClass funtion|string Either the fully qualified class name (e.g., "springroll.Application") or the reference to the class if already included.

Returns

  • object The prototype for the new child class which extends the parent class.
var ParentClass = function(){};
var SubClass = function(){
	ParentClass.call(this);
};

// Without the use of extend
var p = SubClass.prototype = Object.create(ParentClass.prototype);

// Inheritance using extend
var p = extend(SubClass, ParentClass);

##mixin()

Arguments

  • instance Object The class that should be extending the older class.
  • mixinClass funtion|string Either the fully qualified class name (e.g., "springroll.Application") or the reference to the class if already included.

Returns

  • object The original instance object.
var instance = new Character();
mixin(instance, 'springroll.EventDispatcher');