Terminology

This text is obsolete in parts. Please refer to the official DnD documentation.

Source: A source is an HTML node that can be dragged around. It can be a simple node, or a node which contains other nodes - a DIV, a TABLE, etc. In Dojo, a source has type dojo.dnd.Source.

Target: Target is like a placeholder, onto which nodes can be dropped. A good example is a shopping cart application, where an item icon is a source while the shopping cart is a target.

Interestingly, all dojo.dnd.Source objects in Dojo DnD are also targets, so many applications just use dojo.dnd.Source for both. For a pure target, i.e. one that's not draggable, you define the target with type dojo.dnd.Target.

Avatar: Avatar is kind of ghost image of the object being dragged. This ghost image follows the mouse cursor, till the time it is dropped to a proper placeholder. In Dojo this functionality is available to every drag and drop operation by default. The 'Dojo.dnd.Avatar' class does all this for you and displays a nice tooltop with text 'moving' or 'copying', indicating the type of operation being performed.

DnD Manager: The DnD Manager is a singleton, which is responsible for handling all DnD operations on a page. It accomplishes many complex tasks required for successful DnD operations like detecting initialization of valid drag operation by user, creation of Avatar, allowing drop to only eligible targets and such things. Most of the time the default manager works fine, but you can extend or create your own DnD Manager class for more complex scenarios.

Mover: Mover is a mixin class which makes an object (HTML node) movable. Once a node is made movable using this class, user can freely drag and drop the node anywhere on the page, for example a popup window. There is no concept of source and target in this case.

Selector : Selector is the base class for Source in Dojo. This means that every Source is a Selector. A Selector controls how its child nodes can be selected. This also means that every node that participates in DnD operation is part of some selectable list.

Container: Container is the baseclass for Selector. It provides functionality of sensing mouse movement over its children.

To sum up: a container contains nodes, a selector makes it possible to select single or multiple nodes, a mover makes the selected nodes movable, an Avatar provides visual cue during DnD and the DnD Manager makes the overall operation possible.

A Simple Example

This text is obsolete in parts. Please refer to the official DnD documentation.

Let's make things interesting: a simple example of Dojo DnD in action ! In this example we will implement very basic DnD functionality in a web page. We will have a red and a blue rectangle that can be dragged and dropped onto a target.

First, we'll start with the standard header and some CSS:

This is an important part. In this example we have only defined four classes. The 'target' and the 'source' class will be used by Dojo. The other two classes are used to create the red and blue rectangle.

Note: in 0.9, to use the class dojo.dnd.Source, you must dojo.require the resource dojo.dnd.source. Note the capitalization here. In Dojo 1.0+, both are capitalized.

Next, to hold the source and targets, we have a table with two cells. The first(left) cell hosts a source and the second(right) cell hosts a target:

The outermost <div> tag creates a source object. The inner <div> tags with class 'dojoDnDItem' create nodes, that can participate in DnD. The 'dndType' attribute can be used to specify 'type' of a node. You can specify more than one type for a node. Our nodes contains a red and blue rectangle with text on them. You can replace this content with whatever you like.

The above markup creates a pure target that can accept nodes with type 'blue' and 'darkred'. The accept attribute is a comma separated list of 'types' which can be dropped onto this node. This means that only those nodes whose 'dndType' is present in the list can be dropped onto this target. You can restrict DnD operations easily by specifying appropriate 'types' for nodes and targets. With no effort on your part, Dojo creates a default 'avatar' for each element when it is being dragged

As you can see, with pure markup and no code at all we added awesome drag and drop functionality to our page. This was a simple example of DnD, in the next chapters we will dive into more details of the API. We will see how to customize DnD behaviour, use events and restricting DnD operations.

Beautification

This text is obsolete in parts. Please refer to the official DnD documentation.

Our last example looked pretty average. After playing with it for some time you may realize that visual indicators for DnD actions could be a great addition. Wouldn't it be nice if you could customize look of nodes so as to indicate important conditions or events in drag and drop functionality?

This is made very easy in Dojo. You don't have to intercept events and add your own code to modify the look of the nodes. Nodes that take part in DnD make use of certain predefined CSS classes. All you need is to supply a declaration to customize look and feel. We will making some changes to the last example to make it beautiful.

First, we will be using these two images in place of those ugly rectangles (BLUE.png and RED.png). [inline:BLUE.png=test] [inline:RED.png=test]

Then, we change our markup a bit. We will use <img> tags instead of <div>. Finally, we add the magic <style> section. Many classes have been defined in this section. You may want to play around with them a bit. A list of such class can be found in 'dndDefault.css' file located in dojotoolkit/dojo/tests/dnd directory. Given below is the complete source :

<html>
<head>
<title>Beautification</title>
<style type="text/css">
        .target {border: 1px dotted gray; width: 300px; height: 300px;padding: 5px; 
              -moz-border-radius:8pt 8pt;radius:8pt;}
	.source {border: 1px dotted skyblue;height: 200px; width: 300px;
               -moz-border-radius:8pt 8pt;radius:8pt;}
	.dojoDndItemOver {background: #feb;border: 1px dotted gray; }
	.dojoDndItemBefore {border-left: 2px dotted gray; }
	.dojoDndItemAfter {border-right: 2px dotted gray; }
	.target .dojoDndItemAnchor {border:1px solid gray;}
	.dojoDndAvatar {font-size: 75%; color: black;}
	.dojoDndAvatar td {padding-left: 20px; padding-right: 4px;height:20px}
	.dojoDndAvatarHeader {background: #ccc; background-repeat: no-repeat;}
	.dojoDndAvatarItem {background: #eee;}
	.dojoDndMove .dojoDndAvatarHeader {background-image: url(images/dndNoMove.png);}
	.dojoDndMove .dojoDndAvatarCanDrop .dojoDndAvatarHeader {background-image: 
                url(images/dndMove.png);}
</style>
<script type="text/javascript" src="../../dojo.js" djConfig="parseOnLoad: true">
</script>
<script type="text/javascript"> 
        dojo.require("dojo.dnd.source"); // capital-S Source in 1.0
        dojo.require("dojo.parser");	
</script>
</head>
<body style="font-size: 12px;">
<h1>A Beautification Example</h1>

<table><tbody><tr>
<td>
SOURCE
<div dojoType="dojo.dnd.Source" jsId="c1" class="source">
        <img src="BLUE.png" class="dojoDndItem" dndType="blue"/>
	<img src="RED.png" class="dojoDndItem" dndType="red"/>
    	<img src="BLUE.png" class="dojoDndItem" dndType="blue"/>
	<img src="RED.png" class="dojoDndItem" dndType="red"/>   
    	<img src="BLUE.png" class="dojoDndItem" dndType="blue"/>
	<img src="RED.png" class="dojoDndItem" dndType="red"/>   
    	<img src="BLUE.png" class="dojoDndItem" dndType="blue"/>
	<img src="RED.png" class="dojoDndItem" dndType="red"/>   
    	<img src="BLUE.png" class="dojoDndItem" dndType="blue"/>     
</div>
</td>
<td>
TARGET
<div dojoType="dojo.dnd.Target" jsId="c2" class="target" accept="red,blue">
</div>
</td>
</tr><tbody/></table>

</body>
</html>

Note that we haven't added any code yet. But now if you run this example you will agree that it certainly looks more beautiful. Some points worth noticing are:

• The target and source and clearly marked.
• Node gets highlighted when mouse hovers over it.
• The node that was last to be dropped shows a black gray border making it distinguishable from others.
• When you move the avatar onto the target, the left or right border of the node beneath get highlighted , indicating whether your node will be inserted before or after it.
• The avatar looks very pretty. Observe the nice little image on top-left of the avatar. It changes to a green arrow when you move the avatar over target. This indicates that it is possible to drop the node there. But if you move the avatar out of the target, it shows a red sign.

Drag and Drop Actions

This text is obsolete in parts. Please refer to the official DnD documentation. Instead of complicated topic processors you should use onDrop(), onDropInternal(), onDropExternal() local events.

The following messages can be subscribed to :

• /dnd/source/over
• /dnd/start
• /dnd/drop
• /dnd/cancel

dojo.subscribe("/dnd/drop", function(source,nodes,iscopy){
  //code to perform some action			
});

dojo.subscribe("/dnd/start", function(source,nodes,iscopy){
  //code to perform some action		
});

dojo.subscribe("/dnd/source/over", function(source){
  //code to perform some action	
});

dojo.subscribe("/dnd/cancel", function(){
  //code to perform some action	
});

• source : Source of the nodes which are being dragged/dropped.
• nodes: Array of HTML node objects. To get corresponding DnDItem object use the following method:

  var jsnode = source.getItem(nodes[0].id);
  var d = jsnode.data;
  var t  = jsnode.type;

• iscopy: This parameter is a boolean , which is true for a copy operation and false for drag operation.

If you are interested in getting the target object, then you can use following method:

var t = dojo.dnd.manager().target;

<div dojoType="dojo.dnd.Source" jsId="cart" class="target" accept="red,blue" id="target1">
</div>

DnD Events Example
Now let us have a look at simple example of DnD events. In this example, I have created a simple shopping cart. Each blue and red sphere inside the source(shelf) has some price associated with it. This is assigned using the 'dndData' item. You can select multiple spheres from the source(shelf) and drop them onto the target (shopping cart). You will see the updated total price of your cart items. If you drop certain items back to the shelf, the corresponding amount is deducted from the total. I have attached a text file with this article which contains complete source. You will require BLUE.png and RED.png images to run the example.

Below is a excerpt from the file followed by explanation :

<script type="text/javascript"> 
dojo.require("dojo.dnd.source"); // capital-S Source in Dojo 1.0

var item_price;
var total = 0;
function AddItems(target,nodes)
{
	for (var i=0;i<nodes.length;i++)
	total += parseFloat((target.getItem(nodes[i].id)).data);
	dojo.byId("cost").innerHTML = total;
}

function SubstractItems(target,nodes)
{
	for (var i=0;i<nodes.length;i++)
	total -= parseInt((target.getItem(nodes[i].id)).data);
	dojo.byId("cost").innerHTML = total;
}
	
function ShowPrice(target,nodes)
{	var sum =0;
	for (var i=0;i<nodes.length;i++)
	sum += parseInt((target.getItem(nodes[i].id)).data);
	dojo.byId("msg").innerHTML = "Selected Item Price is $"+ sum ;
}

function ClearMsg()
{   dojo.byId("msg").innerHTML = "";}

function init()
{
	
	dojo.subscribe("/dnd/drop", function(source,nodes,iscopy){
  		var t = dojo.dnd.manager().target;
		ClearMsg();	
		if(t == source) return;
		if(t == cart)AddItems(t,nodes);
		if(t == shelf)SubstractItems(t,nodes);});

	dojo.subscribe("/dnd/start", function(source,nodes,iscopy){
  		var t = dojo.dnd.manager().target;
		ShowPrice(source,nodes);});

	dojo.subscribe("/dnd/cancel", function(){
  		ClearMsg();});

}

dojo.addOnLoad( init );
</script>

<div dojoType="dojo.dnd.Source" jsId="shelf" class="source" id="source1" accept="red,blue" singular=false>
    <img src="BLUE.png" class="dojoDndItem" dndType="blue" dndData="10" title="$10"/>
    <img src="BLUE.png" class="dojoDndItem" dndType="blue" dndData="3" title="$3"/> 
	.....    
</div>

<div dojoType="dojo.dnd.Source" jsId="cart" class="target" accept="red,blue" id="target1"></div>

Total Price (USD): <span id="cost">0.00</span><br/>

<b>Message: <span id="msg" style="color:blue"></span></b>

• A global level javascript variable 'total' is used to store the updated price.
• When the user starts dragging items, the 'ShowPrice' function gets called, which shows the total price of only the selected spheres.
• The callback function for "dnd\drop" message does the following :
  • If the target and source are the same, exit and don't modify the total. This is because item has been dropped on same source from where it was dragged.
  • If target is cart, then call 'AddItems()' to add the prices of dropped items to the total.
  • If target is shelf, it means that items are being moved from cart to shelf, so call the 'SubstractItems()' function to deduct prices of those items from total.

This was a simple example of handling the DnD events to execute custom defined actions. So far we have covered basics, looked at using CSS for rich user interface and seen how to handle events. In next chapters we will learn about the 'node creator' function and build a very simple web based application to demonstrate use of DnD.

New Events in Dojo 1.0

Moveable implements three new events:

• onMove, which implements the move itself
• onMoving, which is called before onMove, so you have a chance to change something, for example, the new position of the move to implement some restrictions.
• onMoved, which is called after the move, so you can update other objects after the move.

Events have better locality than topics: instead of getting called on every move and check if it is "the right" move, you can connect directly to events on the Moveable. Nevertheless topics are still supported.

Advanced Topics

This text is obsolete in parts. Please refer to the official DnD documentation.

Creating Source/Target with javascript
To do this we need to place two container tags on the page. The following javascript code will create a Source and Target object for us.

var node_creator = function(data, hint){
var types = [];
var node = dojo.doc().createElement("div");
if(data == 'RED'){ types.push("red"); dojo.addClass(node, "redsquare");}
if(data == 'BLUE'){ types.push("blue");dojo.addClass(node, "bluesquare"); } 
node.innerHTML = data;
node.id = dojo.dnd.getUniqueId();
return {node: node, data: data, type: types};};

c1 = new dojo.dnd.Source("c1", {creator: node_creator, accept: ["item"],
  horizontal: false, copyOnly: false});
c2 = new dojo.dnd.Target("c2", { creator: targetnode_creator,
  accept: ["item"]});
c2.insertNodes(false, ["RED","GREEN");

• 'c1' and 'c2' are ids of <div> tags used to create source and target.
• 'node_creator' function needs to be specified. This is called for creation of each node. We will discuss this part in detail in the very next topic.
• 'copyOnly' set to true indicates that always a copy operation is performed (instead of moving nodes). If set to false 'CTRL' key needs to be used for copying.
• 'horizontal' set to true indicates horizontal alignment, else use vertical alignment.
• Nodes can only be inserted using call 'insertNodes'. First parameter if set to true will result in selection of the inserted nodes. Second parameter is an array. We need to understand the working of 'insertNodes' and 'node_creator' in more detail.

{"id": "S001", "name": "PENCIL", "price": "3.20", "rating": "3", "description": "A really cool product.", "img_url": "images/RED.png"}
Sample JSON from server	HTML node created by the 'node_creator' function.	Customized avatar created using 'node_creator'

c2.selectAll();
c2.deleteSelectedNodes();
c2.clearItems();

var x = c2.getAllNodes();
for(i =0;i<x.length;i++)
{//jsNode is javascript object for node
 //x[i] represents HTML element for the node
var jsnode = c2.getItem(x[i].id);}

djConfig="usePlainJson: true"

• shopping_cart.html
• Test.php
• data.txt
• logout.html
• readme.txt