Explaining jQuery AJAX Success Method

Question

Im trying to use this jQuery script and this is confusing me:

function CallService() 
        {
                $.ajax({
                    type        : varType, //GET or POST or PUT or DELETE verb
                    url         : varUrl, // Location of the service
                    data        : varData, //Data sent to server
                    contentType : varContentType, // content type sent to server
                    dataType    : varDataType, //Expected data format from server
                    processdata : varProcessData, //True or False
                    success     : function(msg) {//On Successfull service call
                    ServiceSucceeded(msg);                    
                    },
                    error: ServiceFailed// When Service call fails
                });
        }

The bit im confused about is the sucess object. The jQuery documentation says:

success(data, textStatus, jqXHR)Function, Array

A function to be called if the request succeeds. The function gets passed three arguments: The data returned from the server, formatted according to the dataType parameter; a string describing the status; and the jqXHR (in jQuery 1.4.x, XMLHttpRequest) object. As of jQuery 1.5, the success setting can accept an array of functions. Each function will be called in turn. This is an Ajax Event.

But this method signature looks nothing like the:

success     : function(msg) {//On Successfull service call
                        ServiceSucceeded(msg);                    
                        }

Object that we seem to be passing in.

Questions:

1) What does function(msg){ServiceSucceeded(msg)} mean?

2) What is 'msg' in this context?

3) How on earth am I meant to know how to structure the method sugnature for sucess?

Answer 1

Perfectly reasonable question. :-) In JavaScript, you don't necessarily have to call a function with as many args as it defines, and you don't have to define as many args as you may get called with. Which can be confusing if you're used to more constrained environments. :-)

Answering specifics:

1) What does function(msg){ServiceSucceeded(msg)} mean?

It defines a function (an anonymous one) that accepts one named argument (msg) and calls ServiceSucceded passing in that arg. jQuery will call the function with the three arguments defined by the jQuery documentation for the success function, but this particular success function is only using the first of those (data). More about named functions vs. anonymous functions here.

2) What is 'msg' in this context?

The first argument to the function. jQuery's docs call this first argument data, but you can call it whatever you like.

3) How on earth am I meant to know how to structure the method sugnature for sucess?

You did the right thing, it's in the jQuery documentation.

This thing about function arguments can be confusing, so let's do some examples:

function foo(arg) {
    alert(arg);
}

That's perfectly clear, I'm defining a function called foo that takes a single named argument, arg. And thus:

foo("Hi there"); // alerts "Hi there"

But I can also do this:

foo(); // alerts "undefined"

There, I didn't give any arguments for foo, and so within foo, arg is undefined.

I can also do this:

foo("Hi there", "again"); // alerts "Hi there"

I'm calling foo with two arguments, but foo only makes use of one of them.

I could define foo to use as many arguments as you pass in:

function foo() {
    var index;

    for (index = 0; index < arguments.length; ++index) {
        alert(arguments[index]);
    }
}

arguments is an automatic thing all functions have, which is a pseudo-array (it's not really an Array) of the actual arguments the function was called with. And so:

foo("Hi there", "again"); // alerts "Hi there", and then alerts "again"

You can even mix named and unnamed arguments:

function foo(arg) {
    var index;

    alert(arg);
    for (index = 1; index < arguments.length; ++index) {
        alert("[" + arguments[index] + "]");
    }
}

So now

foo("Hi there", "again"); // alerts "Hi there" and then alerts "[again]"

Note the [] around the second alert, because I started looping with index 1 rather than zero.

arguments and named args are connected:

function foo(arg) {
    alert("arg = " + arg);
    alert("arguments[0] = " + arguments[0]);
    arg = "Updated";
    alert("arg = " + arg);
    alert("arguments[0] = " + arguments[0]);
}

If I do foo("Hi");, that shows these alerts:

arg = Hi
arguments[0] = Hi
arg = Updated
arguments[0] = Updated

(It goes the other way, too, if you update arguments[0].)

Answer 2

The function is passed 3 parameters: data, status, and the jqXHR object. data is what is returned from the AJAX call, status is the HTTP status code (I think), and jqXHR is a jQuery wrapped XHR object.

In this script, they only care about the data parameter, and not the other two.

So using success: function(msg), they only get the data parameter. The other two are sent, but ignored.

ServiceSucceeded is just a function that is being called with the data parameter sent to it.

success: ServiceSucceeded could have also worked here.