Search jQuery

jQuery Forum

Developing jQuery Core

mike_laird

Documentation content

Working on it

Need more info
Working on it
Answered

in Developing jQuery Core • 12 years ago

I just finished looking at the documentation page for the change function. It shows a function with 2 arguments, as in

change( [ eventData ], handler(eventObject) )

The discussion and the examples don't talk about 2 arguments. It would be very helpful if they did.

I have seen tutorials with change functions written as

change: function(event, ui){ //do something}

This doesn't match up with the format above, or if it does, I need some explanation to understand. It seems this version has the event as the first argument.

I don't mean to pick on the change function. This seems to be a general phenomena in the documentation. Maybe someone could set some standards about documentation content and format for presenting it, and people could work towards it over time.

Lastly, it would be nice if the user comments at the bottom of the documentation sections had dates on them. It is hard to tell if I'm reading forward or backward in time, and impossible at times to tell if the user comment refers to a current version of jQuery. A lot has changed in jQuery and some of the user comments seem dated.

Replies(2)

kswedberg

Re: Documentation content

12 years ago

Hi Mike,

The function you refer to is just one of the three signatures listed for .change(). As you can see in the documentation, that signature was added very recently -- in jQuery 1.4.3. The first argument, eventData, is optional. So, you can keep using .change() the way it has always been used. But, if you want to pass in data to be used by the change handler, you can do so with that first argument. Basically, 1.4.3 added that argument to all of the event shortcut methods so they'd more closely match the feature set of .bind(), which has had it all along.

The examples you refer to that have change: function(event, ui) { } look very much to me like option methods for jQuery UI widgets. As such, they're probably not relevant here. However, all of jQuery's core event methods can take an argument in the callback function (the second argument of that two-argument signature), as well. This argument passed in, when called, is the event object.

I agree that the documentation should make mention of this new argument for the shortcut event methods. We'll make sure that it gets in there soon. In the meantime, you can read more about it at http://api.jquery.com/bind/#passing-event-data

--Karl

mike_laird

Re: Documentation content

12 years ago

Karl,

Thanks. In this change function example, some discussion and examples of the data passing argument would be helpful - like data in an option list versus data in a remote database. Similar expanded completeness and detail would be helpful in other documentation examples.

Yes, the change: function(event, ui) is an option method from Autocomplete. IMO, Autocomplete is only modestly documented. I have many questions after studying it, for example on just this single option method: does this option method perform the same function as the change event function, if not, what are the differences; if this option method is not relevant to the change event, why; what goes in the ui argument vs the event argument; how does one change 'term' and 'filter' in Autocomplete using this option method; what other useful internal Autocomplete variables can be changed; can the change event function make changes to 'term' and 'filter', if so, how; etc. etc.

I'm pretty new at jQuery with no background in JS, so some of my questions may not make sense to an experienced JS / jQuery developer, but it would be nice to have the jQuery documentation "lead the mind" so that the right questions come up for further investigation when working code, and nonsensical questions come to mind less often.

I don't mean to be critical, just helpful from the perspective of a jQuery newbie. JQuery rocks.

Top Reply

Response title

Attachments

jQuery Forum

Documentation content

Working on it

change( [ eventData ], handler(eventObject) )

Replies(2)

Re: Documentation content

Re: Documentation content

Statistics

Tags

Actions

Related Posts