Bug Tracker

Opened 11 years ago

Closed 11 years ago

Last modified 10 years ago

#10612 closed bug (fixed)

Documentation for appendTo and friends does not explain what these functions return

Reported by: atrigent Owned by:
Priority: undecided Milestone: None
Component: unfiled Version: 1.6.4
Keywords: Cc:
Blocked by: Blocking:


appendTo and its fellow "inverse" functions (prependTo, insertBefore, insertAfter, and replaceAll) return the elements that were added to the page (including clones), rather than the original set of elements that they were called on. In keeping consistent with the chaining abilities of jQuery, I (and I believe most other jQuery users) would expect the original set of elements to be returned, and this unexpected behavior is not documented anywhere that I can find, so I think it's clear that either the behavior or the documentation needs to change.

Change History (2)

comment:1 Changed 11 years ago by dmethvin

Resolution: fixed
Status: newclosed

I've updated the docs, thanks!

comment:2 Changed 10 years ago by Turing

Another drawback is that $('<div>').appendTo(undefined) returns an empty set!

In my opinion it should return the former element $('<div>') to allow chaining, even if the element/selector to insert to is undefined.

Yes, you can explain that in the documentation but I think you should change that. Since using appendTo as we use append is dangerous, I (and maybe others) use it only when we want to clone elements.

And most misinformed people using appendTo like using append (moreover in a chained style call) are doing unsafe things.

So why not doing:

  • appendTo($sthg) would work as it feels natural (returning the former matched set) and not duplicating content (so only insert it in the first match)
  • cloneTo($sthg, clone_events, deeply) would work quite as the actual appendTo, with two more arguments to be consistent with clone

But it would break code compatibility...

Since I feel that you wont change behavior, you really should update the documentation:

  • api.jquery.com says that "The .append() and .appendTo() methods perform the same task."
  • docs.jquery.com says that "This operation is, essentially, the reverse of doing a regular $(A).append(B)"

And this is really far from the truth.

Thanks (and sorry for my english)

Note: See TracTickets for help on using tickets.