Movable Rows and Columns
- Movable Rows
- Moving Rows Between Tables
- Moving Rows To Non-Tabulator Elements
- Movable Columns
- Events
Movable Rows
To allow the user to move rows up and down the table, set the movableRows parameter in the options:
var table = new Tabulator("#example-table", { movableRows: true, //enable user movable rows })
This will allow users to drag rows around by clicking and dragging on any part of the row.
Row Handles
If you would prefer the user only be able to move a column around by one particular cell, the you can set the rowHandle property to true in the column definition object for that column to restrict the trigger for row movement to that cell only.
var table = new Tabulator("#example-table", { movableRows: true, //enable user movable rows columns:[ {rowHandle:true, formatter:"handle", headerSort:false, frozen:true, width:30, minWidth:30}, {title:"name", field:"name"} //normal column ] })
Programmatic Row Moving
If you want to programmatically move a row to a new position you can use the moveRow function.
The first argument should be the row you want to move, and can be any of the standard row component look up options.
The second argument should be the target row that you want to move to, and can be any of the standard row component look up options.
The third argument determines whether the row is moved to above or below the target row. A value of false will cause to the row to be placed below the target row, a value of true will result in the row being placed above the target
table.moveRow(1, 12, true); //move the row with an index of 1 above the row with an index of 12
Alternatively if you have the row component for the row you want to move, you can call the move function on it.
In this instance first argument should be the target row that you want to move to, and can be any of the standard row component look up options.
The second argument determines whether the row is moved to above or below the target row. A value of false will cause to the row to be placed below the target row, a value of true will result in the row being placed above the target
row.move(12, true); //move the current row above the row with an index of 12
Movable Rows and Grouping
If you move a row between groups, its values will be updated to match those of the new group.
If you move the last row in a group out of that group, that group will be removed.
Moving Rows Between Tables
Tabulator also allows you to move rows between tables. To enable this you should supply either a valid CSS selector string, a DOM node for the table or the Tabuator object for the table to the movableRowsConnectedTables option. if you want to connect to multple tables then you can pass in an array of values to this option.
var table = new Tabulator("#example-table", { movableRows: true, //enable movable rows movableRowsConnectedTables: "#table2", //connect to this table });
var table = new Tabulator("#example-table", { movableRows: true, //enable movable rows movableRowsConnectedTables: [firstTable, secondTable], //connect to these tables });
Connections to receiving tables are established when a row starts being dragged, so the receiving tables do not need to exists when the sending table is created
Note: When moving rows between tables is enabled, you will no longer be able to move rows around inside the sending table.
Note: The movableRows option must be enabled on both tables to move rows from one to the other.
Row Movement Lifecycle
When you move a row between table, a series of events take place. In the lifecycle below the sending table is where the row is being moved from, and the receiving tables are any tables that the sending table is connected to.
Sending Connections Started
The tabulator-movingrow-sending class is applied to the sending table element and the movableRowsSendingStart callback is called
Receiving Connections Started
The tabulator-movingrow-receiving class is applied to all receiving table elements and the movableRowsReceivingStart callback is triggered
Row Received
When the moving row is dropped on the receiving table the movableRowsReceiver function is triggered, if it returns true the movableRowsReceived callback is triggered, otherwise the movableRowsSentFailed is triggered
Row Sent
If the row is successfully received then the movableRowsSender function is triggered and the movableRowsSent callback is triggered, if it failed then the movableRowsReceivedFailed callback is triggered
Close Sending Connection
The sending table closes its connections to other tables, removes the tabulator-movingrow-sending class from its table element and triggers the movableRowsSendingStop callback.
Close Receiving Connection
Each receiving table then closes its connection, removes the tabulator-movingrow-receiving class from its table element and triggers the movableRowsReceivingStop callback
Receiver Function
The movableRowsReceiver option should be set on the receiving tables, and sets the action that should be taken when the row is dropped into the table.
There are several inbuilt receiver functions:
- insert - inserts row next to the row it was dropped on, if not dropped on a row it is added to the table (default)
- add - adds row to the table
- update - updates the row it is dropped on with the sent rows data
- replace - replaces the row it is dropped on with the sent row
var table = new Tabulator("#example-table", { movableRowsReceiver: "add", //add rows when dropped on the table })
You can also pass a callback to the movableRowsReceiver option for custom receiver functionality. the callback must return a boolean to indicate whether the drop should be considered successful or not (eg. you may want to reject a drop if it was not on a row)
//custom receiver function - update only one value of the toRow and only if the fromRow is dropped on a row var customReceiver = function(fromRow, toRow, fromTable){ //fromRow - the row component from the sending table //toRow - the row component from the receiving table (if available) //fromTable - the Tabulator object for the sending table if(toRow){ toRow.update({"name":fromRow.getData().name}); return true; } return false; } //set custom receiver var table = new Tabulator("#example-table", { movableRowsReceiver: customReceiver, });
Sender Function
The movableRowsSender option should be set on the sending table, and sets the action that should be taken after the row has been successfully dropped into the receiving table.
There are several inbuilt sender functions:
- false - do nothing(default)
- delete - deletes the row from the table
var table = new Tabulator("#example-table", { movableRowsSender: "delete", //remove the row from this table after it is successfully received })
You can also pass a callback to the movableRowsSender option for custom sender functionality.
//custom receiver function - increment a moved column on the sent row var customSender = function(fromRow, toRow, toTable){ //fromRow - the row component from the sending table //toRow - the row component from the receiving table (if available) //toTable - the Tabulator object for the receiving table fromRow.update({moved:fromRow.getData().moved + 1}) } //set custom receiver var table = new Tabulator("#example-table", { movableRowsSender: customSender, });
Callbacks
A range of callbacks are available for row movement between tables. See the Row Movement Callbacks section for more information.
Moving Rows To Non-Tabulator Elements
Tabulator also allows you to move rows between Tabulator tables and any other non-Tabulator elements on the page. To enable this you should supply either a valid CSS selector string or a DOM node for the elements you wish to be able to connect to to the movableRowsConnectedElements option. if you want to connect to multple tables then you can pass in an array of values to this option.
var table = new Tabulator("#example-table", { movableRows: true, //enable movable rows movableRowsConnectedElements: "#drop-area", //element to receive rows });
When you start dragging a row, the tabulator-movingrow-receiving class will be applied to all elements supplied to the movableRowsConnectedElements option, to allow you to highlight any droppable areas.
When a row is dropped on element from from the movableRowsConnectedElements option the movableRowsElementDrop event will be triggered. You can use this event to trigger any changes as a result of the drop
var table = new Tabulator("#example-table", { movableRows: true, //enable movable rows movableRowsConnectedElements: "#drop-area", //element to receive rows }); table.on("movableRowsElementDrop", function(e, element, row){ //e - mouseup event object //element - node object for the element that the row was dropped onto //row - row component for the row that was moved //add a div to the drop element containing the name property from the row data var div = document.createElement("div"); div.textContent = row.getData().name; element.appendChild(div); });
Dropping a row in an element will not directly result in the row appearing inside the element, it will simply trigger the movableRowsElementDrop callback, allowing you to the decide the next action.
Movable Columns
To allow the user to move columns along the table, set the movableColumns parameter in the options:
var table = new Tabulator("#example-table", { movableColumns: true, //enable user movable columns });
This will allow users to drag columns around using the column headers at the top of the table.
Programmatic Column Moving
If you want to programmatically move a column to a new position you can use the moveColumn function.
The first argument should be the column you want to move, and can be any of the standard column component look up options.
The second argument should be the target column that you want to move to, and can be any of the standard column component look up options.
The third argument determines whether the column is moved to before or after the target column. A value of true will cause to the column to be placed after the target column, a value of false will result in the column being placed before the target
table.moveColumn("name", "age", true); //move the name column after the age column
Alternatively if you have the column component for the column you want to move, you can call the move function on it.
In this instance first argument should be the target column that you want to move to, and can be any of the standard column component look up options.
The second argument determines whether the column is moved to before or after the target column. A value of false will cause to the column to be placed after the target column, a value of true will result in the column being placed before the target
column.move("age", true); //move the current column after the age column
Events
A range of callbacks are available for column and row movements. See the Column Events and Row Events sections for more information.