Skip to content
AtlanticBT Monogram Atlanticbt.com
Menu
javascript
June 30, 2011

Create your own Javascript Library

capabilities covered
Amazon Web Services

Create your own javascript library in these fun, easy steps!

Contents

Background

We all know about the performance benefits of putting all of our javascript/jQuery calls into .js files, so that browsers will cache the whole chunk on the client-side.

It’s even more tempting to put all of our complicated jQuery calls into a single file, thus further enhancing performance by reducing HTTP requests (i.e. the browser doesn’t have to download so many files).

However, have you ever taken a look at a site using the jQuery Cycle plugin on the homepage? If you open up the debugging console (firebug), go to a page without the slideshow, and I bet you’ll see a little message in the console like:

[cycle] terminating; too few slides: 0

This is because the cycle init code, while correctly put inside the DOM-ready function, is still being called on every page, regardless of whether it has a slideshow or not.

Most of the time you won’t even notice the extra overhead because jQuery fails gracefully, but it’s still traversing the DOM, looking for elements that aren’t there.

Solution

The solution is to encapsulate your code in a segmented library, and only call necessary aspects within the actual page. This has the benefits of:

  • separation – keeps functionality organized as atomic units, so there’s no conflict between similar functions
  • readability – when properly documented and structured, it should be easier to find your way around a library than code just stuck in a page.
  • usability – make your functions as complex as you want, but use them in multiple places with a single call. Added bonus: some IDEs like Eclipse can provide autocomplete and some documentation for the library class, making it easier to call what you’re looking for.
  • performance – since you’re only calling the functions you need when you need them, there’s no overhead from wasted DOM manipulation.

Library Shell

The following section provides a summarized example with most of the principles involved. It will:

  1. Declare the library “namespace” (see red section)
    • this is the external variable you’ll use to actually call your library publicly — you can change this name to avoid conflicts, or customize for each site.
    • wrap your library in a scope “wrapper” — this is to protect your methods, etc from external conflicts, and optionally to protect your usage of jQuery within the library.
  2. Declare the private “namespace” (see green section)
    • you’ll use this to refer to your library internally — basically just a shorthand reference
    • sets up the library as a javascript Object (JSON)
  3. Declare page directives or sublibraries (see blue section)
    • group functions or data into sublibraries, or organize along pages — here, we have a section for common tools, and a section for the search pages
    • use javadoc-style commenting to explain each sublibrary – some IDEs may pick this up
    • mark-off the closing { of sublibraries and methods with ///—- and the name of the library, to aid in navigation and organization
      • use 2 slashes with 3 dashes for methods
      • 3 slashes with 4 dashes for sublibraries
      • 4 and 4 for the library itself
      • this is really just so that monospaced fonts line them up; (my IDE also colors // vs //// differently)
    • you can also place the commas on separate lines as well, just so they don’t interfere with comments, and provide extra visual padding
  4. Declare actual function calls
    • within each function, you can bind to the jQuery document-ready function (see purple section); this is just to make it easier to use them with just 1 line outside the library.
    • you can use other methods and sublibraries within function calls (see yellow text); refer to the library with LIB.section.method, while you may also be able to use the shorthand this to call the current sublibrary (depending on whether you’re inside another anonymous function scope).
  5. Close all sublibraries and methods
  6. Return internal reference (see green text at bottom) – exposes the library object to public view.
  7. Close library scope wrapper (see red text at bottom)

Then, in your actual page, reference your library with the public namespace variable (see yellow text at bottom).

The Code

var Mylib = (function($) { //reference “namespace”, scope wrapper, encapsulates jQuery

var LIB = { //internal name of library
/**
* Testing function – indicates if our library is present
*/

”’test”’ : function(){ $(‘body’).prepend(‘SPECIAL library loaded’); } //page directives or sublibraries
,
/**
* General tools
*/

”’tools”’ : {
/**
* Console-log wrapper
*/
”’log”’ : function() { if( window.console && window.console.log ){
window.console.log( Array.prototype.slice.call(arguments) ); }
}//— lib.tools.log

}///—- lib.tools
,
/**
* Search namespace – related to search box or pages
*/

”’search”’ : {
/**
* Helper function
* @param msg a message for the alert
*/

”’notify”’ : function(msg){
alert(‘Doin’ the search:’ + msg);
}//— lib.search.notify
,
/**
* Enable advanced search box
*/

”’toggleAdvancedSearch”’ : function(){
this.notify( ‘self-reference the sublibrary OUTSIDE’ ); //call the sublibrary outside anon-func

$(function(){ //waits for document-ready
var $advancedSearch = $(‘#site-search-advanced’)
$searchResults = $(‘#search-results’)
;
LIB.tools.log( ‘here’s an example of self-referencing’ ); //call the library internally
LIB.search.notify( ‘self-reference the sublibrary INSIDE’ ); //call the sublibrary inside anon-func scope

//hide by default
$advancedSearch.slideUp(‘3000’);

$searchResults.delegate(‘#refine-search’, ‘click’, function(){
$advancedSearch.slideToggle();
return false;
});
});
}//— lib.search.toggleAdvancedSearch
}///—- lib.search
};////—- lib
return LIB; // send the internal name back out
})(jQuery); //scope wrapper, encapsulates jQuery

Mylib.tools.log( ‘actually using the library’ ); //call the library externally

Extensions

Multiple Internal Libraries

You could conceivably include more than one internal library (LIB, LIB2, etc) within your library scope. This is more for the following – #DOM wrapper like jQuery

DOM wrapper like jQuery

You can also include DOM-manipulation within your library. In the “shipping estimator” example, the library has an internal myDOM object that takes an HTML #id tag and creates a new instance of itself, which has several attached methods. This is similar to how jQuery works.

You’ll notice that at the end of the scope wrapper, instead of returning the LIB internal namespace, it’s merging the properties of that library back on to the myDOM object with:

//attach sublibraries to manipulation object (to avoid writing an .extend method?)
for(func in LIB){
	myDOM[func] = LIB[func];
}
return myDOM;

Again, this is similar to how jQuery extends itself (also see the “Build Your Own Library” reference).

Examples

See attached files – I apologize that these are mostly out-of-context, and probably have too much extra junk to be very simple to follow, but should give you an idea of what you can do with a library.

References

capabilities covered
Amazon Web Services

The Atlantic BT Manifesto

The Ultimate Guide To Planning A Complex Web Project

Partner With Us

Ready for modern web technology and a sharp, user-friendly design? We want to give you exactly that. Contact us to get started.

Contact
  • This field is for validation purposes and should be left unchanged.