I would like to understand the syntax of jQuery plugin

Question

The jQuery site provides the basic syntax for the jQuery plugin:

(function( $ ){ $.fn.myPlugin = function() { // there no need to do $(this) because // "this" is already a jquery object // $(this) would be the same as $($('#element')); this.fadeIn('normal', function(){ // the this keyword is a DOM element }); }; })( jQuery ); 

I just wanted to understand what is going on there from a Javascript point of view, because it does not look like any syntax I have seen before. So here is my list of questions:

• If you replace the function ($) ... with a variable, say, "the_function", the syntax is as follows:

    (the_function)( jQuery ); 

  What is "(jQuery)"; do? Do you need parentheses around a function? Why are they there? Is there any other code you can give that is similar?

• It starts with a function ($). So this is creating a function that, as far as I can tell, will never be run, with the $ parameter already defined? What is happening there?

Thanks for the help!

Answer 1

 function(x){ x... } 

is just an unnamed function that takes a single argument "x" and does things with x.

Instead of "x", which is the common name of a variable, you can use $, which is a less common variable name, but still legal.

 function($){ $... } 

I will put it in parentheses to make sure that it parses the expression:

 (function($){ $.... }) 

To call a function, you put () after it a list of arguments. For example, if we wanted to call this function, passing through 3 for the value of $ , we would do this:

 (function($){ $... })(3); 

Just for hits, call this function and pass jQuery as a variable:

 (function($){ $.... })(jQuery); 

This creates a new function that takes one argument, and then calls that function, passing the value to jQuery.

Why?

• Since writing jQuery every time you want to do something with jQuery is tedious.

WHY DO NOT ONLY WRITE $ = jQuery ?

• Because someone else could have defined $ to mean something else. This ensures that any other $ values ​​are obscured by this.

Answer 2

---

 (function( $ ){ })( jQuery ); 

This is a self-signed anonymous function that uses the $ argument in the argument so that you can use it ( $ ) instead of jQuery inside this function and not be afraid to run into other libraries, because in other libraries, $ also has special meaning. This template is especially useful when writing jQuery plugins.

You can also write any character instead of $ :

 (function(j){ // can do something like j.fn.function_name = function(x){}; })(jQuery); 

Here j will automatically catch up with the jQuery specified at the end (jQuery) . Or you can completely exclude the argument, but then you have to use the jQuery keyword around, not $ , without fear of a collision. So, $ enclosed in an argument for short hands, so you can write $ instead of jQuery inside this function.

Even if you look at the jQuery source code, you will see that everything is wrapped between:

 (function( window, undefined ) { // jQuery code })(window); 

This is the same as a self-starting anonymous function with arguments. The window argument (and undefined ) is created and displayed by the global window object at the bottom (window) . This is a popular pattern these days and has a slight increase in speed, because here the window will be studied from the argument, and not from the global window object that is displayed below.

---

$.fn is a jQuery object in which you create your new function (which is also an object) or the plugin itself, so jQuery wraps your plugin in its $.fn object and makes it available.

---

Interestingly, I answered a similar question:

JavaScript / jQuery close function syntax

You can also check this article to find out more about the self-contained functions that I wrote:

Javascript Self-Completion Functions

Answer 3

The syntax of the main plugin allows you to use $ to denote jQuery in the body of your plugin regardless of the identification of $ during plugin loading. This prevents name conflicts with other libraries, primarily Prototype.

The syntax defines a function that takes a parameter known as $ , so you can refer to it as $ in the body of the function, and then immediately call that function, inserting jQuery as an argument.

It also helps not to pollute the global namespace (therefore, the declaration var myvar = 123; window.myvar will not be defined in your plugin module), but the main supposed purpose is to allow you to use $ , where $ may have since been redefined.

Answer 4

You are dealing with a self-naming anonymous function. It's like "best practice" to wrap a jQuery plugin inside such a function to make sure that the $ sign is bound to a jQuery object.

Example:

 (function(foo) { alert(foo); }('BAR')); 

This will warn the BAR when entering the <script> block. The BAR parameter is passed to the function that itself calls.

The same principle happens in your code, the jQuery object is passed to the function, so $ will refer to the jQuery object exactly.

Answer 5

jQuery at the end passes itself (jQuery) to the function, so you can use the $ character in your plugin. You can also do

 (function(foo){ foo.fn.myPlugin = function() { this.fadeIn('normal', function(){ }); }; })( jQuery ); 

Answer 6

To find a clear explanation of this and other modern tricks and common javascript practices, I recommend reading the Javascript Garden.

http://bonsaiden.github.com/JavaScript-Garden/

This is especially useful since many of these templates are widely used in many libraries, but are not explained.

Answer 7

The other answers here are wonderful, but there is one important point that has not been considered. You speak:

So this creates a function that, as far as I can tell, will never be run, with the $ parameter already defined?

There is no guarantee that the global variable $ is available . By default, jQuery creates two variables in the global scope: $ and jQuery (where the two are aliases for the same object). However, jQuery can also be run in noConflict mode :

 <script type="text/javascript" src="jquery.js"></script> <script type="text/javascript"> jQuery.noConflict(); </script> 

When you call jQuery.noConflict() , the global variable $ set to everything that was before the jQuery library was included. This allows you to use jQuery with other Javascript libraries, which also use $ as a global variable.

If you wrote a plugin in which $ was an alias for jQuery, your plugin will not work for users working in noConflict mode.

As others have already explained, the code you submitted creates an anonymous function that is called immediately. Then, the jQuery global variable is passed to this anonymous function, which is safely pseudo-lowering as the local $ variable inside the function.