Contributing Your Libraries

The things to watch out for are:

• Needing the HTML using your library to know about images or assets you've included
• Needing the domain to be the same (e.g. if you use IFRAMEs or createPopupWindow, you might need your libraries to sit locally, not hosted elsewhere (which isn't a big deal, it just means JSLoader will only be helpful if you deploy it locally in your server, rather than use it in "hosted" mode).
• Need any JS config provided before you load your scripts.. (such as BASE_PATH, or other similar variables).

Organizing the code:

The code assets should be placed under /assets/CATEGORY/PRODUCT/VERSION (e.g. /assets/ria/prettify/1.0/*). Once you're in that folder structure, it really doesn't matter how you organize your files (you get to simplify it when you make your package definition).

Creating the package files.

Once the files are in there, you can create "Package" files as follows:

1. Create a new folder at the same level as your VERSION folder above, but call this one "incr"
2. Inside "incr" create a folder called "versions" (in case there are other things in incr, like an /etc for config data, etc)
3. Inside "versions" create a js file with the version number you are deploying, (e.g. 1.0.js)

The purpose of this version number is to abstract away the required files for using your library.... In it, we can do 3 main activities:

1. Set/Get environment variables (setEnv and getEnv)
2. Load Javascript Files and Style Sheets
3. Generate the path prefix for a library, given it's category, name, and version number

Example

// Note a special method which will derive the path to use
// from the environment
// JSLoader.makePath(category,product,version);
// Let's work with the ria/prettify example above

// Sample 1.0.js
JSLoader.setEnv("PRETTIFY_PATH", JSLoader.makePath("ria","prettify","1.0"));
JSLoader.loadJavaScript(JSLoader.getEnv("PRETTIFY_PATH")+"prettify.js");
JSLoader.loadStyleSheet(JSLoader.getEnv("PRETTIFY_PATH")+"prettify.css");

This file would (and actually does) sit in /assets/ria/prettify/incr/versions/1.0.js

For more examples

Just view the Demos on our site using firebug and you'll see a x.y.js where x and y are numbers. View the source of those files to see how we abstract away the need to know where things are located.

Advanced: Sub-Packages

Sometimes you need to load sub-library functionality, like special effects, or "plugins". For this there's an additional function called a "Sub Loader" built into JSLoader

To use this, you'd write code like this:

Module.getLoader("ria","some_package","1.0").loadAll(["Some","array","of","features"]); 
// -or -
Module.getLoader("ria","some_package","1.0").load("one-feature");

These files would sit in /assets/CATEGORY/PRODUCT/incr/versions/VERSION/FEATURE.js

Whenever you use this sub loading feature, you get a "Free" environment variable setEnv'd for you, called (product_name.toUpperCase()+"_PATH");

For an example of this, take a look at the PlotKitDemo

-- DovKatz - 22 Oct 2007