LABjs手册

 

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:

• opera_or_gecko = (global.opera && Object.prototype.toString.call(global.opera) == "[object Opera]") ||
  ("MozAppearance" in document.documentElement.style),

  The Opera inference relies on the fact that Opera declares an "opera" property on the window object, and that it's a special native, whose toString() return value cannot be duplicated by someone just declaring a window.opera property themselves. This gives a reasonably strong inference that we are in fact in the Opera browser.

  The Mozilla inference relies on "MozAppearance" only appearing in Gecko browsers in the documentElement's style object. This isn't as solid as the Opera inference, but Gecko/FF has had this property for a really long time and there's a good chance they won't remove it, nor would any other browser have any reason to add a property of that name.

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

• $LAB.setGlobalDefaults()
• $LAB.setOptions()
• $LAB.script()
• $LAB.wait()
• $LAB.queueScript()
• $LAB.queueWait()
• $LAB.runQueue()
• $LAB.noConflict()
• $LAB.sandbox()

---

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:

• AlwaysPreserveOrder: a boolean (defaults to false) which controls whether an implicit empty wait() call is assumed after every script loading, which essentially forces all scripts in the chain to execute serially in order (loading in parallel, by default, is not affected by this setting).
• UseLocalXHR: a boolean (defaults to true) which controls whether LABjs will use an XHR Ajax call to "preload" scripts which are "local" to the current page's domain (note: does *not* take advantage of any cross-domain Ajax techniques). This "preload" is effective and quite performant for local scripts.
  
  Note: This technique is only attempted to be used if it's set to true and in an older Webkit browser, where neither ordered-async or real-preloading were present, and then only on a local same-domain script. Otherwise, this setting is ignored.
• AllowDuplicates: a boolean (defaults to false) which controls whether or not LABjs will inspect its internal script URL cache to prevent a script URI from being (accidentally, most likely) loaded a second time. By default, LABjs will not make any duplicate requests for the same script URL. Duplicates within the same chain will simply be ignored, and duplicates across other chains will cause those duplicate calls in the other chains to patiently wait until the single resource loading finishes. If you turn "AllowDuplicates" on, then no such de-duplication will be done, either within the chain or between multiple chains.
• BasePath: a string (defaults to empty "") which specifies a path value to prepend to every script URL. All relative script URL's are already automatically fully qualified to the page's location, so this BasePath should really be used to set some other absolute path to override this qualification for otherwise relative "looking" script URL's.
• CacheBust: a boolean (defaults to false) which adds a random number parameter to every script URL to prevent the URL you requested from being cached. In other words, your requested script will be loaded new each time, since it will have a new random number on the URL each time.
• Debug: a boolean (defaults to false) which controls if the web console will be used to log the various steps of loading/processing logic for $LAB chains. This option is only effective if using the source file for LABjs, or the LAB-debug.min.js file. Otherwise, this setting will be ignored. As such, it's safe to have this option turned on in both development and production, but not serve the debug build of the file to production unless you need to troubleshoot an issue in production.

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):

• string : a relative or absolute path URI to a local or remote script to load
• object : an object containing one or more of these properties:
  • string src : (required) a relative or absolute path URI to a local or remote script to load
  • string type : (optional) the MIME type attribute (ie, "text/javascript", "text/vbscript", etc)
  • string charset : (optional) the charset attribute (ie, "utf-8", etc)
  • bool allowDup : (optional) whether to suppress a duplicate script URI check for this script. (defaults to the value of the AllowDuplicates global or chain option.
• array : an array of parameters of any of the allowed types (including array)

• function : if a function is found as one of the parameters, that function will be be executed immediately, which must return a value directly. The return value must be one of the other allowable types (string, object, or array). If the function call results in no return value ("undefined") or the value is "falsy" (false, null, etc), it will be interpreted as no script to load.

  This feature allows the construction of "conditional chains", where run-time logic is used to decide ultimately what scripts will be loaded by the $LAB chain.

  See Example 8 below for usage demonstration.

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.");