Row Dragging

Row dragging is used to rearrange rows by dragging the row with the mouse. To enable row dragging, set the column property rowDrag on one (typically the first) column.

There are two ways in which row dragging works in the grid, managed and unmanaged:

• Managed Dragging: This is the simplest and the grid will rearrange rows as you drag them.
• Unmanaged Dragging: This is more complex and more powerful. The grid will not rearrange rows as you drag. Instead the application is responsible for responding to events fired by the grid and rows are rearranged by the application.

Managed Dragging

In managed dragging, the grid is responsible for rearranging the rows as the rows are dragged. Managed dragging is enabled with the property rowDragManaged=true.

The example below shows simple managed dragging. The following can be noted:

• The first column has rowDrag=true which results in a draggable area included in the cell.
• The property rowDragManaged is set, to tell the grid to move the row as the row is dragged.
• If a sort (click on the header) or filter (open up the column menu) is applied to the column, the draggable icon for row dragging is hidden. This is consistent with the constraints explained after the example.

The logic for managed dragging is simple and has the following constraints:

• Works with Client-side row model only and not with the Infinite, Server-side or Viewport row models.
• Does not work if Pagination is enabled.
• Does not work when sorting is applied. This is because the sort order of the rows depends on the data and moving the data would break the sort order.
• Does not work when filtering is applied. This is because a filter removes rows making it impossible to know what 'real' order of rows when some are missing.
• Does not work when row grouping or pivot is active. This is because moving rows between groups would require a knowledge of the underlying data which only your application knows.

These constraints are easily got around by using unmanaged row dragging explained below.

Suppress Row Drag

You can hide the draggable area by calling the grid API setSuppressRowDrag() or by setting the bound property suppressRowDrag.

The example below is almost identical to the previous example with the following differences:

• Button Suppress will hide the drag icons.
• Button Remove Suppress will un-hide the drag icons.
• Applying a sort or a filter to the grid will also suppress the drag icons.

Unmanaged Dragging

Unmanaged dragging is the default dragging for the grid. To use it, do not set the property rowDragManaged. Unmanaged dragging differs from managed dragging in the following ways:

• The grid does not manage moving of the rows. The only thing the grid responds with is firing drag events. It is up to the application to do the moving of the rows (if that is what the application wants to do).
• Dragging is allowed while sort is applied.
• Dragging is allowed while filter is applied.
• Dragging is allowed while row group or pivot is applied.

Row Drag Events

There are four grid events associated with row dragging which are:

• rowDragEnter: A drag has started, or dragging already started and the mouse has re-entered the grid having previously left the grid.
• rowDragMove: The mouse has moved while dragging.
• rowDragLeave: The mouse has left the grid while dragging.
• rowDragEnd: The drag has finished over the grid.

Typically a drag will fire the following events:

1. rowDragEnter fired once - The drag has started.
2. rowDragMove fired multiple times - The mouse is dragging over the rows.
3. rowDragEnd fired once - The drag has finished.

Additional rowDragLeave and rowDragEnter events are fired if the mouse leaves or re-enters the grid. If the drag is finished outside of the grid, then the rowDragLeave is the last event fired and no rowDragEnd is fired, as the drag did not end on the grid.

Each of the four row drag events has the following attributes:

• type: One of {rowDragEnter, rowDragMove, rowDragEnd, rowDragLeave}.
• api: The grid API.
• columnApi: The grid Column API.
• event: The underlying mouse move event associated with the drag.
• node: The row node getting dragged.
• overIndex: The row index the mouse is dragging over.
• overNode: The row node the mouse is dragging over.
• y: The vertical pixel location the mouse is over, with zero meaning the top of the first row. This can be compared to the rowNode.rowHeight and rowNode.rowTop to work out the mouse position relative to rows. The provided attributes overIndex and overNode means the y property is mostly redundant. The y property can be handy if you want more information such as 'how close is the mouse to the top or bottom of the row'.
• vDirection: Direction of the drag, either up, down or blank (if mouse is moving horizontally and not vertically).

Example Events

The below example demonstrates unmanaged row dragging with no attempt by the application or the grid to re-order the rows - this is on purpose to demonstrate the grid will not attempt to re-order rows when unless you set the rowDragManaged property. The example also demonstrates all the events that are fired.

From the example the following can be noted:

• The first column has rowDrag=true which results in a draggable area included in the cell.
• The grid has not set rowDragManaged which results in the grid not reordering rows as they are dragged.
• All of the drag events are listened for and when one is received, it is printed to the console. To best see this, open the example in a new tab and open the developer console.
• Because rowDragManaged is not set, the row dragging is left enabled even if sorting or filtering is applied. This is because your application should decide if dragging should be allowed / suppressed using the suppressRowDrag property.

Simple Unmanaged Example

The example below shows how to implement simple row dragging using unmanaged row dragging and events. The example behaves the same as the first example above however the logic for moving the rows is with the application and not the grid.

From the example the following can be noted:

• The property suppressRowDrag=true is set by the application depending on whether sorting or filtering is active. This is because the logic in the example doesn't cover these scenarios and wants to prevent row dragging when sorting or filtering is active.
• To update the data the example uses an Immutable Data Store and sets deltaRowDataMode=true. The application is free to use any update mechanism it wants - see Updating Data for different options.

The simple example doesn't add anything that managed dragging gives (the first example on this page). Things get interesting when we introduce complex scenarios such as row grouping or tree data, which are explained below.

Dragging & Row Grouping

Row Grouping in the grid allows grouping rows by a particular column. Dragging rows while grouping is possible when doing unmanaged row dragging. The application is responsible for updating the data based on the drag events fired by the grid.

The example below uses row dragging to place rows into groups. It does not try to order the rows within the group. For this reason, the logic works regardless of sorting or filtering.

The example below shows row dragging with Row Grouping where the following can be noted:

• The column 'Athlete' has row drag true for non-group rows. This is achieved using the function variant of the rowDrag property.
• The grid has not set rowDragManaged property which results in unmanaged row dragging.
• The example does not re-order the rows. Instead the example demonstrates putting the rows into groups. If you drag a row, you can place it in a different parent group.
• The example listens to the event onRowDragMove and changes the group a row belongs to while the drag is happening (which is different to the next Tree Data example which waits until the drag is complete). It is the choice of your application whether it wants to move rows in real time during the drag, or wait until the drag action is complete.
• The application can still move rows to groups even if ordering or sorting is applied. For this reason, the application does not suppress row dragging if sorting or filtering is applied.

Row Dragging & Tree Data

Tree Data in the grid allows providing data to the grid in parent / child relationships, similar to that required for a file browser. Dragging rows with tree data is possible when doing unmanaged row dragging. The application is responsible for updating the data based on the drag events fired by the grid.

Example Tree Data

The example below shows Tree Data and row dragging where the following can be noted:

• The auto-group column has row drag true for all rows.
• The example registers for onRowDragEnd events and rearranges the rows when the drag completes.
• The applications does NOT rearrange the rows as the drag is happening. Instead it waits for the onRowDragEnd event before updating the data.

Example Highlighted Tree Data

The example above works, however it is not intuitive as the user is given no visual hint what folder will be the destination folder. The example below continues with the example above by providing hints to the user while the drag is in progress. From the example the following can be observed:

• The example registers for onRowDragMove events and works out what folder the mouse is over as the drag is happening.
• While the row is dragging, the application highlights the folder that is currently selected as the destination folder (called potentialParent in the example code).
• The applications does NOT rearrange the rows as the drag is happening. As with the previous example, it waits for the onRowDragEnd event before updating the data.
• The example uses Cell Class Rules to highlight the destination folder. The example adds the example provided CSS class hover-over to all the cells of the destination folder.
• The example uses Refresh Cells to get the grid to execute the Cell Class Rules again over the destination folder when the destination folder changes.

Dragging Multiple Rows

With unmanaged row dragging, the application is in control of what gets dragged. So it is possible to use the events to drag more than one row at a time, eg to move all selected rows in one go if using row selection.

Other Row Models

Unmanaged row dragging will work with any of the row models Infinite, Server-side and Viewport. With non-managed, the implementation of what happens when a particular drag happens is up to your application.

Because the grid implementation with regards row dragging is identical to the above, examples of row dragging with the other row models are not given. How your application behaves with regards the row drag events is the difficult bit, but that part is specific to your application and how your application stores it's state. Giving an example here with a different data store would be redundant.