Package com.smartgwt.client.docs

Interface TreeGridDrop

public interface TreeGridDrop

TreeGrid drag and drop

TreeGrids support drag and drop interactions to reorder or reparent nodes within the data tree, or to add new data to the tree.

As with listGrid, drag and drop capabilities may be enabled via properties such as TreeGrid.canAcceptDroppedRecords, TreeGrid.canReorderRecords and TreeGrid.canDragRecordsOut. By default, drops are only accepted on folders; set TreeGrid.canDropOnLeaves to true to allow dropping on leaf nodes as well.

Note that the behaviors described below are triggered automatically by interactive drag and drop, and can also be triggered programmatically by calling TreeGrid.transferNodes().

Custom drop behavior: To implement custom drop behavior, developers may override TreeGrid.folderDrop(). Use event.cancel() to suppress the built-in persistence behavior, then perform the desired drop action such as calling updateData() or addData() as needed.

Drag within the same tree: Default behavior when dragging node(s) to a new folder within the same tree is to reparent the dropped node(s) by modifying their parentId field value. For databound treeGrids, an update operation will be issued unless the tree has been configured to save locally.
Dragging a node to a different position within its current parent reorders it locally.
See also TreeGrid.canReparentNodes.

Drops from another component: For drops from another widget default behavior is governed by dragDataAction on the source widget plus dragRecategorize on this treeGrid. dragDataAction (set on the source) controls whether dragged records are removed from the source data set on successful drop, or left in place. dragRecategorize (set on this treeGrid) controls how the dropped records are persisted.
Dropped data may either be recategorized or added as a new node.

Drag-Recategorize: TreeGrids support recategorizing records on drop when the source component is either bound to the same DataSource, or a DataSource with a foreignKey relationship with this treeGrid's DataSource.

When both the source and target components are bound to the same DataSource - for example when a ListGrid is used to display a flat list of nodes from the selected folder of a TreeGrid - dropping a record into the TreeGrid will update the parentIdField on the dropped records to match the idField of the target folder.

When the source and target components' DataSources are related by foreignKey - for example when a ListGrid displays related records from a master tree of categories - the foreignKey field on the dropped records is updated to point to the target folder.

Whether this automatic behavior is applied depends on dragRecategorize (set on the target):

  • "checked" (the default): recategorize only if the source widget's dragDataAction is "move". This is the normal case: the user is moving data to a new location, so updating the foreignKey or parentId is appropriate.
  • "always": recategorize regardless of dragDataAction. This allows you to update the foreignKey/parentId even when the source retains a copy of the record due to dragDataAction:"copy" (e.g., dragging from a template palette).
  • "never": never recategorize. Drops always go through the generic add path below.

Add data: The default TreeGrid drop behavior when drag-recategorize is not applicable or has been disabled via dragRecategorize:"never" is to add dropped records to the tree via DataSource.addData(), with the parentId set to the target folder. addDropValues and getDropValues are applied. If DataBoundComponent.preventDuplicates is set, a duplicate check is performed (which may require a server round-trip if the cache is incomplete).

In all databound cases, queuing is used to combine the DSRequests for a multi-record drop into a single HTTP request, allowing the server to persist all changes in a single transaction.

Visual feedback

The TreeGrid.showDropIcons and ListGrid.showDropLines properties enable customization of the grid appearance during drag interactions.

By default users may drop data after the last node in the grid. The TreeGrid.canDropSiblingAfterLastNode feature allows data to be added as either a sibling of the last node, or to the tree's root node. The TreeGrid.showDropEndSpace causes a spacer to be written out after the last node during drag, so there is space available to accept the drop even if the data fills the TreeGrid viewport. To entirely disable this behavior, set ListGrid.canDropInEmptyArea to false.

For details of how data transfer from a TreeGrid to another DataBoundComponent is handled, see TreeGrid.transferDragData() and ListGrid.getDragData().

See Also: