What are the "response" and "request" arguments in jQuery UI Autocomplete's "source" callback?

Question

I'm looking at the autocomplete tutorial, and I have a few questions: http://jqueryui.com/demos/autocomplete/#option-disabled

$( "#tags" )
            // don't navigate away from the field on tab when selecting an item
            .bind( "keydown", function( event ) {
                if ( event.keyCode === $.ui.keyCode.TAB &&
                        $( this ).data( "autocomplete" ).menu.active ) {
                    event.preventDefault();
                }
            })
            .autocomplete({
                minLength: 0,
                source: function( request, response ) {
                    // delegate back to autocomplete, but extract the last term
                    response( $.ui.autocomplete.filter(
                        availableTags, extractLast( request.term ) ) );
                },
                focus: function() {
                    // prevent value inserted on focus
                    return false;
                },
                select: function( event, ui ) {
                    var terms = split( this.value );
                    // remove the current input
                    terms.pop();
                    // add the selected item
                    terms.push( ui.item.value );
                    // add placeholder to get the comma-and-space at the end
                    terms.push( "" );
                    this.value = terms.join( ", " );
                    return false;
                }
            });

So I understand the parameters for source is request and response. Are these reserved keywords? I couldn't find anything when typing this into google. I am unclear as to what is the request and response being passed into here. Is the request just grabbing the input? Where can I read up more on this?

Cimino

I would console log many of those console.log(response). You could then see what the objects are. Also - console.log(typeof response) might help you too. – Dobbs

Answer 1

request and response are simply the names that the author of the code has chosen to give to the two formal parameters of the callback assigned to the source option of the autocomplete widget:

Autocomplete can be customized to work with various data sources, by just specifying the source option. A data source can be:

• an Array with local data
• a String, specifying a URL
• a Callback

The third variation, the callback, provides the most flexibility, and can be used to connect any data source to Autocomplete. The callback gets two arguments:

• A request object, with a single property called "term", which refers to the value currently in the text input. For example, when the user entered "new yo" in a city field, the Autocomplete term will equal "new yo".
• 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.

Corena

Answer 2

No, request or response are not reserved keywords – if they were, you couldn't use them as function parameter names..

What's going on here is pretty simple, and if you ever do anything in Node you'll see the pattern. It's async JavaScript.

You're passing an anonymous function to source. This function is called whenever autocomplete needs to query the datasource (in other words, the user typed something).

The function's parameters are request and response. request is simply the information autocomplete is requesting; request.term is the query (what the user typed). It's up to you how to implement the search – maybe you have a local variable with possibilities or you might make an AJAX call to the server.

Now the important part: if you're making an AJAX call, you can't simply return a value from source() because the function will return long before the AJAX call completes. That's why there's a response parameter.

response is a function reference passed to your source() function that you call whenever you have the answer to the request. Through the magic of closures, you can call this function from inside an AJAX callback.

response (which could less confusingly be named callback) expects an array of strings or of objects with label and value properties. It will show those results in the autocomplete dropdown.

Putting it all together:

$('selector').autocomplete({
    ...
    source: function(request, response) {
        // calculate results for a query.
        response([{ label: 'Example', value: 'ex'  }]);
    }
});

Thickskinned

Answer 3

It's clearly documented in the jQuery UI autocomplete page.

http://jqueryui.com/demos/autocomplete/

The third variation, the callback, provides the most flexibility, and can be used to connect any data source to Autocomplete. The callback gets two arguments:

A request object, with a single property called "term", which refers to the value currently in the text input. For example, when the user entered "new yo" in a city field, the Autocomplete term will equal "new yo".

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.

Talipes

I don't think that is clearly documented. It's rather uncomprehensible if you're not accustomed to jQuery's semantics. – Inductee

There are a number of posts on SO saying that such and such jQuery facility/idea/assumption/what-have-you is clearly documented on such-and-such page. The problem is that these documentation bits are buried inside several layers of redirection, and worse, the documentation URL on jQuery site is not updated when something is clicked. In this case (of the answer above), if you click the link mentioned in the answer, it does not provide the information. You should then have to click on "API documentation" and then search for "callback" to arrive at the aforementioned answer's text. – Expropriate