index.mustache revision 5b139d58acfcae4b1bcab5a895706abafc2a87a0
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<div class="intro">
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <p> The Drag and Drop Utility allows you to create a draggable interface efficiently, buffering you from browser-level abnormalities and enabling you to focus on the interesting logic surrounding your particular implementation. This component enables you to create a variety of standard draggable objects with just a few lines of code and then, using its extensive API, add your own specific implementation logic. </p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <p>For more information about drag and drop as a design pattern, see the <a href="http://developer.yahoo.com/ypatterns/parent_dragdrop.php">Yahoo! Design Pattern Library</a>.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering{{>getting-started}}
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h2>Using Drag and Drop</h2>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4>Basic Drag</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>You create a simple Drag instance by including the `dd-drag` module and using the following code:</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart PoetteringYUI().use('dd-drag', function(Y) {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4>Basic Proxy Drag</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>You create a simple Proxy Drag instance by including the `dd-drag` and `dd-proxy` modules and using the following code:</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart PoetteringYUI().use('dd-drag', 'dd-proxy', function(Y) {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering }).plug(Y.Plugin.DDProxy); //This config option makes the node a Proxy Drag
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4>Basic Drop Target</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>You create a simple Drop Target instance by including the `dd-drop` module and using the following code:</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart PoetteringYUI().use('dd-drop', function(Y) {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering var drop = new Y.DD.Drop({
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4 id="events">Events</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>Drag and Drop for YUI 3 has been been packed with useful events to allow the implementer to control the end user experience.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p><em>* All Drag and Drop events bubble, by default, to the Drag and Drop Manager.</em></p>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <th>Event</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Target</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Preventable</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Stoppable</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Description</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>`drag:mouseDown`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Handles the mousedown/touchstart DOM event, checks to see if you have a valid handle then starts the drag timers.</td>
40a1eebde6be7ac3f1885147fc24e06ad1da260cDavid Herrmann <td>`drag:afterMouseDown`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires after the mousedown/touchstart event has been cleared.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:mouseup`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires the mouseup event.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:align`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node is aligned.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:removeHandle`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires after a handle is removed.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:addHandle`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires after a handle is added.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:removeInvalid`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires after an invalid selector is removed.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:addInvalid`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires after an invalid selector is added.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:start`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires at the start of a drag operation.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:end`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires at the end of a drag operation.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:drag`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires every mousemove/touchmove during a drag operation.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:over`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node is over a Drop Target. (Fired from dd-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:enter`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node enters a Drop Target. (Fired from dd-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:exit`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node exits a Drop Target. (Fired from dd-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:drophit`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node is dropped on a valid Drop Target. (Fired from dd-ddm-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drag:dropmiss`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when this node is dropped on an invalid Drop Target. (Fired from dd-ddm-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drop:over`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when a drag element is over this target.</td>
747c0ff5648b707abb601f58eefcfd92a7d41695Lennart Poettering <td>`drop:enter`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Fires when a drag element enters this target.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drop:exit`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Fires when a drag element exits this target.</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>`drop:hit`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Fires when a draggable node is dropped on this Drop Target. (Fired from dd-ddm-drop)</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering<h4 id="bubbling">Event Bubbling</h4>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering<p>To allow for a truly Event driven application, all Drag and Drop related events are bubbled to the `DragDropMgr`.</p>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering<p>This allows you to listen for all Drag and Drop events from a central location, per YUI instance.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>This approach is also handy for situations where you are dynamically adding and removing items.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>So instead of doing this:</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringvar doSomething = function() {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering Y.log('Do Something Here');
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd1.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd2.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd3.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd4.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd5.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd6.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd7.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd8.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringdd9.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>You can now do this:</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poetteringvar doSomething = function() {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering Y.log('Do Something Here');
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart PoetteringY.DD.DDM.on('drag:drag', doSomething);
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4 id="delegate">Delegate Dragging</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>Delegate dragging allows you to create a "list/group" of draggable items that are under a common "container". Using this approach, you can have hundreds of draggable items, yet only have one object created under the hood.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>This approach is also handy for situations where you are dynamically adding and removing items from the "list" and need to make them draggable. Using `Delegate` you wouldn't have to create a new `drag` instance when adding or removing it.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart PoetteringYUI().use('dd-delegate', function(Y) {
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering container: '#demo', //The common container
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering nodes: '.item' //The items to make draggable
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4 id="cssclasses">CSS Class Names</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>The Drag and Drop Utility adds CSS class names for important moments in the drag and drop operation. Below you will find the list of these class names.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>The Drag and Drop Utility doesn't ship with a default skin, so no style rules are attached to these class names. That is completely left up to the implementer.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p><strong>Note: </strong> As of version 3.1.0, Drag and Drop changed it's classname prefix from `yui-dd` to `yui3-dd` to mimic the global change in skinning.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Class Name</th>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <th>Target</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>State</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-draggable`</td>
b914e211f3a40f507b3cdc572838ec7f3fd5e4cfLennart Poettering <td>Given to all Drag Nodes</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-locked`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added when a Drag instance is locked</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-dragging`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added while a Drag instance is active</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-proxy`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Proxy</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Given to the Proxy Node</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-drop`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Given to all Drop Targets</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-drop-locked`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added when a Drop instance is locked</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-drop-active-valid`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added to a Drop when it is an valid target for the current drag operation</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-drop-active-invalid`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added to a Drop when it is an invalid target for the current drag operation</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`yui3-dd-drop-over`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Added when a Drag instance is over this Drop Target</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h4 id="gestures">Touch/Gesture Support</h4>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>Native gesture support was added to DD in 3.2.0. This support is transparent and the implementor should not have to do anything to use this functionality. When `dd` is used, loader will check the device to see if it contains support for Gesture Events, if the device supports these events the `dd-gestures` module will automatically be loaded as well as it's dependencies. At this point, DD will operate as usual but it will utilize the native gesture events instead of mouse based events.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<h3 id="modules">Module Descriptions</h3>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering<p>Drag and Drop for YUI 3 has been broken up into several modules to allow you, as the implementer, to pick how you want it to work and what code you need on your page.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Module Name</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Description</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-drag`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Main drag class, this makes something draggable.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-proxy`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Adds proxy support to the main drag class.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-constrain`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Adds constrain support to the main drag class.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-scroll`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Adds node and window based scroll support.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-delegate`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Provides the ability to drag multiple nodes under a container element using only one Y.DD.Drag instance as a delegate.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-drop`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Drop Support, this is the support for all drop targets.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>All of the Drag and Drop modules rolled up into one file.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th colspan="2">Other Included Modules</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-ddm-base`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Base DragDrop Manager, required to make something draggable.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-ddm`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Adds shim support, only needed when you need to drag over something that steals mouse events or you are targeting.</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-ddm-drop`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Adds Drop support, only required when you have drop targets you need to interact with.</td>
9a015429b3bbfe1c2802570c1621e73d6cb57ac3Lennart Poettering<h3 id="plugins">DD Plugins</h3>
9a015429b3bbfe1c2802570c1621e73d6cb57ac3Lennart Poettering<p><strong>In 3.2.0, some modules have been removed from the rollup and were converted to DD Plugins.</strong> Below are the list of plugins that are no longer in the `dd` rollup.</p>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Plugin</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <th>Description</th>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-plugin`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Node plugin for Drag</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-drop-plugin`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Node plugin for Drop</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td nowrap="nowrap">`dd-gestures`</td>
623a4c97b9175f95c4b1c6fc34e36c56f1e4ddbfLennart Poettering <td>Node plugin for Gesture support. This module is automatically loaded by loader when `dd` is used on a device that supports gestures.</td>