berklee / nbl

NBL – a tiny non-blocking JavaScript lazy loader

Minified: 1215 bytes
Compatibility: Tested in Safari, Firefox, IE6+, basically doing nothing too fancy.
Examples: http://berklee.github.com/nbl/example.html

Introduction

Include NBL in your pages and let it dynamically load all your JavaScript files by simply including the following tag:

<script type="text/javascript" src="nbl.js" opt="{ urchin: 'http://www.google-analytics.com/urchin.js', plugins: [ 'jquery.lightbox.min.js', 'jquery.carousel.min.js' ], ready: my_ready_function }"></script>

This will do the following:

• It will load the latest version of jQuery from http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js.
• It will load the Urchin script from Google Analytics.
• After jQuery has loaded, it will start loading the jQuery plugins defined in the plugins array above.
• When jQuery has loaded, it will attach the my_ready_function() to jQuery’s document.ready() method.

Sometimes your pages are rendered before jQuery is fully initialised, in those cases NBL will wait until all scripts have loaded and call the my_ready_function() itself.

Verifying the results

After NBL has done its job you can verify a few things through the global nbl object (you can change the name of this object by specifying name: in the options). I’ll outline the most notable below:

• Every script will be placed in the nbl.q object, referred to by the name given in the options. By default it will load the jQuery library, so nbl.q.jquery will return true, as will nbl.q.urchin in the above example. The status of the plugins can be retrieved by nbl.q.p0 and nbl.q.p1. If a script has loaded successfully, it will return true, otherwise you’ll get the script element of the script you queried.

• You can verify whether jQuery used the document.ready() method to call the my_ready_function() afterwards as nbl.j will be true. If the page rendered before jQuery was ready, NBL will have fired my_ready_function() instead and nbl.j will be undefined.

• When a script fails to load, NBL will fire the my_ready_function() after a default timeout of 1200ms. Afterwards nbl.e will be set to true, signifying the error. You can change the default timeout by specifying timeout: 2400 (or any other number) in the options.

NBL’s options

Here’s a short overview of the available options (in no particular order):

• name: 'nbl' — this string determines the name of the NBL object
• jquery: false or 'url' — set to false won’t load jQuery, or supply an alternate url
• plugins: ['url1', 'url2'] or 'url' — either an array or a single url; plugins will always load after jQuery
• ready: function_name or function(){} — this will be called through jQuery or after all scripts have loaded
• timeout: 1200 — pick a number, any number (of milliseconds); I tried to pick a sensible default of 1200ms

All options are case-sensitive, if you include a file and name it 'urCHin', the corresponding nbl.q object will be nbl.q.urCHin. I advise you to simply use lowercase for all options.

If you do not specify any options in the script tag, NBL will instantiate the default nbl object and will do nothing. You will have to do a manual nbl.run( { options: here } ). You can find more examples in the included example.html.

Replacing jQuery

I realise that NBL is very focussed on jQuery, but on the other hand, if you don’t mind missing jQuery’s document.ready() function, you can just as easily replace it with MooTools or Prototype. Just supply the required url to the jquery: option.

The plugin loading functionality remains intact, simply enter some MooTools/Prototype plugins in the plugins: array, and they will load as soon as the script now replacing jQuery has loaded. After all scripts are done, NBL will fire the ready: function and you can do your favourite library’s specific code in there. That should work just fine.

PS. As mentioned, you don’t need to specify the opt attribute in the script tag, you can call nbl.run( { jquery: 'url' } ) manually. And of course you can load scripts manually with nbl.load( 'name', 'url' ) at any moment as well. If you do wish to use the opt attribute, NBL will search for itself by looking for 'nbl' in its filename, so make sure it has 'nbl' in the filename!

MIT License

Copyright © 2009 Berklee

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.