Merge pull request #25 from marceljuenemann/development

Development of 1.2.0

Author: marceljuenemann

CHANGELOG.md

@@ -1,3 +1,27 @@
+# 1.2.0 (2014-11-30)
+
+## Bug Fixes
+
+- **Fix glitches in Chrome**: When aborting a drag operation or dragging an element on itself, Chrome on Linux sometimes sends `move` as dropEffect instead of `none`. This lead to elements sometimes disappearing. Can be reproduced by dragging an element over itself and aborting with Esc key. (issue #14)
+- **Fix dnd-allowed-types in nested lists**: When a drop was not allowed due to the wrong element type, the event was correctly propagated to the parent list. Nevertheless, the drop was still executed, because the drop handler didn't check the type again. (issue #16)
+
+## Features
+
+- **New callbacks**: The `dnd-draggable` directive now has a new `dnd-dragstart` callback besides the existing `dnd-moved` and `dnd-copied`. The `dnd-list` directive got the callbacks `dnd-dragover` and `dnd-drag` added, which are also able to abort a drop. (issue #11)
+- **dnd-horizontal-list**: Lists can be marked as horizontal with this new attribute. The positioning algorithm then positions the placeholder left or right of other list items, instead of above or below. (issue #19)
+- **dnd-external-sources**: This attribute allows drag and drop accross browser windows. See documentation for details. (issue #9)
+- **pointer-events: none no longer required**: The dragover handler now traverses the DOM until it finds the list item node, therefore it's child elements no longer require the pointer-events: none style.
+
+## Tested browsers
+
+- Chrome 38 (Ubuntu)
+- Chrome 38 (Win7)
+- Chrome 39 (Mac)
+- Firefox 31 (Win7)
+- Firefox 33 (Ubuntu)
+- Safari 7.1 (Mac)
+- Internet Explorer 11 (IE9 & 10 in compatibility mode)
+
 # 1.1.0 (2014-08-31)
 
 ## Bug Fixes

README.md

@@ -6,6 +6,7 @@ Angular directives that allow you to build sortable lists with the native HTML5
 * [Nested Lists](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/nested) 
 * [Simple Lists](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/simple) 
 * [Typed Lists](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/types) 
+* [Advanced Features](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced) 
 
 ## Why another drag & drop library?
 There are tons of other drag & drop libraries out there, but none of them met my three requirements:
@@ -25,7 +26,7 @@ If this doesn't fit your requirements, check out one of the other awesome drag &
 
 Internet Explorer 8 or lower is *not supported*, but all modern browsers are (see changelog for tested versions).
 
-Note that *touch devices* are *not supported*, because the HTML5 drag & drop standard doesn't cover those.
+Note that **touch devices are not supported**, because the HTML5 drag & drop standard doesn't cover those.
 
 
 ## Usage
@@ -38,50 +39,61 @@ Use the dnd-draggable directive to make your element draggable
 
 **Attributes**
 * `dnd-draggable` Required attribute. The value has to be an object that represents the data of the element. In case of a drag and drop operation the object will be serialized and unserialized on the receiving end.
-* `dnd-selected` Callback that is invoked when the element was clicked but not dragged
+* `dnd-selected` Callback that is invoked when the element was clicked but not dragged. The original click event will be provided in the local `event` variable. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/nested) 
 * `dnd-effect-allowed` Use this attribute to limit the operations that can be performed. Options are:
     * `move` The drag operation will move the element. This is the default
     * `copy` The drag operation will copy the element. There will be a copy cursor.
     * `copyMove` The user can choose between copy and move by pressing the ctrl or shift key.
         * *Not supported in IE:* In Internet Explorer this option will be the same as `copy`. 
         * *Not fully supported in Chrome on Windows:* In the Windows version of Chrome the cursor will always be the move cursor. However, when the user drops an element and has the ctrl key pressed, we will perform a copy anyways.
     * HTML5 also specifies the `link` option, but this library does not actively support it yet, so use it at your own risk.
-* `dnd-moved` Callback that is invoked when the element was moved. Usually you will remove your element from the original list in this callback, since the directive is not doing that for you automatically.
-* `dnd-copied` Same as dnd-moved, just that it is called when the element was copied instead of moved.
-* `dnd-type` Use this attribute if you have different kinds of items in your application and you want to limit which items can be dropped into which lists. Combine with dnd-allowed-types on the dnd-list(s). This attribute should evaluate to a string, although this restriction is not enforced (at the moment).
-* `dnd-disable-if` You can use this attribute to dynamically disable the draggability of the element. This is useful if you have certain list items that you don't want to be draggable, or if you want to disable drag & drop completely without having two different code branches (e.g. only allow for admins). *Note*: If your element is not draggable, the user is probably able to select text or images inside of it. Since a selection is always draggable, this breaks your UI. You most likely want to disable user selection via CSS (see [user-select](http://stackoverflow.com/a/4407335)).
+    * [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-moved` Callback that is invoked when the element was moved. Usually you will remove your element from the original list in this callback, since the directive is not doing that for you automatically. The original dragend event will be provided in the local `event` variable. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-copied` Same as dnd-moved, just that it is called when the element was copied instead of moved. The original dragend event will be provided in the local `event` variable. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-dragstart` Callback that is invoked when the element was dragged. The original dragstart event will be provided in the local `event` variable. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-type` Use this attribute if you have different kinds of items in your application and you want to limit which items can be dropped into which lists. Combine with dnd-allowed-types on the dnd-list(s). This attribute should evaluate to a string, although this restriction is not enforced (at the moment). [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/types) 
+* `dnd-disable-if` You can use this attribute to dynamically disable the draggability of the element. This is useful if you have certain list items that you don't want to be draggable, or if you want to disable drag & drop completely without having two different code branches (e.g. only allow for admins). *Note*: If your element is not draggable, the user is probably able to select text or images inside of it. Since a selection is always draggable, this breaks your UI. You most likely want to disable user selection via CSS (see [user-select](http://stackoverflow.com/a/4407335)). [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/types) 
 
 **CSS classes**
 * `dndDragging` This class will be added to the element while the element is being dragged. It will affect both the element you see while dragging and the source element that stays at it's position. Do not try to hide the source element with this class, because that will abort the drag operation.
 * `dndDraggingSource` This class will be added to the element after the drag operation was started, meaning it only affects the original element that is still at it's source position, and not the "element" that the user is dragging with his mouse pointer
 
 ### dnd-list directive
-Use the dnd-list attribute to make your list element a dropzone. Usually you will add a single li element as child with the ng-repeat directive. If you don't do that, we will not be able to position the dropped element correctly. If you want your list to be sortable, also add the dnd-draggable directive to your li element(s). Both the dnd-list and it's direct children must have position: relative CSS style, otherwise the positioning algorithm will not be able to determine the correct placeholder position in all browsers. If you use nested dnd-lists, make sure that all elements excecpt for the dnd-lists and it's direct children have the pointer-events: none CSS style.
+Use the dnd-list attribute to make your list element a dropzone. Usually you will add a single li element as child with the ng-repeat directive. If you don't do that, we will not be able to position the dropped element correctly. If you want your list to be sortable, also add the dnd-draggable directive to your li element(s). Both the dnd-list and it's direct children must have position: relative CSS style, otherwise the positioning algorithm will not be able to determine the correct placeholder position in all browsers.
 
 **Attributes**
 * `dnd-list` Required attribute. The value has to be the array in which the data of the dropped element should be inserted.
-* `dnd-allowed-types` Optional array of allowed item types. When used, only items that had a matching dnd-type attribute will be dropable.
-* `dnd-disable-if` Optional boolean expresssion. When it evaluates to true, no dropping into the list is possible. Note that this also disables rearranging items inside the list.
+* `dnd-allowed-types` Optional array of allowed item types. When used, only items that had a matching dnd-type attribute will be dropable. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/types) 
+* `dnd-disable-if` Optional boolean expresssion. When it evaluates to true, no dropping into the list is possible. Note that this also disables rearranging items inside the list. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/types) 
+* `dnd-horizontal-list` Optional boolean expresssion. When it evaluates to true, the positioning algorithm will use the left and right halfs of the list items instead of the upper and lower halfs. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-dragover` Optional expression that is invoked when an element is dragged over the list. If the expression is set, but does not return true, the element is not allowed to be dropped. The following variables will be available:
+    * `event` The original dragover event sent by the browser.
+    * `index` The position in the list at which the element would be dropped.
+    * `type` The `dnd-type` set on the dnd-draggable, or undefined if unset.
+    * [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-drop` Optional expression that is invoked when an element is dropped over the list. If the expression is set, it must return the object that will be inserted into the list. If it returns false, the drop will be aborted and the event is propagated. The following variables will be available:
+    * `event` The original drop event sent by the browser.
+    * `index` The position in the list at which the element would be dropped.
+    * `item` The transferred object.
+    * `type` The dnd-type set on the dnd-draggable, or undefined if unset.
+    * [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
+* `dnd-external-sources` Optional boolean expression. When it evaluates to true, the list accepts drops from sources outside of the current browser tab. This allows to drag and drop accross different browser tabs. Note that this will allow to drop arbitrary text into the list, thus it is highly recommended to implement the dnd-drop callback to check the incoming element for sanity. Furthermore, the dnd-type of external sources can not be determined, therefore do not rely on restrictions of dnd-allowed-type. Also note that this feature does not work very well in Internet Explorer. [Demo](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/advanced)
 
 **CSS classes**
 * `dndPlaceholder` When an element is dragged over the list, a new placeholder child element will be added. This element is of type li and has the class dndPlaceholder set.
 * `dndDragover` This class will be added to the list while an element is being dragged over the list.
 
 ### Required CSS styles 
-* `pointer-events: none` With nested lists it's very important that **only the dnd-list and it's children** react to mouse events.
-* `position: relative` Both the dnd-list and it's children require this, so that the directive can determine the mouse position relative to the list and thus calculate the correct drop position.
+Both the dnd-list and it's children require relative positioning, so that the directive can determine the mouse position relative to the list and thus calculate the correct drop position.
 
 <pre>
-ul[dnd-list] * { 
-    pointer-events: none; 
-}
-
 ul[dnd-list], ul[dnd-list] > li { 
-    pointer-events: auto;
     position: relative;
 }
 </pre>
 
+*Since 1.2.0 `pointer-events: none` is no longer required*
+
 ### Example
 
 Take a look at the code in the [Simple Lists](http://marceljuenemann.github.io/angular-drag-and-drop-lists/demo/#/simple) example