I'd like to understand the jQuery plugin syntax - javascript

The jQuery site lists the basic plugin syntax for jQuery as this:
(function( $ ){
$.fn.myPlugin = function() {
// there's 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'd just like to understand what is going on there from Javascript's point of view, because it doesn't look like it follows any syntax I've seen JS do before. So here's my list of questions:
If you replace function($)... with a variable, say "the_function", the syntax looks like this:
(the_function)( jQuery );
What is "( jQuery );" doing? Are the parenthesis around the_function really necessary? Why are they there? Is there another piece of code you can give that is similar?
It begins with function( $ ). So it's creating a function, that as far as I can tell will never be run, with the parameter of $, which is already defined? What is going on there?
Thanks for the help!

function(x){
x...
}
is just a function without a name, that takes one argument, "x", and does things with x.
Instead of 'x', which is a common variable name, you can use $, which is a less common variable name, but still legal.
function($){
$...
}
I'll put it in parentheses to make sure it parses as an expression:
(function($){
$....
})
To call a function, you put () after it with a list of arguments. For example, if we wanted to call this function passing in 3 for the value of $ we would do this:
(function($){
$...
})(3);
Just for kicks, let's call this function and pass in jQuery as a variable:
(function($){
$....
})(jQuery);
This creates a new function that takes one argument and then calls that function, passing in jQuery as the value.
WHY?
Because writing jQuery every time you want to do something with jQuery is tedious.
WHY NOT JUST WRITE $ = jQuery?
Because someone else might have defined $ to mean something else. This guarantees that any other meanings of $ are shadowed by this one.

(function( $ ){
})( jQuery );
That is self-executing anonymous function that uses $ in argument so that you can use it ($) instead of jQuery inside that function and without the fear of conflicting with other libraries because in other libraries too $ has special meaning. That pattern is especially useful when writing jQuery plugins.
You can write any character there instead of $ too:
(function(j){
// can do something like
j.fn.function_name = function(x){};
})(jQuery);
Here j will automatically catch up jQuery specified at the end (jQuery). Or you can leave out the argument completely but then you will have to use jQuery keyword all around instead of $ with no fear of collision still. So $ is wrapped in the argument for short-hand so that you can write $ instead of jQuery all around inside that function.
If you even look at the source code of jQuery, you will see that everything is wrapped in between:
(function( window, undefined ) {
// jQuery code
})(window);
That is as can be seen also a self-executing anonymous function with arguments. A window (and undefined) argument is created and is mapped with global window object at the bottom (window). This is popular pattern these days and has little speed gain because here window is will be looked into from the argument rather than global window object which is mapped below.
The $.fn is jQuery's object where you create your new function (which is also an object) or the plugin itself so that jQuery wraps your plugin in its $.fn object and make it available.
Interestingly, I had answered similar question here:
JavaScript / jQuery closure function syntax
You can also check out this article to know more about self-executing functions that I had written:
Javascript Self-executing Functions

The basic plugin syntax allows you to use $ to refer to jQuery in the body of your plugin, regardless of the identify of $ at the time the plugin is loaded. This prevents naming conflicts with other libraries, most notably Prototype.
The syntax defines a function that accepts a parameter known as $ so you can refer to it as $ in the function body, and then immediately invokes that function, putting jQuery in as the argument.
This also helps not pollute the global namespace (so declaring var myvar = 123; in your plugin body won't suddenly define window.myvar), but the main ostensible purpose is to allow you to use $ where $ may have since been redefined.

You're dealing with a self-invoking anonymous function there. It's like "best practice" to wrap a jQuery plugin within such a function to make sure, that the $ sign is bound to the jQuery object.
Example:
(function(foo) {
alert(foo);
}('BAR'));
This would alert BAR when put into a <script> block. The parameter BAR is passed to the function which calls itself.
The same principle is happening in your code, the jQuery object is passed to the function, so $ will refer to the jQuery object for sure.

The jQuery at the end passes itself (jQuery) over to the function, so that you can use the $ symbol within your plugin. You ccould also do
(function(foo){
foo.fn.myPlugin = function() {
this.fadeIn('normal', function(){
});
};
})( jQuery );

To find a clear explanation of this and other modern javascript tricks and common practices, I recommend reading Javascript Garden.
http://bonsaiden.github.com/JavaScript-Garden/
It's especially useful, because many of these patterns are widely used in many libraries but not really explained.

The other answers here are great, but there is one important point that hasn't been addressed. You say:
So it's creating a function, that as far as I can tell will never be run, with the parameter of $, which is 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 $ is set back to whatever it was before the jQuery library was included. This allows jQuery to be used with other Javascript libraries that also use $ as a global variable.
If you wrote a plugin that relied on $ being an alias for jQuery, then your plugin would not work for users running in noConflict mode.
As others have already explained, the code you posted creates an anonymous function that is called immediately. The global variable jQuery is then passed in to this anonymous function, which is safely aliased as the local variable $ within the function.

Related

Anonymous functions syntax in jQuery

I have read lots of articles regarding jQuery and its syntax. However I have not fully understood its syntax and I would really like to get a better and deeper understanding of it.
Many articles fail to point out the simple syntax rules (and what they are necessary for).
As of right now I am experiencing a syntax-understanding-problem:
my HTML:
<body>
jQuery.com
jQuery.com
jQuery.com
<!-- JQUERY -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script>
(function ($) {
// EXAMPLE 1
$("a").each(function () {
console.log(this.title);
});
})(jQuery); // ... everything works fine.
(function ($) {
// EXAMPLE 2
$("a").each(function () {
console.log(this.title);
});
}); // ... missing (jQuery). Why isn't this working?
$(function () { // ... notice the $ at the beginning.
// EXAMPLE 3
$("a").each(function () {
console.log(this.title);
});
}); // ... missing (jQuery). Why IS this working?
// EXAMPLE 4
$("a").each(function () {
console.log(this.title);
}); // ... everything works fine.
</script>
</body>
I will clarify how I understand the code, and I would absolutely appreciate if you answer me in a very basic manner. Please do point out all my misunderstandings!
My Understanding and Questions so far:
Example 1: I create an anonymous JavaScript-function. This function is executed right in that moment the browser reads it. I pass it the jQuery-Object (with ($) but I don't know why this is important at that point). From now on my function 'speaks' jQuery (it understands its syntax - I am assuming). At the very end of my JavaScript-function I pass it the jQuery object again (but why would that be necessary?). Please enlighten me.
Example 2: I tried the same function without the (jQuery) at the end. Now it is not working. I understand what is missing. But why is that (jQuery) at the end so important?
Example 3: Now I STARTED my Javascript-function with the $ and I assume that from now on my whole function is WRAPPED inside a jQuery object. Inside this jQuery-object my function understands jQuery syntax. At the end NO (jQuery) is needed.
Example 4: Here I did NOT build a JavaScript function. I just use jQuery to select and return the ("a"). This code gets executed right in the second the browser reads it. No waiting for the document to be ready.
My Question basically is:
In Example 1, why is that ($) at the beginning AND the (jQuery) at the end necessary? What is the purpose?
I would really appreciate longer answers where I can get a deeper understanding of "reading jQuery syntax correctly" and speaking about jQuery syntax and what it requires. Thanks.
I create an anonymous JavaScript-function. This function is executed right in that moment the browser reads it.
Not quite. You create a function expression.
function () { }
You then follow it with () which calls it a moment later.
You could have done it like this:
var myfunction = function ($) { ... };
myfunction(jQuery);
I pass it the jQuery-Object (with ($) but I don't know why this is important at that point).
No. You are defining a function. It accepts a single argument, the value of which gets assigned to a local variable called $.
From now on my function 'speaks' jQuery (it understands its syntax - I am assuming).
Syntax belongs to JavaScript, not jQuery.
At the very end of my JavaScript-function I pass it the jQuery object again (but why would that be necessary?). Please enlighten me.
You are passing the jQuery object for the first time. It is the argument you are passing to the function when you call it. The value of jQuery (the jQuery object) is assigned to the local $ variable.
This is used for two purposes:
It lets you use the $ variable without worrying about it being overwritten by Prototype JS, Mootools, or any of the other libraries that thought it was a good idea to use something as generic as $ as a variable name.
It lets you have local variables that won't pollute the global scope.
I tried the same function without the (jQuery) at the end. Now it is not working. I understand what is missing. But why is that (jQuery) at the end so important?
The () are important because without them you won't call the function.
The jQuery is important because otherwise $ would be undefined within the function.
Now I STARTED my Javascript-function with the $
Here you are calling the function $() with your function expression as the argument.
$ is a horribly overloaded function that does many different things depending on what type of argument you pass it.
If you pass it a function, then it will assign that function as a document ready event handler.
When the DOM has finished loading, the event will fire and the function will be called.
Here I did NOT build a JavaScript function. I just use jQuery to select and return the ("a"). This code gets executed right in the second the browser reads it. No waiting for the document to be ready.
Yes
First off, there is no "jQuery syntax". jQuery is a library, written in JavaScript, so the syntax is JavaScript.
Example 1: I create an anonymous JavaScript-function. This function is executed right in that moment the browser reads it. I pass it the jQuery-Object (with ($) but I don't know why this is important at that point). From now on my function 'speaks' jQuery (it understands its syntax - I am assuming). At the very end of my JavaScript-function I pass it the jQuery object again (but why would that be necessary?). Please enlighten me.
You seem to know how functions and arguments work. So look at your code:
(function ($) {
// EXAMPLE 1
$("a").each(function () {
console.log(this.title);
});
})(jQuery);
You define an anonymous function that takes one argument: a variable named $, which you use in the statement $("a"). Then you call your anonymous function and pass it the jQuery object, so inside the function, $ === jQuery.
Example 2: I tried the same function without the (jQuery) at the end. Now it is not working. I understand what is missing. But why is that (jQuery) at the end so important?
Without the () at the end, you're not even calling your function. You just define it and then lose it since you're not assigning it to a variable.
If you put just (), it won't work either because the function argument $ would be undefined and override the global $ (window.$).
However, if you declared the function just as function(), I think it would work because $ would then refer to window.$.
Example 3: Now I STARTED my Javascript-function with the $ and I assume that from now on my whole function is WRAPPED inside a jQuery object. Inside this jQuery-object my function understands jQuery syntax. At the end NO (jQuery) is needed.
Now you call $ as a function with one argument: your anonymous function.
Example 4: Here I did NOT build a JavaScript function. I just use jQuery to select and return the ("a"). This code gets executed right in the second the browser reads it. No waiting for the document to be ready.
Yes you do build a function, and you pass it as argument to the each() function of the object that $("a") returns.
My Question basically is:
In Example 1, why is that ($) at the beginning AND the (jQuery) at the end necessary? What is the purpose?
What's the purpose of arguments to functions?
But what you don't seem to understand: $ is just a variable (or a function if you want, but in JS functions are variables).
The solution to your problem comes down to understanding closures within JavaScript ... and not so much jQuery - jQuery is just using closures.
With a closure you can scope the content that is within and also pass arguments to that closure for use within.
For your example 2, if you pass in jQuery to the closure it would work fine.
Like:
(function ($)
{
$("a").each(function () {
console.log(this.title);
});
})(jQuery); // arguments passed in here
Becuase you do not pass in jQuery at the end then the argument $ is undefined and therefore cannot be called in the case of $('a'). When written the way I have changed it jQuery is assigned to the $ argument, which is available to the code which is inside the closure.
Similarly for your example 3, you are not passing in jQuery and you also have no variable $ within your closure so it will not work. Note that you could change it to be like (illustrative purposes only):
(function (thisIsJquery)
{
thisIsJquery("a").each(function () {
console.log(this.title);
});
})(jQuery);
Now jQuery is assigned to the argument thisIsJquery and it is available within the closure.
As for your exmaple 4, $ is being used within the closure it was defined in (and not another closure inside that) so it is readily available for use.
Closures are an excellent way to hide implementation and provide a way to make things private in JavaScript.
Further reading:
http://www.w3schools.com/js/js_function_closures.asp
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures
I'll only focus on what's not working. The following snippet:
(function ($) {
$("a").each(function () {
console.log(this.title);
});
}) // not calling function
First of all, you're not calling the function. So, anything inside it will not run. So, you might think that by adding () at last, might solve it.
But that's not all!
Because $ refers to jQuery, outside the snippet. But since you're including a named parameter as $ and not passing anything to it, the $ inside the snippet shadows the one outside. And since it's not assigned any value, it is undefined. So you'll end up with
undefined is not a function
To prove it, adding ($) will work, as now, the named parameter $ refers to the $ which points to jQuery.

Self-invoking function jQuery [duplicate]

This question already has answers here:
What is the purpose of this? (function ($) { //function code here })(jQuery);
(4 answers)
Closed 9 years ago.
I noticed that in some places, jQuery code is wrapped in a self-invoking function like below. Why is this done, in what cases is this useful and in what cases is an unnecessary boilerplate?
function( $ ) {
...
}( jQuery );
The short answer: To prevent variable name conflicts. It is not always needed, but good practice in order to create conflict free reusable code.
The long answer: In javascript the $ symbol is just another variable. jQuery uses it because it is a nice shorthand instead of having to type out jQuery each time, but so can any other code (including other libraries).
To prevent conflict with other uses of a variable at the same scope (in this case $ at the "global" scope) it is common for code to be wrapped in a self-invoking function with the "conflict-free" variables passed as the function parameters. This then creates a new scope where your variable won't interfere with other uses of that variable. That way you can pass the full named variable & uses it with whatever name you want within the anonymous function.
So, when creating conflict free reusable code it is good practice to use this methodology:
(function( $ ) {
...
})( jQuery );
Along these lines you will also see the following format:
(function( $, window, undefined ) {
...
})( jQuery, window );
In this instance undefined is simply used for readability to indicating that no more arguments are passed to the function.
In case you want to avoid conflict regarding use of $
function( $ ) {
...
}( jQuery );
Inside this function you can use $ without having to worry about it's use outside of it as inside that function, $ always refers to the jQuery object.
This is helpful while creating jQuery plugins,You will see jQuery plugin's use this kind of function to avoid conflicts with other plugins.
Reference : http://learn.jquery.com/plugins/basic-plugin-creation/
In function scope $ is local variable that not conflict with any other global $.

function call with '$' as parameter

I have a script which contains the following piece of code:
(function ($) {
// ...
})($);
Can anyone explain how to read it?
Create an anonymous function
Let it take one argument which will be called $
Call the function immediately
Pass it one argument which is whatever the value of $ is in the outer scope.
If the $ in the outer scope changes (by having a new value assign to it) then the value for $ in the inner scope will be protected from the change (since it is a different variable).
This also provides a clean scope for all other variables declared inside the function (if they use var as they should).
'$' is a legal variable in JavaScript. It could have just as easily been someCrazyLongVariableName
It kind of defeats the purpose of encapsulating the $ sign into an anonymous function.
It's a self executing anonymous function that takes $ as argument.
In most of the cases, you use this markup to avoid js libraries collisions : say that you want to use jQuery and prototype in your project. Very nice, but they both use the '$' sign... how to overcome this?
// jquery code here
(function($){
alert($ === jQuery);// the $ is a shortcut to jQuery
})(jQuery);
// non-jquery code here - ex: prototype
alert($ === jQuery);// the $ is NOT a shortcut to jQuery ANYMORE
If you're not thinking about the $ in particular, the extract is creating a javascript function and calling it in a single statement.
I'm not 100% sure, but i guess that the 2 $ variables would be a different scope.
I found this page useful, if a little verbose: -
http://www.authenticsociety.com/blog/JavaScript_DollarSign
In summary, it's no different to calling the variable a, but should be avoided.

$(document).ready shorthand

Is the following shorthand for $(document).ready?
(function($){
//some code
})(jQuery);
I see this pattern used a lot, but I'm unable to find any reference to it. If it is shorthand for $(document).ready(), is there any particular reason it might not work? In my tests it seems to always fire before the ready event.
The shorthand is:
$(function() {
// Code here
});
The shorthand for $(document).ready(handler) is $(handler) (where handler is a function). See here.
The code in your question has nothing to do with .ready(). Rather, it is an immediately-invoked function expression (IIFE) with the jQuery object as its argument. Its purpose is to restrict the scope of at least the $ variable to its own block so it doesn't cause conflicts. You typically see the pattern used by jQuery plugins to ensure that $ == jQuery.
The correct shorthand is this:
$(function() {
// this behaves as if within document.ready
});
The code you posted…
(function($){
//some code
})(jQuery);
…creates an anonymous function and executes it immediately with jQuery being passed in as the arg $. All it effectively does is take the code inside the function and execute it like normal, since $ is already an alias for jQuery. :D
Even shorter variant is to use
$(()=>{
});
where $ stands for jQuery and ()=>{} is so called 'arrow function' that inherits this from the closure. (So that in this you'll probably have window instead of document.)
This is not a shorthand for $(document).ready().
The code you posted boxes the inside code and makes jQuery available as $ without polluting the global namespace. This can be used when you want to use both prototype and jQuery on one page.
Documented here: http://learn.jquery.com/using-jquery-core/avoid-conflicts-other-libraries/#use-an-immediately-invoked-function-expression
The multi-framework safe shorthand for ready is:
jQuery(function($, undefined) {
// $ is guaranteed to be short for jQuery in this scope
// undefined is provided because it could have been overwritten elsewhere
});
This is because jQuery isn't the only framework that uses the $ and undefined variables
These specific lines are the usual wrapper for jQuery plugins:
"...to make sure that your plugin doesn't collide with other libraries that might use the dollar sign, it's a best practice to pass jQuery to a self executing function (closure) that maps it to the dollar sign so it can't be overwritten by another library in the scope of its execution."
(function( $ ){
$.fn.myPlugin = function() {
// Do your awesome plugin stuff here
};
})( jQuery );
From http://docs.jquery.com/Plugins/Authoring
What about this?
(function($) {
$(function() {
// more code using $ as alias to jQuery
// will be fired when document is ready
});
})(jQuery);

a simple question on jquery closure

what does this mean?
(function($){
})(jQuery);
to make the question clearer, what does wrapping a function in parenthesis mean in JS (sorry, I'm a bit confused on the concept of closures). What about the $ parameter? and the "jQuery" in the end parenthesis?
Can I do the same with mootools and combine them in 1 JS file?
(function($){})(jQuery);
(function($){})(mooTools);
I have only worked with jquery and am planning to work with Mootools
Wrapping a function between parenthesis ensures this function to be evaluated as a function expression.
That happens because the Grouping Operator (the parentheses), can only evaluate expressions.
If no parenthesis are used, it will be interpreted as a function declaration, and it will cause a syntax error, since the function name is not optional for function declarations.
(function(arg){
alert(arg); // alerts test
})("test");
In the above example, the function expression is automatically executed, passing an argument.
That pattern is heavily used by jQuery plugins, since jQuery can run in noConflict mode, the $ global variable will not be created, so the jQuery global object is passed as an argument of this anonymous function and inside of that function, you can freely refer to it as $ (the received argument).
Keep in mind that also, the function context (the this keyword) inside self-executing function expressions invoked like the above example, will refer always to the Global object.
For a more in-depth info about the differences between function expressions and function declarations, give a look to the following resources:
Explain JavaScript’s encapsulated anonymous function syntax
Named function expressions demystified
CMS have given you the correct answer but I just want to add that this is not a closure. This is just the () operator being used to return the result of an expression which in this case is a function expression and the fact that in javascript, a returned anonymous function can be called directly. So this is simply combining both:
var x = (1+1); // <-- () evaluates an expression
and:
var arr = [0,1,2];
arr.push(function(text){alert(text)});
arr[3]('hello'); // <-- function returned by array called directly
And as for the $ parameter, that's just one of the characters that javascript allows for variable names. Your examples is exactly equivalent to:
(function(jQ){})(jQuery);
(function(moo){})(mooTools);
The main point for doing this is so that objects created within the function's expression can be utilized from properties and methods attached to passed in objects, without exposing those objects publicly. This can aid in preventing variable collisions. It also allows for variables created to be accessed as private storage for anything that is attached..
(function($){
//jQuery is available here as $
var myPrivateArray = []; //this is private
$.addItem = function(item) {
myPrivateArray.push(item);
}
})(jQuery);
//I can't access myPrivateArray here...
//but I can use jQuery.addItem to add something.
Here is an article on closures: http://www.jibbering.com/faq/faq_notes/closures.html
Basically, as CMS has said, it is a function expression. There is a perfect example to help you better understand about 2/3 of the way down that page.
The jQuery in the last set of parentheses means you're passing the jQuery object to the inner function. That inner function takes the object and it is assigned as $. So, when you're accessing the $ inside the function, you're actually acting upon the jQuery object you've passed.
As for mixing these with jQuery and Mootools, I've never used Mootools so I'm not sure how it assigns itself. The only thing I would think is that if it uses $ like jQuery, you can call jQuery.noConflict(); and reassign jQuery to another variable, maybe var $j = jQuery; Then, you can use Mootools as you normally would.
function($) { ... } creates a function that accepts a parameter called $.
Wrapping in in parentheses does nothing.
Adding (jQuery) calls the function with jQuery as a parameter.
This is done to make the function independent of $ in the global scope.
When you write $ in the function, you're referring to the parameter $, not the global variable $.
the mootools equivalent for namespacing $ is:
(function($) {
// $ is the mootools one (aliasing document.id)
})(document.id);
you can combine them into one file, but keep in mind that mootools is a prototypical framework and $ only serves the purpose of a selector whereas all functions go into the element/array/class etc prototypes. hence doing this in mootools works:
var foo = $("bar");
foo.hide(); // the element inherits .hide()
but in jquery it will fail and needs to be transcribed as
var foo = $("#bar");
$(foo).hide();
the point is, you can't namespace the stuff that mootools exports into prototypes.

Categories

Resources