Modules

Bases of the notation:

Archetype uses a handy notation in order to be able to identify easily each files needed by the application, using modules . By default, each module is equivalent to a file. However, if your using file bundles, each of this bundle can represent multiple modules.

The main notation is inspired by the "Java package" notation. The idea is to replace folder separators ("/" in URLs) by a simple dot ".". You can use either a slash based notation (url notation) or dot based notation (module notation) in order to refer to an url in Archetype.

Please note that in path notations, in order to replace "." in file and directory names(it's quite uncommon), as this would be interpreted as a "/", you have to use "#" instead The scriptaculous library is delivered in a script.aculo.us directory as an example of this functionnality: this is expressed in the configuration by script#aculo#us.

By default, all of the locations are relative to the location of the archetype.js file. Eventually, this default setting can be overridden using the modules configuration.

Using Archetype.modules configuration:

The namespace Archetype.modules allows user to simplify or enhance the dependency management.

Each keys of the HashMap defines a module name or a part of a module name. In order to get a module path, Archetype will get settings from the hole hierarchy of your file, the more precise, the highest priority in configuration: if you do some path configuration for "foo", some other for "foo.baz", then you want to load "foo.baz.foobar" and have no particular path configuration for "foo.baz.foobar", then the configuration of "foo.baz" will be taken into account, adding just "foobar" to this path configuration. Have a look at the configuration file below, it's quite natural.

Only path configuration (aPath and rPath) are affected by this strategy. Both needs and subModule are used only if asking for the particular path you have configured them to.

Some modules configuration are bundled by default in the Archetype distribution. It defines simple notations for all of the standard libraries used by Archetype.

It's advised not to change (until you perfectly now what you do) the configuration made by default for Archetype modules, but you can (and you'll probably want to, if you're planning to include some other libraries for your development) append new lines to this configuration for your own needs (creating aliases, defining a file dependencies, etc.).

Here is the standard configuration :

Archetype.modules = {
	/**
	 * Possible options:
	 * - aPath: absolute path for the file
	 * - rPath: relative path from Archetype path to the javascript files
	 * - subModules: Use it to include multiple files at once with a common denomination,
	 *               arranged like subclass of a class path.
	 *               Example: "scriptaculous" embeds the core "scriptaculous.core",
	 *               the builder "scriptaculous.builder", etc.
	 * - needs: Use it for loading files before the one defined /!\ incompatible with subModules at the same time.
	 */

     /** Bootstrap dependency : no support for needs or submodule **/
	//-- Prototype related
    'Archetype.libs.prototype':{rPath:"Archetype.libs.prototype.1#6#0#3"},
    //-- Comment this out in order to use Google CDN for delivering the file
    //'Archetype.libs.prototype.prototype':{aPath:"http://ajax.googleapis.com/ajax/libs/prototype/1.6.0.3/prototype"},
    //--

    //-- jQuery related
    'Archetype.libs.jQuery':{rPath:"Archetype.libs.jQuery.1#3"},
    //-- Comment this out in order to use Google CDN for delivering the file
    //'Archetype.libs.jQuery.jquery':{aPath:"http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js"},
    //-- or this one if you want to debug (bigger)
    //'Archetype.libs.jQuery.jquery':{aPath:"http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.js"},
	'Archetype.libs.jQueryEnumerable':{rPath:"Archetype.libs.jQuery.enumerable.jquery#enumerable"},

    /** Implementation dependencies, these can use needs (they aren't transitive however) but not subModules **/
    //-- engines dependencies
	"Archetype.engine.jQueryEngine":{needs:["Archetype.libs.jQuery.jquery", "Archetype.libs.jQueryEnumerable"]},
	"Archetype.engine.prototypeEngine":{needs:["Archetype.libs.prototype.prototype"]},
	//--

    //-- logger related
	'log':{rPath:"Archetype.log"},
	'Archetype.log.nullLogger':{rPath:"Archetype.log.abstractLogger"},
	'Archetype.log.piDebuggerLogger':{needs:["Archetype.libs.pidebugger.SOURCE.pi", "Archetype.libs.pidebugger.SOURCE.debugger"]},
    //--
    /** End of Bootstrap dependencies, you can use needs or subModules**/

    //-- components related
	'Archetype.component':{
			subModules:["abstractComponent","componentManager"],
			needs:["Archetype.Joiners"]},
	'Archetype.component.componentManager':{needs:["Archetype.component.facetManager"]},
	'Archetype.component.facetManager':{needs:["Archetype.component.facets"]},
	'Archetype.component.facets':{subModules:["logFacet","scopeFacet","eventListenerFacet","eventSenderFacet","observeFacet"]},
	'Archetype.Joiners':{needs:["Archetype.Class"]},
    //--

    //-- templates related
	'Archetype.template.talTemplate':{needs:["template.abstractTemplate", "Archetype.libs.tal.domtal"]},
	'Archetype.template.trimpathTemplate':{needs:["Archetype.template.abstractTemplate", "Archetype.libs.jst.trimpath-template"]},
	'Archetype.template.ejsTemplate':{needs:["Archetype.template.abstractTemplate", "Archetype.libs.ejs.ejs_production"]},
	'Archetype.template.regexpTemplate':{needs:["Archetype.template.abstractTemplate"]},
	//--


	//-- Scriptaculous related
	'scriptaculous':{rPath:"Archetype.libs.script#aculo#us", subModules:["builder","controls","dragdrop","effects","slider","sound"]},
    //-- Comment this out in order to use Google CDN for delivering the file
    //'Archetype.libs.script#aculo#us':{aPath:"http://ajax.googleapis.com/ajax/libs/scriptaculous/1.8.2"},
    //--
	'scriptaculous.controls':{needs:["scriptaculous.effects"]},
	'scriptaculous.dragdrop':{needs:["scriptaculous.effects"]}
};
			

For each keys of the HashMap, there are different kind of options:

aPath : absolute path to the file. This can be any kind of url, including external servers for at least JS and CSS files. We advise to use an URL Notation for aPaths.

rPath : relative path from Archetype path to the file. We advise to use a Module Notation for rPaths.

subModules : Use it to include multiple files at once using a common denomination, Particularly useful with multple files libraries. This is a bit like defining an "import my.package.*" in Java.

Example :

• "scriptaculous" will load the library including all of it submodules.
• "scriptaculous.builder", the builder module
• "scriptaculous.sound", the sound module
• etc.

needs : Use it for loading some modules before the one defined. It's the good way to define dependencies between modules.

Example :

• "scriptaculous.controls", needs "scriptaculous.effects" in order to work. Thanks to the "needs" configuration, the latter file will always been loaded before controls, which avoid stupid JavaScript errors.

Archetype.defaultModules for loading some modules by default:

To use Archetype with all it's functionalities, you have to keep at least the default values:

							
Archetype.defaultModules = ["Archetype.component"];
			

In order to load any module before the start of your page, for all applications using this configuration, then you just have to add the module name you want in the list.