Fuel Your Coding » Javascript

Open-Source Spotlight: Underscore.js

Jerod Santo — Thu, 01 Apr 2010 16:20:36 +0000

JavaScript is a powerful language, but it lacks some of the handy utilities that developers of other languages like Ruby & Python have come to know and love. Underscore.js is your utility belt. In the author’s own words:

Underscore is a utility-belt library for JavaScript that provides a lot of the functional programming support that you would expect in Prototype.js (or Ruby), but without extending any of the built-in JavaScript objects. It’s the tie to go along with jQuery’s tux.

Underscore.js provides collection functions like each, map, include, and reduce. It makes arrays more powerful by adding flatten, uniq, and intersect. It extends objects with many useful functions like keys, values, functions, isNaN, and many more.

A few examples to whet your appetite:

Using the each function to write each array value to the console:

// object-oriented way
_(['John', 'Paul', 'George', 'Ringo']).each(function(beatle) {
    console.log(beatle);
});
// functional way
_.each(['John', 'Paul', 'George', 'Ringo'], function(beatle) {
    console.log(beatle);
});

Using the reduce method to round three numbers down and sum the results:

_.reduce([1.5,2,3.7], 0, function(memo, num) { return memo + Math.floor(num) });
// => 6

Using the pluck method to to extract just the names from an array of objects:

var beatles = [
  {name: 'John', dead: true},
  {name: 'Paul', dead: false},
  {name: 'Ringo', dead: false},
  {name: 'George', dead: true}
]

_.pluck(beatles, 'name');
// => ["John", "Paul", "Ringo", "George"]

The library weighs in at just 2.5kb once packed and gzipped, so there is little excuse not to take advantage of its offerings. There are over 60 functions included, the documentation on how to use each function is great, the source code is freely available on GitHub, and the library is completely DOM-free which means you can use it server-side as well.

Thanks to Jeremy Ashkenas and the folks at DocumentCloud for a great open-source library that we can all benefit from!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Open-Source Spotlight: Underscore.js

jQuery Plugin Design Patterns: Part I

Douglas Neiner — Wed, 20 Jan 2010 18:21:06 +0000

jQuery plugins come in all shapes and sizes. They perform very simple or very complex tasks depending on their intended use. When it comes time for you to design your own plugin, its really important to understand what patterns other developers use and what will best suits your needs.

As a side note, I have built a number of plugins for my own projects and client work that will never be released. The jQuery community needs to stop thinking of plugins only as releasable, open-source projects, and start thinking of them instead as a reusable pieces of code that can help optimize and DRY up a complex website. Take this little plugin as an example:

$.fn.notice = function(){
    return this.slideDown(500).delay(4000).slideUp(500);
}

It simply abstracts the animation for displaying a notice (using jQuery 1.4). Would I ever release this on an open source site? Of course not! But it is still a fully functioning jQuery plugin that can be used over and over throughout a website.

Design Pattern Series Overview

Basics & Structure (this article)
Options & Updating
Callbacks & Custom Events
Misc. General Practices

Basics

Filename

Every jQuery plugin sits in its own JS file, and is normally named using the following pattern:

jquery.pluginname.js
jquery.pluginname.min.js

Released plugins often also have a version number:

jquery.pluginname-1.3.js
jquery.pluginname-1.3.min.js

If you end up building a lot of plugins for your website, consider also including a namespace to keep all your files together (And of course you would combine and minify them for production, right?):

jquery.mysite.pluginname.js
jquery.mysite.pluginname.js

Basic File Layout

After any comments you choose to put at the top of your file, the very next thing you should have is a self executing anonymous function that will actually wrap your entire plugin. Say what!? Don’t worry, you have seen it before, and it looks like this:

(function($){

   ... code here ...

})(jQuery);

This gives your plugin a private scope to work in, and also allows your plugin to be used with $.noConflict mode without creating a problem. By passing jQuery into the function, the $ will equal jQuery inside the function even if $ means something different outside your plugin.

Structure

There are three basic structures you will see when you look at released plugins:

Contained Function

In this structure, (almost) all the code to run your plugin is contained within the function used to call your plugin. This is the most common format:

(function($){

   $.fn.myPlugin = function(){
      return this.each(function(){
         // do something
      });
   }

})(jQuery);

You should use this this structure when you are writing a simple plugin that acts once upon the jQuery result set on each execution. For complex plugins that need to maintain an adjustable state, you should consider the “Class and Function” structure.

Class and Function

In this structure, a class is used and an instance is created for each DOM element in the result set. You may see these objects attached in some way to the DOM elements they modify:

(function($){
   var MyClass = function(el){
       var $el = $(el);

       // Attach the instance of this object
       // to the jQuery wrapped DOM node
       $el.data('MyClass', this);
   }

   $.fn.myPlugin = function(){
      return this.each(function(){
         (new MyClass(this));
      });
   }

})(jQuery);

You should use this structure if you need to be able to access the object later that is associated with a DOM element. It is far easier to attach a single object vs several key/value pairs using the data() method. In this approach, you can access the object by calling $('selector').data('MyClass'). This functions more like a widget and is a plugin that maintains state and can adjust its state on the fly (Learn how in the next article.).

Note: Widget Factory: The next release of jQuery UI is going to see the addition of a Widget Factory that will be designed to specially assist in developing widget-like plugins.

Extend

In my opinion, this is the least idiomatic way to create a jQuery plugin. It uses the jQuery.fn.extend method instead of jQuery.fn.pluginName:

(function($){

   $.fn.extend({
     myPlugin: function(){
      return this.each(function(){
         // do something
     },
     myOtherPlugin: function(){
      return this.each(function(){
         // do something
     }
   });

})(jQuery);

You will find this structure helpful if you need to add a large number of plugin methods to jQuery. I would contend, however, that if your plugin needs to add that many methods, there may be a better way to structure its implementation.

I feel the extend method is used more by programmers transitioning from other JS libraries. I personally find the simple $.fn.pluginName = structure to be easier to read, and more in line with what you will normally see in jQuery plugins.

Up Next

In the next part of this series, we will look at passing options and providing methods for updating settings and functionality after a plugin has been called.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

jQuery Plugin Design Patterns: Part I

jQuery Enlightenment: Book Review and Giveaway (Winners Announced!)

Douglas Neiner — Wed, 13 Jan 2010 20:04:58 +0000

Winners Announced

I was really happy to see so much participation in this giveaway! After seeing how many people entered, I was feeling really bad that only one of them would leave with a copy of the book. I talked to Cody, and he graciously provided two more free copies so we can award a total of three books! I randomly picked three winners (using Random.org) and am happy to announce the following winners:

Brad Rhine (truetech.org)
Mila
Geoff Woodburn (woodburndesigns.com)

Book Review

Late in 2009, Cody Lindley published a PDF book on jQuery titled jQuery Enlightenment. Today we are presenting our view of the book as well as offering a free copy to one lucky reader.

About The Author

Cody Lindley is a core team member of the jQuery project, and the original developer of the well known Thickbox plugin for jQuery. I had the pleasure of meeting and listening to Cody present at the jQuery Conference last year in Boston. He describes himself on his website:

Today I am a Christian, husband, son, brother, professional Web developer, and outdoor enthusiast. I spend a majority of my time sleeping and working, but who doesn’t? In between the daily routines of the average American, I desire an existence that entails a relationship with God, my family, and nature. I would like to consider myself a bookworm (a novice theologian at best), but truth be told, I simply enjoy watching movies and playing xBox way too much. I guess I also have the luxury of pursuing my profession as a personal passion. Yes, I often work even when I am not at work.

Overview

jQuery Enlightenment is a different type of book than I am used to seeing in the tech field. A list of what it is not might help shed light on what I mean. It is not documentation, a tutorial/walkthrough, or just conceptual material. jQuery Enlightenment is an amazingly clear montage of principals and code samples every jQuery developer needs to know grouped by topic. Cody covered topics both basic and profound throughout the pages of the book.

I consider myself quite adept at using jQuery, but found myself constantly amazed at the things I was learning while reading this book. Cody says it picks up where the jQuery documentation leaves off. I can see his point, but I think this book would be a better starting place for a new jQuery developer than even reading through the jQuery API site.

Pros

Code Samples

Code samples make up over 70% of the book (rough estimation). The book is not written in an editorial way at all. It is about presenting what you need to know, demonstrating it with an example, and moving on. For this reason the book is an extremely fast read and perfect for reference on a day to day basis.

Possibly one of the neatest features of the book itself is that (almost) every code sample provided in the book has a link to the same code on JSBin.com. JSBin is an online playground for testing and demonstrating JavaScript, HTML, and CSS technologies. jQuery Enlightenment isn’t a flat reading experience, it allows you to immediately jump in and play with the code samples until everything makes sense.

Additional Notes

Many of the topics are followed by a little box titled ‘Notes’. I am glad Cody didn’t choose some cheesy title for these boxes, but ‘Notes’ really does not sum up what they provide. You will find many undocumented (or hard to find) tips and tricks about the finer points of jQuery in these boxes. Skip over them at your own peril!

No Fluff Quality

Cody doesn’t waste any time on any of the topics presented in the book. The pattern used is simple: explain, demonstrate, move on. I personally will be using this book not just for reference, but for a quick read-through every few weeks to keep my jQuery senses sharp.

Cons

You will be hard pressed to find something negative to say about this book, and it wasn’t until I reached the end that I had one complaint about the content. The chapter on Ajax (Chapter 11) was far too short. Perhaps this is because the documentation is very clear, but I still wanted to learn more and have more examples to glean from. Perhaps the second edition of the book (which will cover jQuery 1.4) will provide more detail on jQuery’s AJAX implementation and associated methods.

Conclusion

I am confident new users and seasoned users alike will find much to learn in jQuery Enlightenment. After reading the book, my only concern is that I won’t remember all of the cool things I learned while reading it!

Win a FREE Copy!

Next Wednesday we will be selecting a winner to receive a free copy of jQuery Enlightenment. Entering the competition is easy!

Head over to jQuery Enlightenment and quickly look through table of contents. Then, leave a comment below telling us what chapter you think you would learn the most from if you were to win the book. Only comments referencing one of the actual chapters in the book will be eligible to win. ~~We will randomly select a winner next Wednesday and announce it here on the site.~~. Sorry, but the contest is over!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

jQuery Enlightenment: Book Review and Giveaway (Winners Announced!)

JavaScript Can Learn: Now Teach It Tricks!

Douglas Neiner — Fri, 30 Oct 2009 07:00:34 +0000

When you do a lot of development with backend technologies, it can be frustrating to then move to the front end and feel like you are using a completely different syntax. One thing I really miss is the helper methods, especially when using Ruby on Rails on the server. Little helpers like titleize() or downcase() get replaced in javascript by a custom function and toLowerCase() respectively. You don’t have to feel lost anymore! There is a way you can extend the native objects found in JavaScript to make your environment feel a little more like “home.”

This is accomplished by using the prototype object. Each native object in JavaScript includes a prototype object. Don’t get this confused with the PrototypeJS framework… the prototype object is a way to extend all objects that have inherited from the base object you extended. You can easily extend the prototype object by adding functions to it like this:

Object.prototype.functionName = function(){

}

You can then call them directly:

var obj = new Object();
obj.functionName();

There are a number of advanced uses of the prototype object, but this is the important thing to remember: any function added to the prototype of an object is available on any object that inherits from it. So if you extend the prototype on the Number object, all numbers will have access to the new function; if you extend the Array object, all arrays can access your custom function. You only use the prototype.functionName syntax when declaring the new function, not when calling it.

Enough theory, lets see some (somewhat) practical uses:

Do you find yourself capitalizing a lot of words in a particular JavaScript app? Just add a capitalize method to the String object.

String.prototype.capitalize = function(){
  if(this.length == 0) return this;
  return this[0].toUpperCase() + this.substr(1);
}

Now you can capitalize any string in your application by calling "lower".capitalize() and get "Lower" in return. Since it returns a string, you could chain it with any other function you can execute on a string.

Do you always find yourself forgetting you can call Number(”25″) to turn a string into a number? Just add a toNumber() function to the String prototype:

String.prototype.toNumber = function(){
  return Number(this);
}

If you need to split large JSON arrays into groups of two or three each, you could extend the Array object like this:

[js]
Array.prototype.inGroupsOf = function(num){
	var ret = [],
		length = this.length,
		groups = Math.ceil(length / num);

	for(var i = 0; i < groups; i++){
		var start = i * num,
			end   = start + num;

		ret.push(this.slice(start, end))
	}
	return ret;
}

Now calling inGroupsOf(3) on any Array would return that same array split into as many parts as needed to ensure no group has more than three items in it.

There are a number of objects you can extend, but the ones you will use the most are String, Array, Object, Number, Date. One trouble area you might face is calling methods on numbers. The following example will fail:

Number.prototype.to_s = function(){
  return this + "";
}

25.to_s();

The prototype function is correct, but the way we called it is wrong. There are two ways to call our custom functions on numbers:

var n = 25;
n.to_s(); // Returns "25"

(25).to_s(); // Also returns "25"

Think Start, Not End

Its important when deciding what object to extend that you focus on what object type you are starting with, not so much which type you plan on ending with. For instance, if you wanted to extend an object to easily parse Twitter date strings you would not extend the Date object. You would extend the String object, and your function would return a Date object.

Load Your Extensions First

It is normally a good idea to load these extensions prior to any other library, including jQuery. Anytime you extend the prototype object, the new method is instantly available to all objects of the same type or any object that has inherited from that type. However, since you want to be sure your methods are always available, you guarantee their availability by loading them first.

How to Group The Extensions

Naming your files Prototype.Date.js and Prototype.Array.js is an easy way to keep all your extensions in one part of your JS folder, and easy to access during development. If you follow this method, you would simply put Date.prototype methods in the Prototype.Date.js file, etc. This starts to break down when you have parallel functions. You might have a toDateFromTwitter() method on the String object and a toTwitterFromDate() method on the Date object. Putting these in separate files might not make sense. At that point, you should put both these extensions in a file named TwitterHelpers.js or something similar. Obviously use what makes sense to you and works with your flow.

Don’t Bloat

Just because you write 500+ awesome Array extensions in the next 2 years, does not mean you need to include them on every project. Be sure to only use this technique when it makes sense for the project and when it helps clean up your code.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

JavaScript Can Learn: Now Teach It Tricks!

jQuery Custom Events: They Will Rock Your World!

Douglas Neiner — Thu, 09 Jul 2009 00:12:50 +0000

Ok, maybe they won’t exactly “Rock Your World” but they might completely change the way you look at your jQuery development. At the very least, I hope this simple technique will help you build clean, reusable and extendable front-end code.

A Quick ‘n’ Dirty Overview

If you are the “just the facts” type of person, here is the 20 second overview. You can trigger custom events on any DOM object of your choosing using jQuery. Just trigger it using the following code:

$("#myelement").trigger('fuelified');

You can subscribe to that event using either bind or live functions in jQuery:

$("#myelement").bind('fuelified',function(e){ ... });
$(".cool_elements").live('fuelified',function(e){ ... });

You can even pass additional data about the event when triggering it and reference it on the listeners end:

$("#myelement").trigger('fuelified',{ custom: false });
$("#myelement").bind('fuelified',function(e,data){ if(data.custom) ... });

The element the trigger has been called on, is available to listener’s callback function as the variable this.

A Little Philosophy

I encourage you to view your front end code in parts and pieces instead of one huge piece of front-end code. If you look at each part separately, you can build better, reusable pieces of code. You won’ t have a lot of duplicated code in your web-site, and you will be able to extend what you have built later on. A rating site might have widgets that are used to take in the ratings. You may have another widget that monitors the rating widgets and tallies the scores. Making the pieces as independent as possible makes reuse and extension a breeze.

A Fun Example

For those who like tutorials or walkthroughs, this should be a fun demonstration of the power of jQuery custom events.

Preparation

To get started, download my blank website template. Then head over to Starter for jQuery and create two jQuery plugins using the following settings:

Class Name: ColorBlock
Include: Options, Getter (Not Comments)
Class Name: ColorObserver
Include: Options, Getter (Not Comments)
Default Options: colorObjs|div.color_block

After you enter each item, click Create then Download. Save each file to the js/ directory of our Blank Website Template. Then add

HTML

Copy and paste the following HTML markup into the tag of the index.html file:

Normally I might delegate the creation of the div.color_block elements to a script as well, but that is not the point of this exercise!

CSS

Copy and paste the following CSS into the layout.css file. Basically it sets simple styling for our elements. The important part is that it sets a width and height of 50px for our .color_block elements, and floats them to the left. If you were to load index.html in a browser right now, you wouldn’t see too much.

.color_block {
	width: 50px;
	height: 50px;
	cursor: pointer;
	float: left;
	margin: 0 5px 5px 0;
}

.observer {
	clear: left;
	margin: 10px 0;
	padding: 10px;
	float: left;
	background: #eee;
	font-family: Helvetica, Arial;
}

#observer-one { border-top: solid 2px red; }
#observer-two { border-top: solid 2px blue; }

JS

The plugins you created using Starter for jQuery have added two new functions to our jQuery objects. We are going to call both of them in our script area. Paste the following code between the opening and closing braces of the document.ready function:

$(".color_block").colorBlock();
$("#observer-one").colorObserver();

The first line calls our colorBlock plugin on all the blocks. The second, calls our colorObserver method on one of our observer divs. If you load the page now, you should not get any errors, but nothing should do anything yet either.

ColorBlock

We want to give our ColorBlocks an array of colors. They will all start on color 1 (index position 0) and every time you click on them, they will change to the next color. To do this, we will add code to our jquery.colorblock.js file.

Note: Most of you are probably not familiar with Starter for jQuery, or the code it puts out. I plan on writing an article about it sometime, but for this article remember these important principles. Anywhere in the plugin class itself ($.ColorBlock for example) base refers to base object. And base.el and base.$el refer to the DOM element and the jQuery wrapped DOM element the base object is connected to.

The plugin supports override-able options. We need to use this for our plugin, so find the $.ColorBlock.defaultOptions and paste this between the curly braces:

colors: ["red","blue","green","yellow"]

Now, we need to give our object the ability to change colors. Paste the following code after the base.init function definition (but before the base.init() call. That should always come last in the plugin) :

base.setColor = function(new_color_index){
	if( new_color_index != base.current_color_index ){
		base.current_color_index = new_color_index;
		base.$el.css({backgroundColor: base.options.colors[base.current_color_index]});
	}
}

base.nextColor = function(){
	var new_color_index = base.current_color_index + 1;
	if ( new_color_index > ( base.options.colors.length - 1 ) )
		new_color_index = 0;
	base.setColor( new_color_index );
}

base.getColor = function(){
	return base.options.colors[base.current_color_index];
}

This gives our object three methods. A method to set the color using an arbitrary index. A method to trigger the next color in the cycle. And finally a way to retrieve which color is currently in use. Nothing so far is rocket science.

Finally to enable our little widget, we add two lines of code to the base.init function after the line that initializes the options.

base.$el.click(function(){ base.nextColor(); });
base.setColor(0);

The first line triggers base.nextColor() every time our object is clicked. And the second line just initializes our object using the first color in the array (index position 0).

Now, if we load index.html in our browser, you will be able to cycle through the colors on each block simply by clicking on them.

In our make believe world, we can be happy that we made a working jQuery plugin. YAY! However, bad news also occurs in our world, and our client requests a way to monitor which colors are currently showing. So, along comes our ColorObserver widget.

Already we are making educational progress, because we realize the functionality to monitor all color_blocks is not the function of the ColorBlock widget (You do realize that right?).

ColorObserver

Our observer needs a method to find all ColorBlocks and find out which colors are showing. The following code should do the trick. Paste the following code into the jquery.colorobserver.js file, after the base.init definition, but before the base.init(); call.

base.discoverColors = function(){
	var colors_count = {};
	$(base.options.colorObjs).each(function(){
		var color = $(this).data('ColorBlock').getColor();

		if(!colors_count[color])
			colors_count[color] = 1;
		else
			colors_count[color] += 1;
	});

	var output = "";
	$.each(colors_count, function(key,value){
		output += key + "=" + value + "
";
	})
	base.$el.html(output);
}

In a nutshell, this code uses the selector from our defaultOptions or an overridden option to find which objects are ColorBlocks. It then gets the color, and either adds it to the colors_count array, or increases its count by one if it already exists. It then puts together a HTML snippet, and updates its base.$el content with our snippet. (Remember that base.$el refers to the jQuery wrapped DOM element we originally tied the widget to. In this case, #observer-one)

The Most Important Part

Now we need to tie to two objects together. You might be tempted to hardwire some $("#observer-one").getColorObserver().discoverColors() call into your setColor function over on the ColorBlocks. It would work for sure, but it makes your code more and more dependent on each other… making future changes more likely to break your code.

Instead we will use custom events to solve our problem. Put the following line inside the base.setColor function on the ColorBlock, inside the if statement as the last line:

base.$el.trigger('color_changed');

Now, any time the color changes on a single block, a ‘color_changed’ event fires. Now, put the following two lines in the base.init function of the ColorObserver class (After the options setup code):

$(base.options.colorObjs).live('color_changed', function(){ base.discoverColors(); });
base.discoverColors();

The first line binds to our custom event and tells the ColorObserver class to rediscover the visible colors. The second line is just the initial call to find out the starting state of the colors.

At this point our job is done, and our two widgets are correctly wired together. Load index.html up in your browser and see for yourself. Every time you change a block color, the observer knows about it and changes its data to match.

The best part is that you could delete the