jQueryPlugin: return this vs return this.each()

Question

Yes, there are many topics about that, but I still didn't get it.

I prepared two jsfiddle:

return this

return this.each()

What's the difference? There any many answers, but my examples show the same output. So some some of these answers might be wrong!?

---

what does "return this.each()" do in jQuery?

"It allows for one to call a plugin or an event on a bunch of elements and then apply that same function or event to all of them" --> work's with return this as well

"It allows you to chain multiple functions" --> same here

"Allows you to do things like: $("mySelector").foo().show();" --> I still can do this as well, when I use return this

---

I also created another jsfiddle that shows - in my opinion - that it doesn't matter if you're wrapping you code into return this.each();:

http://jsfiddle.net/7S3MW/1/

The Chrome Console shows the same output!

So what's the difference?

Answer 1

Two things:

1. Your examples are flawed in that they do exactly the same thing to each element.
2. The real issue isn't return this versus return this.each, the issue is this versus this.each.

For (1), consider the difference between this plugin:

(function($) {
    $.fn.mangle = function(options) {
        this.append(' - ' + this.data('x'));
        return this;
    };
})(jQuery);

Demo: http://jsfiddle.net/ambiguous/eyHeu/

And this plugin:

(function($) {
    $.fn.mangle = function(options) {
        return this.each(function() {
            $(this).append(' - ' + $(this).data('x'));
        });
    };
})(jQuery);

Demo: http://jsfiddle.net/ambiguous/5dMMH/

So you see, you need to use this.each if you need to treat the individual elements in the this set differently. You would have similar effects if your plugin had to attach element-specific data to each element: if you didn't use each then you'd end up attaching the exact same piece of data to all of the elements inside this and that would just leave you confused about why information is bleeding all over the place.

For (2), it doesn't matter if you return this or return this.each(... since x.each(...) returns x anyway.

Answer 2

Let me show you two "equivalent" pieces of code that could clarify your question:

With jQuery "each" function:

(function($) {
    $.fn.mangle = function(options) {
        return this.each(function() {
            $(this).append(' - ' + $(this).data('x'));
        });
    };
})(jQuery);

Without jQuery "each" function:

(function($) {
    $.fn.mangle = function(options) {
        var objs = this;
        for (var i=0; i<objs.length; i++) {
            var obj = objs[i];
            $(obj).append(' - ' + $(obj).data('x'));
        };
        return this;
    };
})(jQuery);

So, basically, each function is used to apply some code to all elements contained in this object (as this usually refers to a group of elements returned by a jQuery selector) and return the reference to this (as each function always returns that reference -to allow chaining calls-)

As a side note: The second approach (-for loop-) is faster (notably on old browsers) than former one (-each function-).