Using Gloader
----

Overview
====

Gloader is a JavaScript module loader that was create as part of the BBC Glow project. It can however be used with any JavaScript library that follows the same Glow module pattern.

Gloader's Idea of a "Module"
====

JavaScript does not intrinsiclly support code modules, but we can define our own modules in code. Basically we are striving to have a chunk of related code in a self-contained package, a "module". Module need to describe themselves with some meta information, including: what library they belong to, which version number describes them, and what other modules they depend on. Finally a module needs to define some function that when executed will create the module object; this function is called the "builder".

Gloader's Idea of a "Library"
====

A group of related modules are held together under a single library. In fact the library is itself a module, but what makes it unique is that it can contain other modules. Every library must have exactly one library module.

An Example of a Library Module
====

As explained previously a library is actually a special kind of module, and you must have exactly one library module. Bearing that in mind, when creating a library you should start with the library module. It will follow a pattern that looks like this:

    gloader.library({
		name: "myLibrary",
		version: "1.0.0",
		builder: function () {
			// this is where you create your library module
			var myLibrary = {}; // <-- can be anything
			
			return myLibrary;
		}
	});

It is conventional that you use a variable-like name for your library but in fact the `name` can be any string: It can contain any combination of characters except for the forward-slash character "/", which has special meaning to gloader.

Likewise the `version` identifier is be a string that can contain any chraracters except for the forward-slash. however if you follow the convention of using a pattern like: `<int>.<int>.<int>` you will gain special functionality from gloader in which it can automatically manage version updates for you (this is discussed further on).

The `builder` function actually creates your library module. You can execute any code you like inside the builder, but it is recommended that you create a function scoped object, by using the `var` keyword as shown, and then returning a reference to it at the end of the builder. Following this pattern will allow gloader to "sandbox" your library so that people can eventually have multiple versions of a single library defined on the same page.

Notice that there are no dependencies defined. That's becuase a library is expected to stand alone: it cannot be dependednt on any other library or module to run.

An Example of a Module
====

Once you have a library you can attach modules to it. The process of defining a module is very similar to that of a library:

	gloader.module({
		name: 'myLibrary.myModule',
		library: ['myLibrary', '1.0.0'],
		
		builder: function(myLibrary) {
			myLibrary.myModule = {};
		}
	});

The differences are that a module must define what library (lbrary name and library version) it belongs to. Notice that a module does not have it's own version identifier, instead modules always inherit their vesrions from their library. Therefore this module, named "myLibrary.myModule", is version "1.0.0".

As with the library module definition, the module definition has a builder function, however the builder for a module will always receive a single argument: the same object returned by the library's builder. This, presumably, will be the library object and you can then attach your module to that object.

Dependencies
====

Any module definitio can optionally list other modules as dependencies. For example, if you were to define a second module that depended on the module we defined in the previous section, it would be written like so:

	gloader.module({
		name: 'myLibrary.myOtherModule',
		library: ['myLibrary', '1.0.0'],
		depends: [
			['myLibrary', '1.0.0', 'myLibrary.myModule']
		],
		
		builder: function(myLibrary) {
			myLibrary.myOtherModule = {};
		}
	});

The `depends` option is an array of arrays: the inner arrays define the dependent library name, library version, and zero or more modules from that library. Variations on that woulr be written like so:

	// only need the library
	depends: [
		['myLibrary', '1.0.0']
	]
	
	// need several modules from the same library
	depends: [
		['myLibrary', '1.0.0', 'myLibrary.myModule', 'myLibrary.Etc']
	]
	
	// several modules from the several libraries
	depends: [
		['myLibrary', '1.0.0', 'myLibrary.myModule', 'myLibrary.Etc'],
		['otherLibrary', '1.2.0', 'otherLibrary.myModule', 'otherLibrary.Etc']
	]
