[html5] r3889 - [e] (0) Drag and drop model documentation.

whatwg at whatwg.org whatwg at whatwg.org
Thu Sep 17 23:59:20 PDT 2009


Author: ianh
Date: 2009-09-17 23:59:19 -0700 (Thu, 17 Sep 2009)
New Revision: 3889

Modified:
   index
   source
Log:
[e] (0) Drag and drop model documentation.

Modified: index
===================================================================
--- index	2009-09-18 05:12:43 UTC (rev 3888)
+++ index	2009-09-18 06:59:19 UTC (rev 3889)
@@ -58039,9 +58039,111 @@
 
   <p><i>This section is non-normative.</i></p>
 
-  <p class=XXX>It's also currently non-existent.</p>
+  <p>To make an element draggable is simple: give the element a <code title=attr-draggable><a href=#the-draggable-attribute>draggable</a></code> attribute, and set an event
+  listener for <code title=event-dragstart><a href=#event-dragstart>dragstart</a></code> that
+  stores the data being dragged.</p>
 
+  <p>The event handler typically needs to check that it's not a text
+  selection that is being dragged, and then needs to store data into
+  the <code><a href=#datatransfer>DataTransfer</a></code> object and set the allowed effects
+  (copy, move, link, or some combination).</p>
 
+  <p>For example:</p>
+
+  <pre><p>What fruits do you like?</p>
+<ol ondragstart="dragStartHandler(event)">
+ <li draggable data-value="fruit-apple">Apples</li>
+ <li draggable data-value="fruit-orange">Oranges</li>
+ <li draggable data-value="fruit-pear">Pears</li>
+</ol>
+<script>
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragStartHandler(event) {
+    if (event.target instanceof HTMLLIElement) {
+      // use the element's data-value="" attribute as the value to be moving:
+      event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
+      event.effectAllowed = 'move'; // only allow moves
+    } else {
+      event.preventDefault(); // don't allow selection to be dragged
+    }
+  }
+</script></pre>
+
+  <hr><p>To accept a drop, the drop target has to listen to at least three
+  events. First, the <code title=event-dragenter><a href=#event-dragenter>dragenter</a></code>
+  event, which is used to determine whether or not the drop target is
+  to accept the drop. If the drop is to be accepted, then this event
+  has to be canceled. Second, the <code title=event-dragover><a href=#event-dragover>dragover</a></code> event, which is used to
+  determine what feedback is to be shown to the user. If the event is
+  not canceled, then the feedback (typically the cursor) is updated
+  based on the <code title=dom-DataTransfer-DropEffect><a href=#dom-datatransfer-dropeffect>dropEffect</a></code> attribute's
+  value, as set by the event handler. Finally, the <code title=event-drop><a href=#event-drop>drop</a></code> event, which allows the actual drop
+  to be performed. This event also needs to be canceled so that the
+  <code title=dom-DataTransfer-DropEffect><a href=#dom-datatransfer-dropeffect>dropEffect</a></code>
+  attribute's value can be used by the source (otherwise it's
+  reset).</p>
+
+  <p>For example:</p>
+
+  <pre><p>Drop your favourite fruits below:</p>
+<ol class="dropzone"
+    ondragenter="dragEnterHandler(event)"
+    ondragover="dragOverHandler(event)"
+    ondrop="dropHandler(event)">
+</ol>
+<script>
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragEnterHandler(event) {
+    // cancel the event if the drag contains data of our type
+    if (event.dataTransfer.types.contains(internalDNDType)
+      event.preventDefault();
+  }
+  function dragOverHandler(event) {
+    event.dataTransfer.dropEffect = 'move';
+    event.preventDefault();
+  }
+  function dropHandler(event) {
+    // drop the data
+    var li = document.createElement('li');
+    var data = event.dataTransfer.getData(internalDNDType);
+    if (data == 'fruit-apple') {
+      li.textContent = 'Apples';
+    } else if (data == 'fruit-orange') {
+      li.textContent = 'Oranges';
+    } else if (data == 'fruit-pear') {
+      li.textContent = 'Pears';
+    } else {
+      li.textContent = 'Unknown Fruit';
+    }
+    event.target.appendChild(li);
+  }
+</script></pre>
+
+  <hr><p>To remove the original element (the one that was dragged) from
+  the display, the <code title=event-dragend><a href=#event-dragend>dragend</a></code> event
+  can be used.</p>
+
+  <p>For our example here, that means updating the original markup to
+  handle that event:</p>
+
+
+  <pre><p>What fruits do you like?</p>
+<ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)">
+ <em>...as before...</em>
+</ol>
+<script>
+  function dragStartHandler(event) {
+    // <em>...as before...</em>
+  }
+  function dragEndHandler(event) {
+    // remove the dragged element
+    event.target.parentNode.removeChild(event.target);
+  }
+</script></pre>
+
+
+
+
   <h4 id=the-dragevent-and-datatransfer-interfaces><span class=secno>7.9.2 </span>The <code><a href=#dragevent>DragEvent</a></code> and <code><a href=#datatransfer>DataTransfer</a></code> interfaces</h4>
 
   <p>The drag-and-drop processing model involves several events. They

Modified: source
===================================================================
--- source	2009-09-18 05:12:43 UTC (rev 3888)
+++ source	2009-09-18 06:59:19 UTC (rev 3889)
@@ -67617,9 +67617,119 @@
 
   <p><i>This section is non-normative.</i></p>
 
-  <p class="XXX">It's also currently non-existent.</p>
+  <p>To make an element draggable is simple: give the element a <code
+  title="attr-draggable">draggable</code> attribute, and set an event
+  listener for <code title="event-dragstart">dragstart</code> that
+  stores the data being dragged.</p>
 
+  <p>The event handler typically needs to check that it's not a text
+  selection that is being dragged, and then needs to store data into
+  the <code>DataTransfer</code> object and set the allowed effects
+  (copy, move, link, or some combination).</p>
 
+  <p>For example:</p>
+
+  <pre><p>What fruits do you like?</p>
+<ol ondragstart="dragStartHandler(event)">
+ <li draggable data-value="fruit-apple">Apples</li>
+ <li draggable data-value="fruit-orange">Oranges</li>
+ <li draggable data-value="fruit-pear">Pears</li>
+</ol>
+<script>
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragStartHandler(event) {
+    if (event.target instanceof HTMLLIElement) {
+      // use the element's data-value="" attribute as the value to be moving:
+      event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
+      event.effectAllowed = 'move'; // only allow moves
+    } else {
+      event.preventDefault(); // don't allow selection to be dragged
+    }
+  }
+</script></pre>
+
+  <hr>
+
+  <p>To accept a drop, the drop target has to listen to at least three
+  events. First, the <code title="event-dragenter">dragenter</code>
+  event, which is used to determine whether or not the drop target is
+  to accept the drop. If the drop is to be accepted, then this event
+  has to be canceled. Second, the <code
+  title="event-dragover">dragover</code> event, which is used to
+  determine what feedback is to be shown to the user. If the event is
+  not canceled, then the feedback (typically the cursor) is updated
+  based on the <code
+  title="dom-DataTransfer-DropEffect">dropEffect</code> attribute's
+  value, as set by the event handler. Finally, the <code
+  title="event-drop">drop</code> event, which allows the actual drop
+  to be performed. This event also needs to be canceled so that the
+  <code title="dom-DataTransfer-DropEffect">dropEffect</code>
+  attribute's value can be used by the source (otherwise it's
+  reset).</p>
+
+  <p>For example:</p>
+
+  <pre><p>Drop your favourite fruits below:</p>
+<ol class="dropzone"
+    ondragenter="dragEnterHandler(event)"
+    ondragover="dragOverHandler(event)"
+    ondrop="dropHandler(event)">
+</ol>
+<script>
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragEnterHandler(event) {
+    // cancel the event if the drag contains data of our type
+    if (event.dataTransfer.types.contains(internalDNDType)
+      event.preventDefault();
+  }
+  function dragOverHandler(event) {
+    event.dataTransfer.dropEffect = 'move';
+    event.preventDefault();
+  }
+  function dropHandler(event) {
+    // drop the data
+    var li = document.createElement('li');
+    var data = event.dataTransfer.getData(internalDNDType);
+    if (data == 'fruit-apple') {
+      li.textContent = 'Apples';
+    } else if (data == 'fruit-orange') {
+      li.textContent = 'Oranges';
+    } else if (data == 'fruit-pear') {
+      li.textContent = 'Pears';
+    } else {
+      li.textContent = 'Unknown Fruit';
+    }
+    event.target.appendChild(li);
+  }
+</script></pre>
+
+  <hr>
+
+  <p>To remove the original element (the one that was dragged) from
+  the display, the <code title="event-dragend">dragend</code> event
+  can be used.</p>
+
+  <p>For our example here, that means updating the original markup to
+  handle that event:</p>
+
+
+  <pre><p>What fruits do you like?</p>
+<ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)">
+ <em>...as before...</em>
+</ol>
+<script>
+  function dragStartHandler(event) {
+    // <em>...as before...</em>
+  }
+  function dragEndHandler(event) {
+    // remove the dragged element
+    event.target.parentNode.removeChild(event.target);
+  }
+</script></pre>
+
+
+
+
   <h4>The <code>DragEvent</code> and <code>DataTransfer</code> interfaces</h4>
 
   <p>The drag-and-drop processing model involves several events. They




More information about the Commit-Watchers mailing list