Events

JavaScript events are the perfect way to integrate the spreadsheet with your applications. There are three ways to handler those events, such as:
  • The global event dispatcher method;
  • Implement methods for individual events such as onchange, onclick, etc;
  • Implement the onevent method inside a spreadsheet plugin;

In this section, we give more details about the first two ways. If you are interested in the events inside plugins, please visit the plugins documentation.


Specific event handlers

There are several specific event handlers available on jspreadsheet as shown below.
Event description
onload onload(worksheet: Object, instance: Object)=> void
This method is called when the data in the spreadsheet is ready.
onclick onclick(worksheet: Object, section: String, x: Number, y: Number) => void
When the spreadsheet is clicked. Sections: nested | header | row | cell | selectall | tabs | cloning | toolbar | footer
onundo onundo(worksheet: Object, historyRecord: Object) => void
When undo is applied
onredo onredo(worksheet: Object, historyRecord: Object) => void
When redo is applied
onbeforesave onbeforesave(worksheet: Object, instance: Object, data: Array) => Array
Before any data is sent to the backend. Can be used to overwrite the data or to cancel the action when return false.
onsave onsave(worksheet: Object, instance: Object, data: Array) => void
After the data is sent to the server.
onbeforechange onbeforechange(worksheet: Object, cell: DOMElement, x: Number, y: Number, value: Any) => Array
Before a column value is changed. NOTE: It is possible to overwrite the original value, by return a new value on this method. v3.4.0+
onchange onchage(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, oldValue: Any) => void
After a column value is changed.
onafterchanges onafterchanges(worksheet: Object, records: Array)
After all changes are applied in the table.
oncopy oncopy(worksheet: Object, selectedCells: Array, data: String) => String
When a copy is performed in the spreadsheet. Any string returned will overwrite the user data or return null to progress with the default behavior.
onbeforepaste onbeforepaste(worksheet: Object, data: String, x: Number, y: Number) => Array
Before the paste action is performed. Can return parsed or filtered data, can cancel the action when return false.
onpaste onpaste(worksheet: Object, data: Array) => void
After a paste action is performed in the spreadsheet.
onbeforeinsertrow onbeforeinsertrow(worksheet: Object, rowNumber: Number, numOfRows: Number, insertBefore: Boolean) => Any
Before a new row is inserted. You can cancel the insert event by returning false.
oninsertrow oninsertrow(worksheet: Object, rowNumber: Number, numOfRows: Number, insertBefore: Boolean) => void
After a new row is inserted.
onbeforedeleterow onbeforedeleterow(worksheet: Object, rowNumber: Number, numOfRows: Number) => Any
Before a row is deleted. You can cancel the delete event by returning false.
ondeleterow ondeleterow(worksheet: Object, rowNumber: Number, numOfRows: Number, rowDOMElements: Array, rowData: Array, cellAttributes: Array) => void
After a row is excluded.
onbeforeinsertcolumn onbeforeinsertcolumn(worksheet: Object, columnNumber: Number, numOfColumns: Number, insertBefore: Boolean) => Any
Before a new column is inserted. You can cancel the insert event by returning false.
oninsertcolumn oninsertcolumn(worksheet: Object, columnNumber: Number, numOfColumns: Number, historyRecords: Array, insertBefore: Boolean) => void
After a new column is inserted.
onbeforedeletecolumn onbeforedeletecolumn(worksheet: Object, columnNumber: Number, numOfColumns: Number) => Any
Before a column is excluded. You can cancel the insert event by returning false.
ondeletecolumn ondeletecolumn(worksheet: Object, columnNumber: Number, numOfColumns: Number, affectedDOMElements: Array, historyProperties: Array, cellAttributes: Array) => void
After a column is excluded.
onmoverow onmoverow(worksheet: Object, origin: Number, destination: Number) => void;
After a row is moved to a new position.
onmovecolumn onmovecolumn(worksheet: Object, origin: Number, destination: Number) => void
After a column is moved to a new position.
onresizerow onresizerow(worksheet: Object, row: Mixed, height: Mixed, oldHeight: Mixed) => void
After a height change for one or more rows.
onresizecolumn onresizecolumn(worksheet: Object, column: Any, width: Any, oldWidth: Any) => void
After a column width change for one or more columns.
onselection onselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin: Number) => void
When the selection is changed.
onbeforecomments onbeforecomments(worksheet: Object, cells: Object) => Any
Before a new comment is added or updated. Return false to cancel the event.
oncomments oncomments(worksheet: Object, cells: Object) => void
After a new comment is added or updated.
onbeforesort onbeforesort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => Any
It runs before sorting a column. It should return an array with a custom sorting or false to cancel the user action.
onsort onsort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => void
When a column is sorted.
onfocus onfocus(worksheet: Object) => void
When the spreadsheed gets the focus.
onblur onblur(worksheet: Object) => void
When the spreadsheet loses the focus.
onmerge onmerge(worksheet: Object, cellName: String, colspan: Number, rowspan: Number) => void
When merge cells is executed.
onchangeheader onchangeheader(worksheet: Object, column: Number, newValue: String, oldValue: String) => void
When the header title is changed.
onchangefooter onchangefooter(worksheet: Object, column: Number, newValue: String, oldValue: String) => void
When the footers are created or updated.
onchangefootervalue onchangefootervalue(worksheet: Object, x: Number, y: Number, value: String) => void
When the value in a cell footer is changed.
oncreateeditor oncreateeditor(worksheet: Object, cell: DOMElement, x: Number, y: Number, element: DOMElement, options: Object) => void
When an editor is created.
oneditionstart oneditionstart(worksheet: Object, cell: DOMElement, x: Number, y: Number) => void
When the editor is opened.
oneditionend oneditionend(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, save: Boolean) => void
When the editor is closed.
onchangestyle onchangestyle(worksheet: Object, mixed: Any, key: String, value: String) => void
When the style of a cell is changed.
onchangemeta onchangemeta(worksheet: Object, mixed: Any, key: String, value: String) => void
When a cell meta information is added or updated.
onbeforechangepage onbeforechangepage(worksheet: Object, pageNumber: Number, oldPage: Number, quantityPerPage: Number) => Any
Before the page is changed. Can cancel the action when return is false.
onchangepage onchangepage(worksheet: Object, pageNumber: Number, oldPageNumber: Number) => void
When pagination is enabled and the user changes the page.
onbeforecreateworksheet onbeforecreateworksheet(worksheet: Options, options: Object) => Any
Add or change the options of a new worksheet.
oncreateworksheet oncreateworksheet(worksheet: Object, options: Object) => void
When the user creates a new worksheet.
onrenameworksheet onrenameworksheet(worksheet: Object, worksheetNumber: Number) => void
When the user renames a worksheet.
ondeleteworksheet ondeleteworksheet(worksheet: Object, worksheetNumber: Number) => void
When the user deletes a worksheet.
onmoveworksheet onmoveworksheet(worksheet: Object, from: Number, to: Number) => void
When the user updates the worksheet tab position.
onopenworksheet onopenworksheet(worksheet: Object, worksheet: Number) => void
When the user opens a worksheet.
onchangerowid onchangerowid(worksheet: Object, instance: Object, rows: Array) => void
When there is a row id update.
onbeforesearch onbeforesearch(worksheet: Object, query: String, results: Array) => Array
Action to be executed before searching. The accepted method return would be: null to continue with the default behavior, false to cancel the user action or an array with the row numbers to overwrite the default result.
onsearch onsearch(worksheet: Object, query: String, results: Array) => void
After the search is applied to the rows.
onbeforefilter onbeforefilter(worksheet: Object, filters: Array, data: Array) => void
Action to be executed before filtering rows. It can cancel the action by returning false.
onfilter onfilter(worksheet: Object, filters: Array, data: Array) => void
After the filter has been applied to the rows.
oncreatecell oncreatecell(worksheet: Object, element: HTMLElement, x: Number, y: Number, value: String) => void
When a new cell is created.
oncreaterow oncreaterow(worksheet: Object, rowNumber: Number, tr: HTMLElement)
After a new row is inserted.


Special events

Event description
contextmenu contextmenu(worksheet: Object, x: Number, y: Number, e: Event, section: String, section_argument1: Any, section_argument2: Any) => Array
Return false to cancel the contextMenu event, or return custom elements for the contextmenu.
updateTable updateTable(worksheet: Object, cell: Object, x: Number, y: Number, value: String) => void
Run every single table update action. Can bring performance issues if perform too much changes.


The event dispatcher

The event dispatcher is a global centralized method to handle all events. The number of arguments depends on the event fired.

NOTE: You can see events on the browser console.



<html>
<script src="https://jspreadsheet.com/v8/jspreadsheet.js"></script>
<script src="https://jsuites.net/v4/jsuites.js"></script>
<link rel="stylesheet" href="https://jspreadsheet.com/v8/jspreadsheet.css" type="text/css" />
<link rel="stylesheet" href="https://jsuites.net/v4/jsuites.css" type="text/css" />

<div id='spreadsheet'></div>

<script>
var data = [
    ['Mazda', 2001, 2000],
    ['Pegeout', 2010, 5000],
    ['Honda Fit', 2009, 3000],
    ['Honda CRV', 2010, 6000],
];

jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [{
        data: [
            ['Mazda', 2001, 2000],
            ['Pegeout', 2010, 5000],
            ['Honda Fit', 2009, 3000],
            ['Honda CRV', 2010, 6000],
        ],
        columns:[
            { title:'Model', width:'300px' },
            { title:'Price', width:'80px' },
            { title:'Model', width:'100px' },
        ],
    }],
    onevent: function(event,a,b,c,d,e,f) {
        console.log(event,a,b,c,d,e,f);
    }
});
</script>
</html>