´óÏó´«Ã½

Introduction

Gloader is currently available as an alpha release.

Whilst it is used across , you may encounter problems configuring and using it in other environments. For now we advise you to use it only if you enjoy debugging JavaScript loading issues.

Most users will be best served loading Glow via the standard script tag method.

Overview

Gloader is a JavaScript loader with the following features.

• Allows multiple versions of the same library to exist separately on the same page at the same time: you never need to worry about another developer overwriting a specific version of the library that you rely on.
• Manages dependencies automatically: you only specify the JavaScript module you want to use, Gloader works out all the files which need to be loaded to make that module usable.
• Handles version upgrades transparently: you request either the exact version you need (like "1.2.3-rc3") or a general version (like "1") and Gloader will automatically deliver the latest available version that matches your request.

Terminology

The following terms are relevant to the use of Gloader:

module

A distinct JavaScript object that encapsulates a set of related features and functionality. Examples: glow.dom and glow.widgets.Panel are both modules.

library

A top-level (though not necessarily global) JavaScript object that contains one or more modules. Example: the glow library contains the glow.dom module.

dependency

When one module uses another module, that other module is a dependency of the first module. Example: the glow.widgets.AutoSuggest module depends on the glow.events and glow.widgets.Panel modules.

version

A library will exist in one or more versions. All the modules in the library share that same version identifier. The usual format of a version identifier is {major}.{minor}.{bugfix}. Example: if you wish, you may use the glow library version 1.0.0 or version 1.5.0.

library map

When requesting a module via Gloader, you only specify the name and version of the module you want. Internally Gloader uses a library map to find the related files that contain the code to define that module. Example: Gloader uses the glow library map at glow/map.js to find the related files when you request glow.dom, version 1.

Installation

You can download the latest version of Gloader from the Downloads section.

The gloader object is defined in a single file named gloader.js. This file must be saved to the same web server directory where you keep your JavaScript libraries. The usual set up is illustrated below:

webdocs/
        index.html
        scripts/
                gloader.js
                glow/
                     map.js
                     1.0.0/
                     1.1.0/
                     1.2.0/
                mylib1/
                mylib2/

By default Gloader expects your library folders to be located at the same level as the gloader.js file itself. With the set up illustrated in the example above, Gloader could be used to manage the glow library and two addition libraries. To do so you would include the gloader.js script in index.html and configure it to load Glow modules by adding the following simple tag near the top of your web page:

<script type="text/javascript" src="scripts/gloader.js"></script>

Using non-standard file paths

In the previous section we described the "usual" folder structure in which to keep Gloader and the glow library. The benefit of using this structure is that Gloader will automatically find all the files necessary to load glow modules, however you may want (or have) to use a different folder structure. In these cases you will have to explicitly tell Gloader where to find things.

<script type="text/javascript" src="scripts/gloader.js">
    gloader.use(
        "glow",
        {
            map: "/my/path/to/glow/map.js",
            base: "/my/path/to/glow/{$version}"
        }
    );
</script>

In this example we use a pattern called the "Degrading Script Tag" discussed by John Resig to include the gloader.js file and also configure the gloader object to look for the glow modules at the filepath: /my/path/to/glow/{$version}. The placeholder {$version} will automatically be replaced by Gloader with whatever the requested version number is, so if the user requests Gloader to load a module with version number "1.2.3", Gloader will look for that module below the base directory: /my/path/to/glow/1.2.3/.

Note that the base will be prepended to the file paths of the requested modules, so you can actually set the base to be any valid URL-like string, for example:

<script type="text/javascript" src="scripts/gloader.js">
    gloader.use(
        "glow",
        {
            map: "http://example.com/glow/map.js",
            base: "http://example.com/cgi-bin/getGlow?v={$version}&mod="
        }
    );
</script>

In this case, if the Gloader were requested to load version 1.5.0 of the glow.dom module, it would construct the following URL:

http://example.com/cgi-bin/getGlow?v=1.5.0&mod=glow/glow.js

The path to the file containing the glow.dom module (in this case glow/glow.js) comes from the glow library map. Each library will provide it's own map to allow Gloader to correctly find the corresponding file for the requested module. Generally speaking a library's map should not be edited by the end user.

Using other libraries

It should be apparent that Gloader will work perfectly well without glow and can be used to load any library that follows the conventions of a library map and JavaScript modules. As detailed above, by following the usual file structure Gloader will automatically find all the required files to load your modules. Simply give the folder containing your library files the same name as your library, and put version-number folders below that. For example, if your library were named "jsuperfun", use this layout:

webdocs/
        index.html
        scripts/
                gloader.js
                jsuperfun/
                          map.js
                          0.0.1/
                          0.0.2/

And the correct tag to add gloader to the index.html page would be:

<script type="text/javascript" src="scripts/gloader.js">
    gloader.use("jsuperfun");
</script>

Similarly, you can put the map and the module files for your own library in non-usual places, as long as you tell glaoder about it:

<script type="text/javascript" src="scripts/gloader.js">
    gloader.use(
        "jsuperfun",
        {
            map: "wherever/map.js",
            base: "anywhere/jsuperfun/{$version}/"
        }
    );
</script>

Multiple libraries, versions and gloaders?

A basic requirement of Gloader is to be able to manage multiple versions of the same library in a single web page. For that reason Gloader will always correctly handle multiple versions of the same library.

But no matter how many times the SCRIPT tag for the gloader.js file appears on a page, only the first tag will have any affect. In this way Gloader follows the 'singleton' pattern, in that once it is created you cannot create a second instance, so it is never possible to have more than one gloader on a page.

It is possible however to use Gloader with more than one library at a time. Assuming you've included gloader as previously described, you can then use additional libraries by including additional gloader.use() calls in separate SCRIPT blocks. For example, to use a second library, after gloader was already added to the page, you would add a new SCRIPT block like so:

<script type="text/javascript">
    gloader.use(
        "mySecondLibrary",
        {
            map: "wherever/map.js",
            base: "anywhere/mySecondLibrary/{$version}/"
        }
    );
</script>

Note that we used an ordinary SCRIPT block there, with no src attribute.

Loading modules

Once you've met the prerequisite described above you can start using Gloader to load library modules. This section mainly describes loading Glow modules, but the techniques should be transferable to other libraries.

For example, to load the glow.anim module from the glow/1.1.0 library, you would use a statement like this:

<script type="text/javascript">
    gloader.load(
        ["glow", "1.1.0", "glow.anim"],
        {
            async: true,
            onLoad: function(glow) {
                // use glow here
            }
        }
    );
</script>

As shown in the code above, the call to gloader.load() can take two different types of arguments: one or more modules you want to load, and an optional final argument that defines some options for the load.

Specifying modules

The general format for specifying modules to load is:

["libraryName", "libraryVersion", "moduleName"]

This is an array of strings specifying what library, library version and modules you want to use.

Note that you can have zero, one or many module names in the array, so this would be valid:

["glow", "1.1.0"]

And this would also be valid:

["glow", "1.1.0", "glow.anim", "glow.dom", "glow.net"]

In the first case you would get just the core glow module, which acts as the base of the Glow library. In the second case you would get that same core module plus three other modules. Note that if any modules you request depend on additional modules, those additional modules will automatically load as well, so there is no need to explicitly request the dependencies yourself.

Glow module names

• glow
• glow.anim
• glow.data
• glow.dom
• glow.dragdrop
• glow.embed
• glow.events
• glow.forms
• glow.net
• glow.tweens
• glow.widgets
• glow.widgets.Carousel
• glow.widgets.Editor
• glow.widgets.InfoPanel
• glow.widgets.Mask
• glow.widgets.Overlay
• glow.widgets.Panel
• glow.widgets.Slider
• glow.widgets.Sortable
• glow.widgets.Timetable

Specifying version numbers

The Glow library uses a three-part version number, like so: major.minor.bugfix. If you know you require an exact, specific version, such as "1.1.0", you can use the full three-part number in your load request. However, in cases where you want a specific major version but just the latest minor version, you may request just the major number, and Gloader will automatically load the latest minor version available.

For example if you request:

["glow", "1"]

You will get the latest version with "1" as a major release number, for example "1.2.3". Similarly if you request a two part version, giving the major and minor numbers, you will automatically get the latest bug fix release.

Other options

The final argument passed to the gloader.load() call can be an object that specifies the load options. The possible properties of that object are:

• onLoad: A function that will be called by Gloader once all the requested modules are available for use.
• onTimeout: A function that will be called by Gloader if all the modules you requested are not done loading before the timeout period expires.
• timeout: The number of milliseconds to wait before calling the onTimeout function (if one is defined). The default is 20 seconds.
• async: A true or false switch to signal whether the load should be asynchronous or not. The default is false, that is it will be synchronous.

The onLoad option

You can define a function that will be called when all the modules you requested become available for use. This function will be called automatically by Gloader and the arguments passed into this function will be all the libraries you've requested.

So if you request modules from the glow/1.1.0 library, the argument passed into your onLoad function will be that version of that library:

gloader.load(
    ["glow", "1.1.0", "glow.anim"],
    {
        onLoad: function(glow) {
            // access the glow/1.1.0 library as 'glow' here
        }
    }
);

Note that in JavaScript all function parameter variables are scoped to their function, so your onLoad function becomes a "sandbox" for your particular version of glow passed in as an argument. A second gloader.load call elsewhere on the page for a different version of glow will not interfere with this call in any way.

Using the glow parameter in the onLoad function

Generally gloader will pass each of the libraries you requested, in the order that you requested them, into your onLoad function. You can declare your own parameter list in your onLoad function but, because the Glow library refers to itself internally as 'glow', it is expected that the parameter for the Glow library be named 'glow' exactly.

The onTimeout and timeout options

You can define a function that will be called if too much time passes before all the modules you requested become available for use. If this function is called by Gloader the onLoad function (if there is one) will be cancelled at the same time, so it is not possible for both the onLoad and onTimeout functions to fire during the same load request: either one or the other will ever be allowed to fire.

The amount of time that will pass before the onTimeout function will fire is controlled by the timeout option, which allows you to specify the number of milliseconds that gloader will wait. The default value is 20000 which is equivalent to 20 seconds.

The async option

By default Gloader will load modules synchronously, that is in a way that will block page rendering. Note that you can only do synchronous loading while the page is still being rendered. Trying to do synchronous loading after a page is fully displayed will result in an error.

If you require asynchronous loading, that is in a way that won't block page rendering while the requested module is finished loading, you can set the async option to true. This style of loading is more flexible than synchronous loading, and can even be used after a page has already finished rendering, for example in response to a button being clicked by a user.