Why are handler functions listed with arguments in the jQuery API documentation?

Question

In the jQuery manual itself it shows the blur function as:

.blur(handler(eventObject)) // PLUS 2 OTHER VARIATIONS

So to me using this function you would get something like this:

<!DOCTYPE html>
<html>
  <head>
    <script src="http://code.jquery.com/jquery-latest.js"></script>
  </head>
  <body>
    <form>
      <input id="target" type="text" value="Field 1" />
      <input type="text" value="Field 2" />
    </form>
    <div id="other">Trigger the handler</div>
    <script>
      $('#target').blur(myhandler(evObj));

      function myhandler(evObj) {
        console.log(evObj);
      };
    </script>
  </body>
</html>

But $('#target').blur(myhandler(evObj)); is not the correct syntax the correct syntax is really $('#target').blur(myhandler);

So overall the entire code for script tag should be:

<script>
  $('#target').blur(myhandler);

  function myhandler(e) {
    console.log(e);
  };
</script>

Why is this so?
How is someone supposed to know NOT to write .blur(handler(eventObject)) ?

You use the functionname() if you want to make use of the returned value. In this case, you don't. — Johan
– Johan, Commented Jan 10, 2013 at 12:52
Learning javascript basics before trying to make yetanothercoolappwithjquery would help a lot. ;) — Yury Tarabanko
– Yury Tarabanko, Commented Jan 10, 2013 at 13:01
I found myself in this situation in the past and realised that learning JavaScript through jQuery was the wrong aproach and if I wanted to understand jQuery properly I needed to learn JavaScript first. I found Mozilla Developer Documentation on Javascript extremly good for start. It answered a lot of question about behaviours which I thought were odd in jQuery but now make sense as that is how JavaScript works. — Nope
– Nope, Commented Jan 10, 2013 at 13:24
Francois I found the answer at learnjavascript.co.uk/jq/reference/events/blur.html before I posted the question, but I posted anyways. I didn't 'see' the answer at api.jquery.com/blur . I just wondered how others arrive at the correct answer from mimimal docs at jquery.com, and understand 'oh thats what they mean' which I don't get just yet. — jim dif
– jim dif, Commented Jan 10, 2013 at 13:34

Katriel · Accepted Answer · 2013-01-10 12:55:26Z

3

You are correct that the technically-correct syntax would be

blur(handler)

However, this isn't actually very useful, because if you're looking at the docs you probably want to know what arguments the handler receives. It's meant to be obvious that you call blur with a function as its sole argument, so the jQuery docs par abus de notation write

blur(handler(eventObj))

to indicate that the handler function takes one argument, the event object.

answered Jan 10, 2013 at 12:55

Katriel

124k19 gold badges141 silver badges172 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Blazemonger · Accepted Answer · 2013-01-10 20:43:35Z

In JavaScript, functions are just another kind of object. You've stumbled upon the big difference between writing myfunction and myfunction() -- the first is the function object, the second is the return value of that function.

So: $('#target').blur(...) is a method that accepts one object, which must be a function.

When you write $('#target').blur( myhandler(evObj) ), then the myhandler function is not passed to .blur(). Instead, the parentheses that follow it tell JavaScript to evaluate the function (using the argument evObj), and the function's return value is passed to .blur() instead.

If that return value happens to be another function object, then all is good. But if not, you'll get an error.

Usually, however, developers won't declare a separate function myhandler. Instead, we'll use an anonymous function like so:

$('#target').blur(function(evObj) {
    /* do stuff with evObj */
})

That's why the API docs write $('#target').blur( myhandler(evObj) ) -- so developers know what arguments are accepted by the anonymous handler function.

Collectives™ on Stack Overflow

Why are handler functions listed with arguments in the jQuery API documentation?

2 Answers 2

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related