Release Notes

Test Suite Passes

Browsers tested and passing the Test Suite (please help to fill in gaps):
Windows: IE 6+, FF 1.5+, Chrome (latest), Opera 9.6+, Safari 4+, Netscape 7.2+, Mozilla 1.7
Mac (OSX): Safari 3.2+, Netscape 9, FF 1.5+, Opera 9.6+, Mozilla 1.7, Camino 2
Linux: FF 1.5+, Opera 9.5+, Netscape 9

Known unsupported

Safari 2, Opera 8, Konquerer (3.4, 4.1), FF 4b7 (only this exact release. <= b6 and b8+ are ok), Blackberry 4


Builds

It is recommended that you simply use the distribution-included minified files LAB.min.js and LAB-debug.min.js in production and development, respectively. However, some developers may want to use their own minification tools to "build" LAB.min.js themselves, from the source file (LAB.src.js). This is fine, but make sure you don't use too aggressive of a minifier/compiler, as it's possible you could alter something about LABjs in an unexpected and breaking way. Typically, compressors like YUIC and Packer (without base62) are quite safe and should be fine.

As of v2.0, LABjs source code (LAB.src.js) has DEBUG-mode code in it, delimited by /!*START_DEBUG*/ and /*!END_DEBUG*/ comments. This debug code is intended to be removed if minifying and building LAB.min.js from the original source code (but left in if building LAB-debug.min.js). This removal is possible with a simple preprocessing regex replace to remove the DEBUG-mode code from the source before minification. For instance, the following regular expression should work for that purpose:

/\/*!START_DEBUG(?:.|\n)+END_DEBUG*\//

The LAB-debug.min.js file skipped this step before minification, thus it includes the debug code. The LAB.min.js file however has the DEBUG-mode code stripped from it.

NOTE: It should also be safe to simply pass LAB.min.js or LAB-debug.min.js to your own minifier (even though they are already minified), which will simply do a harmless re-minification of the file. The best option, however, would be to instruct your build process to ignore minification on these files.


Documentation

Old and busted:

<script src="framework.js"></script>
<script src="plugin.framework.js"></script>
<script src="myplugin.framework.js"></script>
<script src="init.js"></script>

New hotness:

<script>
   $LAB
   .script("framework.js").wait()
   .script("plugin.framework.js")
   .script("myplugin.framework.js").wait()
   .script("init.js").wait();
</script>

In the above example, all scripts load in parallel (by default). "framework.js" needs to execute first, before the others. But "plugin.framework.js" and "myplugin.framework.js" have no dependencies between them, so their execution order is not important (first-come, first-served). "init.js" needs to wait for all 3 scripts to execute before it runs.

There are a few other variations on the .script(...) signature. For instance, you don't have to do a single script() call for each file (though I think it makes thing more readable). You can pass as many scripts singularly as parameters to one script() call. You can also pass an array of scripts, and it will loop through them and load them in the same way. Lastly, you can pass in an object instead of string, and the object literal can contain "src", "type", and "charset" specifications, if you need to override the defaults (for instance, load a "text/vbscript" script).

How to deal with inline scripts

So, there's some special gotchas you need to look out for when using LABjs not only to load scripts but also to "couple" inline scripts to execute in the proper order with the loaded scripts. Take this expanded example from above:

<script src="framework.js"></script>
<script src="plugin.framework.js"></script>
<script src="myplugin.framework.js"></script>
<script>
   myplugin.init();
</script>
<script>
   framework.init();
   framework.doSomething();
</script>

In this example, the browser would normally make sure that the two inline script blocks at the end will not even be parsed/executed until after the 4 scripts have been loaded. So, the references to "myplugin.init", "framework.init", and "framework.doSomething" will already be guaranteed to be defined (in the scripts that are loaded before the code is parsed).

But, because LABjs is an asynchronous loader, this "guarantee" will not be true. So, this code will fail:

<script>
   $LAB
   .script("framework.js").wait()
   .script("plugin.framework.js")
   .script("myplugin.framework.js")
</script>
<script>
   myplugin.init();
</script>
<script>
   framework.init();
   framework.doSomething();
</script>

The reason is because "myplugin.init", "framework.init", and "framework.doSomething" will be undefined symbols the instant after the $LAB chain first executes and starts loading the scripts. To make this code asynchronous safe, we do this instead:

<script>
   $LAB
   .script("framework.js").wait()
   .script("plugin.framework.js")
   .script("myplugin.framework.js")
   .wait(function(){
      myplugin.init();
      framework.init();
      framework.doSomething();
   });
</script>

We wrap the inline script code in a ".wait(function(){ ... })" wrapper, which will defer its execution until the proper time in the loading order of the chain.

A simple pattern for converting <script src="..."></script> and <script>... /* inline code */ ...</script> tags into $LAB API calls, use these two rules:

  1. For every <script src="..."></script> tag you are replacing, you should have a ".script(...)" call
  2. For every <script>... /*inline code*/ ...</script> inline script block with code in it, we need a ".wait(function(){ ... })" call to wrap around the code

If this still is a little confusing, it's ok! Read more about converting inline synchronous code to LABjs suitable asynchronous code over on getiblog.

Special "Feature" Note(s)

LABjs is able to handle non-feature-testable behavior in older legacy browsers through the use of two small but fairly solid browser inference sniffs. This is different from feature-detection (which is always preferable when possible), but with script-loading quirk behavior, there's no way to feature-detect (in those older legacy browsers), so we simply have to fork behavior based on browser family. So, the following two browser inference sniffs are used:

LABjs feature-tests for `async=true` (aka "ordered async") on script-inserted script elements. Read more about this feature on the Dynamic Script Execution Order WHATWG Wiki Page and Henri Sivonen's HTML5 Script Execution Changes.

The HTML Spec has officially been updated to include the "async=false" behavior, that LABjs employs a feature-detect for. FF4+, Webkit (March 2011+), IE10p2+, and Chrome 12+ now have this implemented (and Opera is coming soon).

LABjs also feature-tests for "real preloading". This type of preloading doesn't rely on the "cache preloading" hacks, but instead directly preloads the script (once) and then allows the execution of that code on-demand without a second (cached) request. This functionality has been present in IE since version 4, is suggested in the HTML spec (not required), and has been proposed to be officially declared a requirement. Even if it's never actually standardized any further, it's the best method available for IE, so it's worth it. Read more about the proposal to make this a requirement: Script Execution Control.


LABjs API

Methods



void $LAB.setGlobalDefaults(object optionsObject)

Sets one or more options as global defaults to be used by all $LAB chains on the page. This method is not chainable, and thus must only be called stand-alone like this: $LAB.setGlobalDefaults({...});

Parameters
optionsObject : an object which contains name/value pairs for the options to set:

Returns
none


[$LAB] $LAB.setOptions(object optionsObject)

Sets one or more options only to be in effect for the current $LAB chain being executed. This method is chainable (in fact, for it to have any effect, it must be part of a chain!), but it must be the first call in the chain (as changing many of the options mid-chain would create race conditions). So, it must be called like this: $LAB.setOptions({...}).script(...)...;

Parameters
optionsObject : an object which contains name/value pairs for the options to set
Returns
$LAB : the chained object reference so subsequent calls to script() and wait() can be made.


[$LAB] $LAB.script(varies,...)

This method accepts one or more parameters of varying types. Each parameter value is intended to specify a script resource URI to load.

Parameters
varies (can be any number/combination of the following):

Returns
$LAB : the chained object reference so subsequent calls to script() and wait() can be made.


[$LAB] $LAB.wait(function inlineScript[=null])

This function serves two purposes. Firstly, when inserted into a chain, it tells the chain to ensure that all scripts previously listed in the chain should finish executing before allowing the internal 'execution cursor' to proceed to the remaining part of the chain. Essentially, you can specify "blocking" behavior in terms of execution (not loading!) to ensure dependencies execute in the proper order (regardless of how they were loaded).

Secondly, you can specify a function reference (usually an inline anonymous function) that will be executed in order, immediately following the chain's previous scripts executing, but before subsequent scripts in the chain are executed. This is synonymous with inline <script> tags before or after <script src="..."> type tags.

For instance, it can be used to defer the initialization execution of a script you are downloading, like this: $LAB.script("script.js").wait(function(){initScript();}); where initScript() is a function that is defined in "script.js".

Parameters
inlineScript : (optional, defaults to null)
Returns
$LAB : the chained object reference so subsequent calls to script() and wait() can be made.


[$LAB instance] $LAB.queueScript(varies,...)

This function queues up a call just like it was made against script(), except that the queueing prevents it from being processed right away. The parameters you pass to this function are passed directly to script() once the queue is processed.

Parameters
varies : the same parameters for script()
Returns
$LAB instance : The initial $LAB instance, so subsequent calls to queueScript() and queueWait() can be made.


[$LAB instance] $LAB.queueWait(function inlineScript[=null])

This function queues up a call just like it was made against wait(), except that the queueing prevents it from being processed right away. The parameters you pass to this function are passed directly to wait() once the queue is processed.

Parameters
inlineScript : the same parameters for wait()
Returns
$LAB instance : The initial $LAB instance, so subsequent calls to queueScript() and queueWait() can be made.


[$LAB] $LAB.runQueue(none)

Calls to queueScript() and queueWait() queue up the calls just like you are creating a queued $LAB chain. Calling runQueue() will then process the chain as if it had been directly defined. The return value is the end of the $LAB chain, so it can be further chained as you see fit.

Parameters
none
Returns
$LAB : the chained object reference from the queued chain, so subsequent calls to script() and wait() can be made.


[$LAB instance] $LAB.noConflict(none)

noConflict() rolls back the page to the previous version of LABjs (if any) before this copy of LABjs was loaded, and returns the current instance of $LAB.

Parameters
none
Returns
$LAB instance : the current $LAB instance (from before the rollback)


[$LAB instance] $LAB.sandbox(none)

sandbox() creates a new clean instance of $LAB. This allows you to get new instances of LAB, if for instance you need a new queue for use with queueScript() or queueWait().

Parameters
none
Returns
$LAB instance : a new clean instance of $LAB


Examples

Example 1:

	$LAB
	.script("script1.js")
	.script("script2.js")
	.script("script3.js")
	.wait(function(){ // wait for all scripts to execute first
		script1Func();
		script2Func();
		script3Func();
	});


Example 2:

	$LAB	
	.script({ src: "script1.js", type: "text/javascript" })
	.script("script2.js")
	.script("script3.js")
	.wait(function(){ // wait for all scripts to execute first
		script1Func();
		script2Func();
		script3Func();
	});


Example 3:

	$LAB
	.script("script1.js", "script2.js", "script3.js")
	.wait(function(){ // wait for all scripts to execute first
		script1Func();
		script2Func();
		script3Func();
	});


Example 4:
	
	$LAB
	.script( [ "script1.js", "script2.js" ], "script3.js")
	.wait(function(){ // wait for all scripts to execute first
		script1Func();
		script2Func();
		script3Func();
	});
	
	
Example 5:

	$LAB
	.script("script1.js").wait() // empty wait() simply ensures execution order be preserved for this script
	.script("script2.js") // both script2 and script3 depend on script1 being executed before
	.script("script3.js").wait() // but are not dependent on each other and can execute in any order
	.script("script4.js") // depends on script1, script2 and script3 being loaded before
	.wait(function(){script4Func();});
	

Example 6:

	$LAB
	.script("script1.js") // script1, script2, and script3 do not depend on each other, 
	.script("script2.js") // so execute in any order
	.script("script3.js")
	.wait(function(){  // can still have executable wait(...) functions if you need to
		alert("Scripts 1-3 are loaded!");
	})
	.script("script4.js") // depends on script1, script2 and script3 being executed before
	.wait(function(){script4Func();});
	
	
Example 7:

	$LAB
	.setOptions({AlwaysPreserveOrder:true}) // tells this chain to implicitly "wait" on 
	                                        // execution (not loading) between each script
	.script("script1.js") // script1, script2, script3, and script4 *DO* depend on each 
	.script("script2.js") // other, and will execute serially in order after all 4 have have
	.script("script3.js") // loaded in parallel
	.script("script4.js")
	.wait(function(){script4Func();});
	

Example 8:

	$LAB
	.script(function(){
		// assuming `_is_IE` defined by host page as true in IE and false in other browsers 
		if (_is_IE) {
			return "ie.js"; // only if in IE, this script will be loaded
		}
		else {
			return null; // if not in IE, this script call will effectively be ignored
		}
	})
	.script("script1.js")
	.wait();
	
	
Example 9:

	$LAB
	.queueScript("script1.js") // script1, script2, and script3 do not depend on each other, 
	.queueScript("script2.js") // so execute in any order
	.queueScript("script3.js")
	.queueWait(function(){  // can still have executable wait(...) functions if you need to
		alert("Scripts 1-3 are loaded!");
	})
	.queueScript("script4.js") // depends on script1, script2 and script3 being executed before
	.queueWait(function(){script4Func();});
	
	// ...
	
	$LAB
	.runQueue() // execute the queue as a $LAB chain
	.script("script5.js")
	.wait(function(){
		alert("Script 5 loaded and executed off the end of a previously queued chain.");
	});

This documentation page has generously been translated into Serbo-Croatian by Jovana Milutinovich.