Bug Tracker

#10612 closed bug (fixed)

Opened October 29, 2011 01:18AM UTC

Closed October 29, 2011 01:40AM UTC

Last modified October 11, 2012 03:45PM UTC

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:
Description

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.

Attachments (0)
Change History (2)

Changed October 29, 2011 01:40AM UTC by dmethvin comment:1

resolution: → fixed
status: new → closed

I've updated the docs, thanks!

Changed October 11, 2012 03:45PM UTC by Turing comment:2

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)