#8377 closed bug (notabug)

Opened June 01, 2012 06:55PM UTC

Closed October 25, 2012 02:42AM UTC

Last modified October 25, 2012 03:03PM UTC

Draggable documention should say that appendTo is for use with helper

Reported by: andrewbadr Owned by: andrewbadr
Priority: minor Milestone: 2.0.0
Component: ui.draggable Version: 1.8.20
Keywords: Cc:
Blocked by: Blocking:
Description

The documention for the appendTo option on draggable doesn't say that it only works if the helper element isn't already in the DOM. The relevant line is:

if(!helper.parents('body').length)
    helper.appendTo((o.appendTo == 'parent' ? this.element[0].parentNode : o.appendTo));

This seems to be meant only for use with the 'clone' option, but there's nothing saying that. It could be confusing.

Attachments (0)
Change History (9)

Changed June 01, 2012 07:50PM UTC by scottgonzalez comment:1

summary: Draggable documention should say that appendTo is for use with 'clone' → Draggable documention should say that appendTo is for use with helper

Changed June 01, 2012 07:52PM UTC by scottgonzalez comment:2

owner: → andrewbadr
status: new → pending

Actually, the document is pretty clear that it's for the helper. "The element passed to or selected by the appendTo option will be used as the draggable helper's container during dragging. By default, the helper is appended to the same container as the draggable." How would you word this differently so as to be explicit but not redundant?

Changed June 02, 2012 01:32AM UTC by andrewbadr comment:3

_comment0: What does "helper" mean? \ 1. The element that is being dragged, regardless of whether it is the original draggable or a cloned element \ OR \ 2. Only the "clone" case \ \ Your changes and comment on this ticket, if I understand them correctly, imply that definition 2 is correct. If so, that's the source of my misunderstanding. But the docs are far from clear, in ways that I can elaborate on. → 1338600778659718
status: pending → new

What does "helper" mean?

1. The element that is being dragged, regardless of whether it is the original draggable or a cloned element, OR

2. Only the "clone" case

Your changes and comment on this ticket, if I understand them correctly, imply that definition 2 is correct. If so, that's the source of my misunderstanding. But the docs are far from clear, in ways that I can elaborate on.

Changed June 02, 2012 03:20PM UTC by scottgonzalez comment:4

status: new → pending

#2, but your definition is wrong. Cloning is one of an infinite number of possibilities for a helper. The documentation and default value for helper are confusing, because helper: "original" is really "no helper". This is being addressed in the API redesign in which the default will be helper: null.

Please provide your suggestions for updates to make the documentation more clear.

Changed June 03, 2012 12:55AM UTC by andrewbadr comment:5

status: pending → new

The terms should be defined somewhere, probably on the overview page.

Besides the 'helper' option documentation that you already mentioned, the main problem is the naming on the callback argument, ui.helper. If no helper is specified, ui.helper refers to the original draggable, strongly suggesting that definition (1) above is correct.

Changed October 11, 2012 02:49PM UTC by scottgonzalez comment:6

milestone: 1.9.0 → 2.0.0

Changed October 25, 2012 02:42AM UTC by mikesherov comment:7

keywords: → needsdocs
resolution: → notabug
status: new → closed

Thanks andrewbadr! I''m closing this temporarily to eventually move it to the API docs issue tracker.

Changed October 25, 2012 02:24PM UTC by scottgonzalez comment:8

keywords: needsdocs

Definition (1) above is not correct. The name of the ui property is what's confusing. If you have a suggestion for better wording that doesn't make the assumption that (1) applies to appendTo, please reply to this ticket or send a pull request to modify https://github.com/jquery/api.jqueryui.com/blob/master/entries/draggable.xml

Thanks.

Changed October 25, 2012 03:03PM UTC by mikesherov comment:9

Thanks scott. I was only adding needsdocs as a temporary thing until I can in one shot port them over. Glad you took care of it.