JQuery UI Autocomplete Syntax

Question

Can someone help me understand the following code? I found it here.

It takes advantage of the JQuery UI Autocomplete with a remote source. I've commented the code as best I can and a more precise question follows it.

    $( "#city" ).autocomplete({
        source: function( request, response )  {
//request is an objet which contains the user input so far
// response is a callback expecting an argument with the values to autocomplete with
            $.ajax({
                url: "http://ws.geonames.org/searchJSON", //where is script located 
                dataType: "jsonp", //type of data we send the script
                data: { //what data do we send the script 
                    featureClass: "P",
                    style: "full",
                    maxRows: 12,
                    name_startsWith: request.term
                },
                success: function( data ) { //CONFUSED!
                    response( 
                        $.map( 
                        data.geonames, function( item ) { 
                                            return {
                                                    label: item.name+(item.adminName1 ? ","+item.adminName1:"")+","+item.countryName,   
        value: item.name
                                            }
                                        }
                        )
                    );
                  }
            });
        }
    });

As you can see, I don't understand the use of the success function and the response callback.

I know the success function literal is an AJAX option which is called when the AJAX query returns. In this case, it seems to encapsulate a call to the response callback? Which is defined where? I thought by definition of a callback, it should be called on its own?

Thanks!

Answer 1

The response object as defined by the documentation ("Overview" page):

A response callback, which expects a single argument to contain the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data (String-Array or Object-Array with label/value/both properties). It's important when providing a custom source callback to handle errors during the request. You must always call the response callback even if you encounter an error. This ensures that the widget always has the correct state.

so, the 'response' argument is actually a callback, which must be called upon success of the ajax retrieval of autocomplete items.

Since your data will come back via AJAX, your code must update the widget manually. jQueryUI provides an argument as a function so that your code can do that update by calling the function.

You can see the response object defined in the declaration of the function used for the source option:

source: function( request, response )

You could even take the AJAX call out of the equation and do something like this:

source: function(request, response) {
    response([{label:'foo', value: 'foo'},{label:'bar', value:'bar'}]);
}

Would immediately call the response callback with an array of label/value pairs for the widget.