Documentation: manipulating size during drag

[camtarn]

At the foot of ​http://jqueryui.com/demos/draggable/ , the documentation says:

To manipulate the position of a draggable during drag, you can either use a wrapper as the draggable helper and position the wrapped element with absolute positioning, or you can correct internal values like so:

$(this).data('draggable').offset.click.top -= x

The second part of this does work, but there's a better way - the ui parameter passed into the drag event has a ui.position which is writeable. It contains the position the draggable was going to move to, and writing to it allows you to override the motion while keeping everything internally consistent.

My proposed text:

To manipulate the position of a draggable during drag, you can either use a wrapper as the draggable helper and position the wrapped element with absolute positioning, or you can write to ui.position within the drag() callback like so:

drag: function(event, ui) {
  ui.position.top += x;
} 

The drag() callback is called after Draggable has calculated the coordinates it expects the helper to move to (stored in ui.position), but before the position is applied. Writing to ui.position only affects the current frame, since the position is calculated based on cached values.

I've also got a caveat about draggables changing dimensions while dragging, which could do with being documented. In the options tab, under 'containment', before Code Examples:

Note that Draggable currently only calculates containment coordinates at the start of a drag. Containment is calculated using both the container's and helper's dimensions, so if these change during drag, you may notice containment behaves oddly. Changing the value of the containment option during a drag will do nothing until the next drag.

This caveat is due to #4781, and will no longer be necessary once that patch is incorporated.

[mikesherov]

Thanks for contributing! Those docs are no longer supported. If you have suggestions for documentation improvements against the new docs, please file them here: ​https://github.com/jquery/api.jqueryui.com/issues?state=open