On touch devices, if a draggable element is in a scrollable list, either press and hold the item to drag it or pull it in a direction that cannot be scrolled.
Items can be dragged into this text field.
This is a garbage-bin container. Drag items here to delete them.
Drag items inside this container and to other containers as well. Box 1Box 2Box 3Box 4Box 5Some text with a link. A text field too:
This container is read-only. Items can only be dragged out of this container.
Usage
Initialization
To begin using the library, include the script in your page.
<script src="draggar.min.js"></script>
Containers
Make a container element in your page by setting the data-drag attribute to include container.
<div data-drag="container"> . . . <div>
To specify a read-only container, set the data-drag attribute to include readonly. The order doesn't matter.
<div data-drag="readonly container"> . . . <div>
To specify a garbage container (any items dragged over it will be deleted), include garbage in the data-drag attribute. Again, the order doesn't matter.
<div data-drag="garbage container"> . . . <div>Text field elements may also receive drop data. The text value will come from the first of the element's:
element.value if it is present and has a value.element.getAttribute('data-value') if it is present.element.textContent
By default the text will be replaced. Optionally, add-input can be included in the data-drag attribute. This will append the value to the text field, or if there is a selection then the selection will be replaced with the item value.
<input type="text" data-drag="add-input container"/>
A container may accept dropped items, but give them to a child container. This allows larger drop areas while keeping the dropped items in a much smaller area. This is particularly useful for text fields that are styled to show buttons and other actions. Just add relay to the data-drag attribute.
<div data-drag="relay container">
Anything dragged into this container will automatically go into the first child container.
<div data-drag="container">
This is where dropped elements will be placed.
<div>
<div>
Draggable Items
Elements inside the container must specify that they are draggable by setting the data-drag attribute to draggable. If the element is expected to be dragged into a text field, the data-value attribute may be set (see above for how the text value will be determined).
<div data-drag="container">
<span data-drag="draggable"> . . . <span>
<span>This is not draggable.<span>
<span data-drag="draggable" data-value="Custom Value"> . . . <span>
<div>
<span data-drag="draggable">This will not be draggable because it is not inside a container.<span>
Styling
Styling is not required, as the needed styles will be added and removed in runtime, however styling is recommended. The following classes are used:
.drag-transit Set when the element floats above the page looking for a container..drag-ghost Set when the element has a container, and is positioned over the drop point..drag-spacer Set to an element that takes up space inside the container..drag-garbage Added to the ghost element when the container is a garbage container.
When crafting styles for draggable items, keep in mind that the ghost element will be a child of the <body> element.
It is recommended to add transitions to the ghost element's left and top properties. When the dragging element can be relocated, a transition will show a smooth movement to its new spot. Also, if the drag operation fails, the transition will show its movement back to its original place. The transitions should not take longer than ½ second.
.drag-ghost{opacity:0.75;transition:left ease 0.2s,top ease 0.2s;} .drag-spacer{opacity:0.2;}
Containers and draggable items can also be easily styled with the proper selectors:
[data-drag~='container']{border:2px dashed green;} [data-drag~='draggable']{box-shadow:0 0 3px blue;}
Events
A successful drag-and-drop will emit an dropped event to both the source and destination containers. The following properties will be added to the Event object:
_event['drag-source'] The source container._event['drag-destination'] The receiving container. If it is a garbage container, then this will be null._event['drag-dropped'] The element that was dropped.
Garbage containers don't receive a dropped event, the element is just deleted; the source container will still receive an event.
If the destination container is a text field, the text field will receive an input event as well as a dropped event.
Cloning Customization
When dragging begins, the element is cloned to use as a spacer, and if the source container is read-only, it will be cloned again to create the drop element. By default this is done with Element.cloneNode(true)—this does not clone event listeners. A custom cloning method may be set:
Draggar.clone=function(element,type){ . . . }; Draggar.clone=function(element,type){return $(element).clone(type=='ghost')[0];};//jQuery
Two arguments will be passed to the cloning function:
The element that is being dragged.The type of element to create, either spacer or ghost.
Spacer elements will always be removed after a drag operation is completed. Ghost elements may be removed if the drag operation was not successful.
Container Restriction Customization
If you want to add additional restrictions to which containers can receive which elements, a custom method may be set:
Draggar.allowed=function(container,element){ . . . };
Two arguments will be passed to the checking function:
The container element that wants to receive the element.The element being dragged.
If the function returns true the element is allowed to drop in the container.
Nuances
The dragging element is placed around other elements in the container. If there are whitespace text nodes, they can stack up after several operations and cause visually unpleasant spacing artifacts. When the library is loaded, it automatically removes unwanted whitespace nodes inside all container elements. If containers are added later, the whitespace removal will not happen.
