XUI: Extensible User Interface Framework

Using the Drag-and-Drop API

During a dragging process, a DragDropEvent JavaScript object is available for all methods that are assigned to supported drag and drop attributes. The object is ready to be used when drag-begin phase is started, and it persists until the end of the drag-complete phase. DragDropEvent object offers several methods that enhances the drag and drop process.

DragDropEvent

Object getSource()
Object getTarget()
void setTransferObject(transferObject)
Object getTransferObject()

The getSource() and getTarget() methods
Commonly during the drag-drop phases, a user might want to perform component specific actions, such as row highlighting, row addition/deletion and node addition/removal. By using the getSource() method, the user-defined JavaScript method that is registered to the drag-drop attributes has a reference to the source component. Similarly, by using the getTarget() method, the method has a reference to the targeted component as a JavaScript object.

The getTransferObject() and setTransferObject() methods
The core idea of performing a drag and drop action is to transfer data from one UI component into another. The DragDropEvent object facilitates this by providing the getTransferObject() and setTransferObject() methods.

Commonly, when dragging process begins, the transfer data is identified at this phase. This data is represented in JavaScript valid data-type or object. To set the transferable data, a user can call the DragDropEvent’s setTransferObject() method and pass the transferable data object as the method parameter.

As the drag and drop is completed, the transferable data needs to be transferred to the targeted object. To get the transferable data, a user can call the DragDropEvent’s getTransferObject() method. If nothing is set earlier, the method will return null.

Example
The following example is not intended to teach a user to embed a working drag and drop example. This merely an overview/ a brief demonstration on how approximately the implementation will look like. A comprehensive working example of drag and drop can be found on component specific documentation (xtable, xtree, and xtabbedpane).

The Source Component

<xtable ..
    drag-begin="beginDragging"
    drag-exit="exitSource"
    drag-completed="completeDragDrop">
    ...  <!-- xtable data -->
    .... <!-- xtable data -->
</xtable>

The Target Component

<xtree
    drag-enter="enterTarget"
    drag-over="overTarget"
    drag-drop="transferDataCompletion">	
    ... <!-- xtree data -->
    ... <!-- xtree data -->
</xtree>

The User-Defined JavaScript Code

<xscript>

/****************************** 
  SOURCE RELATED METHODS  
 ******************************/

// beginDragging is attached to the xtable drag-begin attribute
function beginDragging(dragDropEvent)
{
   // get the source object using DragDropEvent's getSource() method
   var source = dragDropEvent.getSource();
   ...
   // do object specific action (such as highligh row, etc)
   ...
   // setting transferable data into DragDropEvent's setTransferObject() method
   var data = "Special Mission Data";
   dragDropEvent.setTransferObject(data);
}

// exitSource is attached to the xtable drag-exit attribute
function exitSource(dragDropEvent)
{
   // ... do something or nothing ...
}

// completeDragDrop is attached to the xtable drag-exit attribute
function completeDragDrop(dragDropEvent)
{
   //... do something or nothing ...
}

/****************************** 
      TARGET RELATED METHODS  
 ******************************/

// enterTarget is attached to the xtree drag-enter attribute
function enterTarget(dragDropEvent)
{
   // ... do something or nothing ...
}

// overTarget is attached to the xtable drag-drop attribute
function overTarget(dragDropEvent)
{
   //... do something or nothing ...
}

// transferData is attached to the xtable drag-drop attribute
function transferDataCompletion(dragDropEvent)
{
   // get the source object using DragDropEvent's getSource() method
   var source = dragDropEvent.getSource();
   
   // get the target object using DragDropEvent's getTarget() method
   var target = dragDropEvent.getTarget();

   // get the transferable data that was set earlier
   var data = dragDropEvent.getTransferObject();
   
   // perform component specific actions... 
   // such as:
   // target.insertNode(data) to insert a new node in a tree
   // source.removeRow(source.selectedRowIndex) to remove the selected row
   ....
   
}

</xscript>

Next: Applying Drag-and-Drop to xtable
Back to: Application Guide