Clipboard
Overview
The clipboard module provides a range of functions that allow data to be copied out of the table into the clipboard and to be pasted into the table from the clipboard.
You can enable clipboard functionality using the clipboard config option. It can take one of four possible values:
- true - enable clipboard copy and paste
- "copy" - enable only copy functionality
- "paste" - enable only paste functionality
- false - disable all clipboard functionality (default)
var table = new Tabulator("#example-table", {
clipboard:true, //enable clipboard functionality
});
Copying Data
If the table has focus, the copyToClipboard keybinding which is by default set to the ctrl + c key combination, will trigger a copy of table to the clipboard, which data is copied depends on the state of the table.
More information on how to configure this option can be found in the Keybindings Documentation
When copying data out of the table, the raw row data will be formatted to match the current order of the columns in the table. Row data in columns that are not currently visible will not be copied to the clipboard.
Column Header Titles
var table = new Tabulator("#example-table", {
clipboardCopyHeader:false, //disable header titles in copied data
});
By default Tabulator will include the column header titles in any clipboard data, this can be turned off by passing a value of false to the clipboardCopyHeader property:
Trigger Copy Programmatically
The copyToClipboard function allows you to copy the current table data to the clipboard. It the first argument lets use to choose which data is copied to the clipboard. it can be one of three options:
The first argument is the copy selector, you can choose from any of the built in options or pass a function in to the argument, that must return the selected row components.
If you leave this argument undefined, Tabulator will use the value of the clipboardCopySelector property, which has a default value of table
The second argument sets whether the column headers should be included in the copied data, true to include the headers (default) and false to hide them.
table.copyToClipboard("selected", true); //copy the currently selected rows to the clipboard and include the column headers
Copy Selector
The copy selector is a function that is used to choose which data is copied into the clipboard. Tabulator comes with a few different selectors built in:
- active - Copy all table data currently displayed in the table to the clipboard (default)
- table - Copy all table data to the clipboard, including data that is currently filtered out
- selected - Copy the currently selected rows to the clipboard, including data that is currently filtered out
Tabulator will try to use the best selector to match your table setup. If any text is selected on the table, then it will be that text which is copied. If the table has selectable rows enabled, the it will be the currently selected rows copied to the clipboard in the order in which they were selected. Otherwise the currently visible data in the table will be copied.
These selectors can also be used when programmatically triggering a copy event. in this case if the selector is not specified it will default to the value set in the clipboardCopySelector property (which is active by default).
var table = new Tabulator("#example-table", {
clipboardCopySelector:"table", //change default selector to active
});
You can also pass a custom selector function into the clipboardCopySelector property, it should take one argument of a boolean that if true means the column headers should be include in the data and return an array of row data objects:
var table = new Tabulator("#example-table", {
clipboardCopySelector:function(showHeaders){
return this.table.getData();
}
});
Copy Formatter
The copy formatter is used to take the row data provided by the selector and turn it into a text string for the clipboard.
There is one built in copy formatter called table, if you have extended the clipboard module and want to change the default you can use the clipboardCopyFormatter property. you can also pass in a formatting function directly into this property.
var table = new Tabulator("#example-table", {
clipboardCopyFormatter:"cusstomFormatter", //use a custom built in formatter
});
You can also pass a custom formatter function into the clipboardCopyFormatter property, it should take one argument of the row data array from the copy selector function and should return a string that will be inserted into the clipboard:
var table = new Tabulator("#example-table", {
clipboardCopyFormatter:function(rowData){
return JSON.stringify(rowData);
}
});
The in-built formatter will create table formatted text string that can be pasted into any standard spreadsheet system like Excel or Google Sheets. Each column is separated by a tab and each row by a new line.
Copy Style
By default Tabulator will copy some of the tables styling along with the data to give a better visual appearance when pasted into other documents.
If you want to only copy the unstyled data then you should set the clipboardCopyStyled option to false in the table options object:
var table = new Tabulator("#example-table", {
clipboard:true,
clipboardCopyStyled:false,
});
Clipboard Accessors
You can use the accessorClipboard and accessorClipboardParams options on a column definition to alter the value of data in a column before it is added to the clipboard.
The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorClipboardParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:
var ageAccessor = function(value, data, type, params, column){
return value >= params.legalAge;
}
{title:"Under Age", field:"age", accessorClipboard:ageAccessor, accessorClipboardParams:{legalAge:18} }
{title:"Under Age", field:"age", mutator:ageMutator, mutatorParams:{legalAge:16}, mutatorEdit:ageMutator, mutatorEditParams:{legalAge:18} }
Full details of how accessors work can be found in the Accessors Documentation.
Pasting Data
You can paste data into the table by making sure it has focus and pressing ctrl + v, there is no keybinding for this as the paste action is triggered by the paste event from the browse.
When data is pasted into the table, it is validated and converted into rows by the paste parser, then a paste action is triggered.
Paste Parser
Tabulator has one built in paste parser, that is designed to take a table formatted text string from the clipboard and turn it into row data. it breaks the tada into rows on a newline character \n and breaks the rows down to columns on a tab character \t.
It will then attempt to work out which columns in the data correspond to columns in the table. It tries three different ways to achieve this. First it checks the values of all columns in the first row of data to see if they match the titles of columns in the table. If any of the columns don't match it then tries the same approach but with the column fields. If either of those options match, Tabulator will map those columns to the incoming data and import it into rows. If there is no match then Tabulator will assume the columns in the data are in the same order as the visible columns in the table and import them that way.
The inbuilt parser will reject any clipboard data that does not contain at least one row and two columns, in that case the clipboardPasteError will be triggered.
If you extend the clipboard module to add your own parser, you can set it to be used as default with the clipboardPasteParser property.
var table = new Tabulator("#example-table", {
clipboardPasteParser:"customParser", //use a custom built in parser
});
You can also pass a custom parser function into the clipboardPasteParser property, it should take one argument of the string of clipboard data and return an array of row data objects that will be passed to the paste action. If the clipboard data isn't valid it should return false.
var table = new Tabulator("#example-table", {
clipboardPasteParser:function(clipboard){
//turn clipboard data into array
return clipboardArray; //return array
}
});
Paste Action
Once the data has been parsed into row data, it will be passed to a paste action to be added to the table. There are three inbuilt paste actions:
- insert - Inserts data into the table using the addRows function (default)
- update - Updates data in the table using the updateOrAddData function
- replace - replaces all data in the table using the setData function
You can set which action should be performed using the clipboardPasteAction property.
var table = new Tabulator("#example-table", {
clipboardPasteAction:"replace", //use replace action on paste
});
You can also pass a custom action function into the clipboardPasteAction property, it should take one argument of the row data from the paste parse function and trigger an action on the table and where possible return the row objects that are created
var table = new Tabulator("#example-table", {
clipboardPasteAction:function(rowData){
return this.table.updateData(rows);
}
});
Clipboard Mutators
You can use the mutatorClipboard and mutatorClipboardParams options on a column definition to alter the value of data in a column as it is pasted into the table.
The example below will transform all ages into a boolean, showing if they are over 18 or not. The mutatorClipboardParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:
var ageAccessor = function(value, data, type, params, column){
return value >= params.legalAge;
}
{title:"Under Age", field:"age", mutatorClipboard:ageAccessor, mutatorClipboardParams:{legalAge:18} }
Note: The mutateClipboard is called before the paste action is triggered, which may result in a different mutator being triggered after mutateClipboard.
Callbacks
A range of callbacks are available for the clipboard. See the Clipboard Callbacks section for more information.