Getting Started

Getting Started

The lsjs AMD loader will load modules from a local storage implementation. By default the loader will use HTML5 localStorage however other implementations (WebSQL and IndexedDB) can be configured provided they follow the storage API. See Storage Implementation Spec for details

Usage

<script type="text/javascript" src="lsjs.js"></script>
<script>
    lsjs({..configuration options see below...}, ["my/module"], function(myModule) {
        .....
    });
</script>

or

<script type="text/javascript" src="lsjs.js"></script>
<script>
    var lsjsConfig = {..configuration options see below...};
    lsjs(["my/module"], function(myModule) {
        .....
    });
</script>

lsjs can be called in the following ways :

• Configuring

  lsjs({baseUrl: "/my/base/path"});

• Loading

  lsjs(["my/Module"]);

• Configuring and loading

  lsjs({baseUrl: "/my/base/path"}, ["my/Module"]);

• Loading and providing a callback

  lsjs(["my/Module"], function(myModule){ } );

• Configuring, loading and providing a callback

  lsjs({baseUrl: "/my/base/path"}, ["my/Module"], function(myModule){ } );

Note you can replace the lsjs entry-point name with require

Configuration

The following are available configuration options :

• baseUrl Root path used to locate modules. Defaults to "./".
• timestampUrl URL value indicating the timestamp checker to be used. See Timestamp Checking Protocol for details on the protocol, Using the nodejs Timestamp Checker and Using the Java Servlet Timestamp Checker for example server implementations.
• forceLoad Force the loader to always load via XHR. Useful if no timestamp checking server component is configured and the loadStorage must be cleared. Defaults to false
• injectViaScriptTag By default modules are injected via eval. This option enables the injection via script tags.
• paths Path mappings via name/value pairs.
• packages An array of package objects, each of which contain a "name", "location" and "main" property. The "name" is used for module name/prefix mappings, the "location" is the real path and the "main" property is the name of the module substituted when the package name is a dependency. "location" is optional, it defaults to the "name" value if not provided. "main" is also optional and like "location" defaults to the "name" value if ommited.
• storageImpl Storage Implementation that follows the Storage Implementation Spec. When specified this storage implementation will be used instead the default (HTML5 localStorage).
• usesCache An array of plugin module ids that can take advantage of the provided cache. For example the dojo/text plugin uses require.cache to attempt to obtain cached text values. require.cache is set to point to the lsjs cache object that contains a map of urls to values.

require.ready

The scoped require object passed to modules currently contains a "require.ready" function that can be used to be notified when the DOM has completed loading (It listens for "DOMContentLoaded" events). The caller passes in a callback function that will be called when the DOM load is complete.

Note this API is not part of the AMD spec. If you are planning on using Dojo then it is recommended that you add a dependeny to the dojo/domReady (depend on a module id of "dojo/domReady!") plugin instead of using require.ready.

Example Dojo 1.7 usage

The lsjs loader supports loading Dojo 1.7 AMD modules. (It should be noted that to do this the loader has to support unspec'd API's for the require object passed as a dependency).

<script type="text/javascript" src="lsjs.js"></script>
<script type="text/javascript">
    lsjsConfig = {
        timestampUrl: "./checktimestamps",
        usesCache: ["dojo/text"],
        packages: [
            {
                name: 'dojo',
                location: 'js/dojo'
            },
            {
                name: 'dijit',
                location: 'js/dijit'
            },
            {
                name: 'dojox',
                location: 'js/dojox'
            }
        ]
    };
	 
    lsjs(["amdtest/Calendar"]);
</script>

The above demonstrates first configuring the lsjs loader and then calling to load a module.

Timestamp Checking Server Component

If the "timestampUrl" configuration property is specified the loader will attempt to use it to obtain timestamp information on the modules it currently knows about. For each page load the "timestampUrl" is POSTed an array of objects in JSON. Each object contains a "url" property and a "timestamp" property containing a date string. The called server is expected to check each url's timestamp and if different return the url in an array of strings back to the lsjs loader. The lsjs loader will load these modules via xhr and update the stored value in local storage.

I provide both a java based servlet implementation that can be used in JEE Web Applications and a nodejs server implementation example however the protocol spec is very simple and can be easily supported in other server-side environments. See Timestamp Checking Protocol for details on the protocol, Using the nodejs Timestamp Checker and Using the Java Servlet Timestamp Checker for example server implementations

Notes on localStorage usage

The Local Storage implementations that most browser provide have a limit of 5 MB of storage per domain.

If the localStorage limit is reached the lsjs loader will still load the modules via XHR requests. You should see console log messages like :

Failed to set value in local storage ["+key+"] : ...