11.2. Drag and Drop script.aculo.us' drag-and-drop functionality (defined in dragdrop.js) is provided by one class (Draggable) and three objects: Draggables (which manages instances of Draggable), Droppables, and Sortables. 11.2.1. class Draggable
initialize( element[, options] ) -
Creates a Draggable instance for element and registers it by calling Draggables.register. Options may include: handle
| May be false (the default, making the element its own handle), an element object, or a string that sets handle to the first child of element with the given class name. | starteffect
| An effect called on element when dragging starts. By default, it changes element's opacity to 0.2 in 0.2 seconds. | reverteffect
| An effect called on element when the drag is reverted. Defaults to a smooth slide to element's original position. | endeffect
| An effect called on element when dragging ends. By default, it changes element's opacity to 1.0 in 0.2 seconds. | constraint
| A string used to limit the draggable directions, either horizontal or vertical. Defaults to null. | zindex
| Sets the CSS zindex property. Defaults to 1000. | revert
| Boolean indicating whether the draggable should slide back to its starting point after being dropped. Can also be an arbitrary function reference, called when the drag ends. Defaults to false. | scroll
| Boolean determining whether the draggable should cause the page to scroll when dragged near the edge. Defaults to false. | scrollSensitivity
| Determines the size in pixels of the area in which the pointer will trigger scrolling. Defaults to 20. | scrollSpeed
| A multiplier affecting the scrolling speed when a draggable gets near the window edge. Defaults to 15. | snap
| Used to cause a draggable to snap to a grid or to constrain its movement. If false (default), no snapping or constraining occurs. If an integer x, the draggable will snap to a grid of x pixels. If an array [x, y], the horizontal dragging will snap to a grid of x pixels and the vertical will snap to y pixels. Can also be a function conforming to Function( x , y , draggable ) that returns an array [x, y]. | ghosting
| Boolean determining whether the draggable should be cloned for dragging, leaving the original in place until the clone is dropped. Defaults to false. |
11.2.1.1. Examples new Draggable('target'); // Slide back to the original position after dragging new Draggable('target', {revert:true}); // Snap target to a 50-pixel grid while dragging new Draggable('target', {snap:50}); // Only allow dragging from an element named 'handle' new Draggable('target', {handle:$('handle')}); // Eliminate the opacity change during dragging, and instead // highlight target when drag finishes new Draggable('target', { starteffect:null, endeffect:function(element){ new Effect.Highlight(element); } }); // Constrain dragging to a 100x50px box new Draggable('target', { snap: function(x, y) { return[ (x < 100) ? (x > 0 ? x : 0 ) : 100, (y < 50) ? (y > 0 ? y : 0) : 50 ]; } }); // Constrain dragging to element's parent node new Draggable('target', { snap: function(x, y, draggable) { function constrain(n, lower, upper) { if (n > upper) return upper; else if (n < lower) return lower; else return n; } var element = draggable.element.getDimensions( ); var parent = draggable.element.parentNode.getDimensions( ); return [ constrain(x, 0, parent.width - element.width), constrain(y, 0, parent.height - element.height) ]; } });
11.2.1.2. Instance methods and properties
delta -
The element's offset (like [left, top]) when last at rest; not updated while dragging. new Draggable('target'); Draggables.addObserver({ onDrag:function(eventName, draggable, event){ draggable.element.update(draggable.delta.inspect( )); } });
dragging -
Boolean representing whether the element is currently being dragged.
handle -
References the element to be used as a handle.
initDrag( event ) -
Bound to handle's mousedown event. If event is a left mouse click and its source is not a form element, calls Draggables.activate, passing the draggable.
updateDrag( event, pointer ) -
Called by Draggables.updateDrag( ). Handles scrolling as necessary, fires an onDrag event to observers, and calls draw( ).
startDrag( event ) -
Called by updateDrag( ) if dragging is false. Fires the onStart event to observers and calls starteffect if defined.
draw( point ) -
Calculates the appropriate position for the draggable based on point and moves the element as needed.
endDrag( event ) -
Called by Draggables.endDrag( ). Stops scrolling and calls finishDrag( ).
finishDrag( event, success ) -
Called by endDrag( ). Sets dragging to false, fires an onEnd event to observers, reverts if necessary, calls endeffect if available, and calls Draggables.deactivate( ).
keyPress( event ) -
Called by Draggables.keyPress( ). Captures keyPress events and finishes the drag if the escape key is pressed.
currentDelta( ) -
Returns an array with the draggables's element's offset coordinates like [left, top]. new Draggable('target'); Draggables.addObserver({ onDrag:function(eventName, draggable, event){ draggable.element.update(draggable.currentDelta().inspect( )); } });
destroy( ) -
Unregisters the draggable and cancels its observer. draggable = new Draggable('target'); draggable.destroy( );
11.2.2. Draggables Tracks all Draggable instances in the document.
Draggables.activeDraggable -
References the Draggable instance currently being dragged.
Draggables.drags -
An array of Draggable instances.
Draggables.observers -
An array of observers that are called by notify( ).
Draggables.register( draggable ) -
Adds draggable to drags. Called by Draggable.initialize( ). The first time this is called, binds document.mouseup to Draggables.endDrag, document.mousemove to Draggables.updateDrag, and document.keypress to Draggables.keyPress.
Draggables.unregister( draggable ) -
Removes draggable from drags. Called by Draggable.destroy( ). If no draggables remain in the document, the event observers are removed as well.
Draggables.activate( draggable ) -
Stores draggable in activeDraggable. Called by Draggable.initDrag( ).
Draggables.deactivate( ) -
Sets activeDraggable to null. Called by Draggable.finishDrag( ).
Draggables.updateDrag( event ) -
Bound to document.mousemove. Calls updateDrag( ) on activeDraggable.
Draggables.endDrag( event ) -
Bound to document.mouseup. Calls endDrag( ) on activeDraggable.
Draggables.keyPress( event ) -
Bound to document.keypress. Calls keyPress( ) on activeDraggable.
Draggables.addObserver( observer ) -
Used to attach observer to all draggables in the document. observer is expected to be an object with at least one property named onStart, onEnd, or onDrag. The values of the properties should be functions conforming to Function( eventName , draggable , event ). Draggables.addObserver({ onStart:function(eventName, draggable, event){ $('console').update('starting'); }, onDrag:function(eventName, draggable, event){ $('console').update('dragging'); }, onEnd:function(eventName, draggable, event){ $('console').update('ending'); } });
Observer functions are called by Draggables.notify( ), which is in turn called by Draggable.startDrag( ), Draggable.updateDrag( ), and Draggable.finishDrag( ).
Draggables.removeObserver( element ) -
Removes all observers attached to element. Draggables.removeObserver(myElement);
Draggables.notify( eventName, draggable, event ) -
Calls all observers that define callbacks for eventName, which should be one of onStart, onEnd, or onDrag. 11.2.3. Droppable Elements Keeps track of elements in the document that support "drops" from draggable elements.
Droppables.drops -
An array containing the options object for each droppable in the document.
Droppables.last_active -
The currently active droppable.
Droppables.add( element[, options] ) -
Adds an object representing a droppable to drops. Droppables.add('target');
options is an object used to customize the behavior of the droppable. Valid properties are:
accept -
A string or an array of strings describing CSS classes. The droppable will only accept draggables that have one or more of these CSS classes. Droppables.add('target', {accept:'green' });
OnDrop -
A callback function called when the draggable accepts a drop. The function should conform to Function( draggableElement , droppableElement , event ). Droppables.add('target', {onDrop:function( ){ $('console').update('dropped!'); }});
onHover -
A callback function that fires when a draggable is moved over the droppable and the droppable is affected (would accept it). The callback should conform to Function( draggableElement , droppableElement , percentageOverlapping ).
Hoverclass -
The name of a CSS class that will be added to element while the droppable is active (has an acceptable draggable hovering over it). Defaults to null. Droppables.add('target', {hoverclass:'hover'});
Greedy -
If true (default), stops processing hoveringother droppables under the draggable won't be searched.
Containment -
Specifies element(s) within which draggables must be contained in order to be accepted by the droppable.
Droppables.fire( event, element ) -
If the last active droppable is affected by element and the point associated with event, calls onDrop. Called by Draggable.finishDrag( ).
Droppables.remove( element ) -
Removes any droppable that is attached to element from drops. Droppables.remove('target');
Droppables.activate( drop ) -
Adds a hover class to drop's element, if specified. Droppables.activate(Droppables.drops[0]);
Droppables.deactivate( drop ) -
Removes the hover class from drop, if specified. Droppables.deactivate(Droppables.drops[0]);
Droppables.isAffected( point, element, drop ) -
Returns true if point is within drop and drop accepts element. Droppables.isAffected([100,200], $('target'), Droppables.drops[0])
Droppables.show( point, element ) -
Activates the deepest droppable that is affected by element and point, if any. Called by Draggable.updateDrag( ). Droppables.show([100,200], $('target'));
Droppables.reset( ) -
Deactivates the last active droppable. Called by Draggable.finishDrag( ). Droppables.reset( );
11.2.4. Sortable Elements Due to browser limitations, Sortables don't work reliably across platforms for table elements (TABLE, THEAD, TBODY, or TR). Sortables nested inside tables ought to have the CSS style position: relative to work well across platforms.
Sortable.sortables -
This object stores references for all of the document's sortables, keyed by element ID.
Sortable.create( element[, options] ) -
Adds sortable behavior to the container element, which can be of any type. For example: // <ul > // <li>Lions</li> // <li>Tigers</li> // <li>Bears</li> //</ul> Sortable.create('list');
Implicitly calls Sortable.destroy( ) if element was already a sortable. The options parameter is an object with properties used to customize the behavior of the sortable. Options are detailed here: Tag
| Specifies the tag name for the child elements of the container. Defaults to li which is appropriate for UL and OL containers. | only
| A string or array of strings further restricting the selection of child elements to those with the given CSS class(es). Defaults to null. | overlap
| Determines how overlap is calculated for ordering elements. Either vertical (default, appropriate for vertical lists) or horizontal (for floating sortables or horizontal lists). | constraint
| See Draggable.options. Defaults to vertical. | containment
| An element or array of elements used to enable sorting elements among multiple containers. See Draggable.options. Defaults to element. | handle
| See Draggable.options. Defaults to null. | hoverclass
| See Draggable.options. Defaults to null. | ghosting
| See Draggable.options. Defaults to false. | dropOnEmpty
| When false (default), empty lists can't have elements dropped into them. If set to true, the sortable container will be made into a droppable, so it can receive a draggable (as according to the containment rules) as a child element when there are no elements inside. | scroll
| Allows for sortable containers to be in fixed-height, scrolling boxes. To use, wrap the sortable container in an element with style overflow:scroll, and assign the wrapper's ID to this option. Before creating the sortable, enable sortable scrolling with this line: Position.includeScrollOffsets = true;. | scrollSensitivity
| See Draggable.options. | scrollSpeed
| See Draggable.options. | tree
| If true, gives sortable functionality to elements listed in treeTag. Defaults to false. | treeTag
| The element type tree nodes are contained in. Defaults to ul. | onChange
| A callback called whenever the sort order changes while dragging. When dragging from one sortable to another, the callback is called once on each sortable. Gets the affected element as its parameter. | onUpdate
| A callback called when the drag ends and the sortable's order is changed in any way. When dragging from one sortable to another, the callback is called once on each sortable. Gets the container as its parameter. Note that the ID attributes of the elements contained in the sortable must be named as described in Sortable.serialize( ). |
Sortable.serialize( element[, options] ) -
Returns a string (in key []= value pairs, suitable for including in an HTTP request) representing the order of the child elements of the sortable associated with element. Generally used to notify the server when a list is reordered. To work, the child elements must have id attributes according to the convention name _ id. Only the id part will be serialized. For example: // <ul > // <li >Lions</li> // <li >Tigers</li> // <li >Bears</li> // </ul> Sortable.create('list'); Sortable.serialize('list'); // => list[]=1&list[]=2&list[]=3
options can have two keys: tag
| Specifies the kind of tag used for child elements. Defaults to the same value as provided to the tag option of Sortable.create( ). | name
| Specifies the name of the key used in the key/value serialization. Defaults to the id attribute of the sortable container. |
Sortable.sequence( element[, options] ) -
Returns an object representing the order of the children of element. // <ul > // <li >Lions</li> // <li >Tigers</li> // <li >Bears</li> // </ul> Sortable.create('list'); Sortable.sequence('list'); // => '1,2,3'
Sortable.setSequence( element, new_sequence[, options] ) -
Reorders the children of the Sortable associated with element according to the array new_sequence. // Reverse the order of 'list' Sortable.setSequence('list', Sortable.sequence('list').reverse( ));
Sortable.tree( element[, options] ) -
Like sequence but returns an object representing the order and structure of the children of element.
Sortable.options( element ) -
Returns the options object for the sortable associated with element . Sortable.create('list'}); Sortable.options($('list')).tag; // => 'li'
Sortable.destroy( element ) -
Removes all sortable behavior from element. Sortable.destroy('list');
|
