Interface

Loader

ilib.Loader

Defines the interface for the loader class for ilib. The main method of the loader object is loadFiles(), which loads a set of requested locale data files from where-ever it is stored.

Methods

# isAvailable() → {boolean}

Return true if the file in the named path is available for loading using this loader. The path may be given as an absolute path, in which case only that file is checked, or as a relative path, in which case, the relative path may appear underneath any of the directories that the loader knows about.

View Source ilib.js, line 640

true if the file in the named path is available for loading, and false otherwise

boolean

# listAvailableFiles() → {Object}

Return all files available for loading using this loader instance. This method returns an object where the properties are the paths to directories where files are loaded from and the values are an array of strings containing the relative paths under the directory of each file that can be loaded.

Example:

 {
     "/usr/share/javascript/ilib/locale": [
         "dateformats.json",
         "aa/dateformats.json",
         "af/dateformats.json",
         "agq/dateformats.json",
         "ak/dateformats.json",
         ...
         "zxx/dateformats.json"
     ]
 }
 

View Source ilib.js, line 629

a hash containing directory names and paths to file that can be loaded by this loader

Object

# loadFiles(paths, sync, params, callback)

Load a set of files from where-ever it is stored.

This is the main function define a callback function for loading missing locale data or resources. If this copy of ilib is assembled without including the required locale data or resources, then that data can be lazy loaded dynamically when it is needed by calling this method. Each ilib class will first check for the existence of data under ilib.data, and if it is not there, it will attempt to load it by calling this method of the loader, and then place it there.

Suggested implementations of this method might load files directly from disk under nodejs or rhino, or within web pages, to load files from the server with XHR calls.

The first parameter to this method, paths, is an array of relative paths within the ilib dir structure for the requested data. These paths will already have the locale spec integrated into them, so no further tweaking needs to happen to load the data. Simply load the named files. The second parameter tells the loader whether to load the files synchronously or asynchronously. If the sync parameters is false, then the onLoad function must also be specified. The third parameter gives extra parameters to the loader passed from the calling code. This may contain any property/value pairs. The last parameter, callback, is a callback function to call when all of the data is finishing loading. Make sure to call the callback with the context of "this" so that the caller has their context back again.

The loader function must be able to operate either synchronously or asychronously. If the loader function is called with an undefined callback function, it is expected to load the data synchronously, convert it to javascript objects, and return the array of json objects as the return value of the function. If the loader function is called with a callback function, it may load the data synchronously or asynchronously (doesn't matter which) as long as it calls the callback function with the data converted to a javascript objects when it becomes available. If a particular file could not be loaded, the loader function should put undefined into the corresponding entry in the results array. Note that it is important that all the data is loaded before the callback is called.

An example implementation for nodejs might be:

var fs = require("fs");

var myLoader = function() {};
myLoader.prototype = new Loader();
myLoader.prototype.constructor = myLoader;
myLoader.prototype.loadFiles = function(paths, sync, params, callback) {
   if (sync) {
       var ret = [];
       // synchronous load -- just return the result
       paths.forEach(function (path) {
           var json = fs.readFileSync(path, "utf-8");
           ret.push(json ? JSON.parse(json) : undefined);
       });

       return ret;
   }
   this.callback = callback;

   // asynchronous
   this.results = [];
   this._loadFilesAsync(paths);
}
myLoader.prototype._loadFilesAsync = function (paths) {
   if (paths.length > 0) {
       var file = paths.shift();
       fs.readFile(file, "utf-8", function(err, json) {
           this.results.push(err ? undefined : JSON.parse(json));
           // call self recursively so that the callback is only called at the end
           // when all the files are loaded sequentially
           if (paths.length > 0) {
               this._loadFilesAsync(paths);
           } else {
               this.callback(this.results);
           }
       });
    }
}

// bind to "this" so that "this" is relative to your own instance
ilib.setLoaderCallback(new myLoader());
Parameters:
Name Type Description
paths Array.<string>

An array of paths to load from wherever the files are stored

sync Boolean

if true, load the files synchronously, and false means asynchronously

params Object

an object with any extra parameters for the loader. These can be anything. The caller of the ilib class passes these parameters in. Presumably, the code that calls ilib and the code that provides the loader are together and can have a private agreement between them about what the parameters should contain.

callback function

function to call when the files are all loaded. The parameter of the callback function is the contents of the files.

View Source ilib.js, line 603