Projects

Introduction goes here.

Namespaces

Although we haven't used them so far, namespace objects are recommended to avoid collissions in the global namespace, an invisible namespace that exists all around us.

var myns = window.myns || {};
myns.MySpirit = gui.Spirit.extend();

Spiritual comes with a formalized API for declaring namespace objects. You would usually do this in one of the first files so that the namespace is ready to be used.

gui.namespace('myns'); // create window.myns (if needed)

This declares the namespace as a property of window. It also returns the namespace object, so you can write it like this if your editor complaints that myns is not defined.

myns = gui.namespace('myns');

Some people like to declare constants and simple properties as part of the namespace declaration. I certainly do, since it's loaded first.

gui.namespace('myns', {
	LOCALHOST: '127.0.0.1',
	PUBLICHOST: '77.66.50.50'
});

When you are done adding members like spirits and plugins to the namespace object, there's a method you can call to name the members. We are not sure if this is supposed to be a manual step, but that's what it is for now.

myns.spacename();

This runs through the namespace members and updates the toString method. It also changes how things get logged in the console and displayed in the profiler. This might not quite work at the moment, but that's the idea.

alert(myspirit); // [object Anonymous]
myns.spacename();
alert(myspirit); // [object myns.MySpirit]

See what's up with issue 17356 nowadays.

Note on namespaces versus config-metatags.

Modules

Spiritual comes with an informal module concept. A module doesn't export methods in the sense of a conventional module, it's more of a convenient place to:

• Channel spirits to CSS selectors
• Assign plugins to all spirits
• Declare mixins for all spirits

You would usually load the module as the last file, having declared all the spirits and plugins that goes into it. Notice the identity token.

gui.module('mymodule@mycompany.com', {
	channels: [ // spirits for selectors
		["a, button", myns.ButtonSpirit],
		["#menubar", myns.MenuBarSpirit]
	],
	plugins: { // plugins for all spirits
		'number' : myns.NumberPlugin,
		'logger' : myns.LoggerPlugin
	},
	mixins: { // methods for all spirits
		example : function() {
			console.log('Great example');
		}
	}
});

You can check if a module is loaded.

gui.HasModule('mymodule@mycompany.com') // true

There's also some methods you can add as part of the module definition in order to:

• Do something now, or as soon as the module gets parsed
• Do something before we crawl the DOM in search for spirits
• Do something after onready has been fired for all spirits.

gui.module('mymodule@mycompany.com', {
	oncontextinitialize: function() { // TODO: rename this
		console.log('Runs immediately');
	},
	onbeforespiritualize: {
		console.log('Before any spirits');
	},
	onafterspiritualize: {
		console.log('All spirits ready');
	}
});

Finally we will note that the gui.module method returns something called a gui.Module that you can work with as an entity if needed.

myns.MyModule = gui.module('mymodule@mycompany.com', {
	credits: function() {
		console.log('My Module was created by My Company');
	}
});
window.onload = myns.MyModule.credits;