Documentation

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;
Implementing methods for individual events such as onchange, onclick, etc;
Implementing the onevent method inside a spreadsheet plugin.

In this section, we provide more details about the first two methods. If you are interested in the events inside plugins, please visit the plugin's documentation.

Specific event handlers

There are several specific event handlers available in Jspreadsheet as shown below:

Event	description
onload	`onload(spreadsheet: 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(spreadsheet: Object, worksheet: Object, data: Object) => Boolean \| Object` 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(spreadsheet: Object, worksheet: Object, data: Object) => void` After the data is sent to the server.
onbeforechange	`onbeforechange(worksheet: Object, cell: DOMElement, x: Number, y: Number, value: Any) => Boolean \| Any` Before a column value is changed. NOTE: It is possible to overwrite the original value, by returning 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: Array, x: Number, y: Number, style: Array, processedData: String) => boolean \| 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) => boolean \| void` Before a new row is inserted. You can cancel the insert event by returning false.
oninsertrow	`oninsertrow(worksheet: Object, rowNumber: Number, numOfRows: Number, records: Array, insertBefore: Boolean) => void` After a new row is inserted.
onbeforedeleterow	`onbeforedeleterow(worksheet: Object, rowNumber: Number, numOfRows: Number) => boolean \| void` 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 deleted.
onbeforeinsertcolumn	`onbeforeinsertcolumn(worksheet: Object, columnNumber: Number, numOfColumns: Number, insertBefore: Boolean) => boolean \| void` 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) => Boolean \| void` 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: Mixed, width: Mixed, oldWidth: Mixed) => void` After a column width change for one or more columns.
onselection	`onselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin?: Object) => void` When the selection is changed.
onbeforecomments	`onbeforecomments(worksheet: Object, newValues: Object) => Boolean \| void` Before a new comment is added or updated. Return false to cancel the event.
oncomments	`oncomments(worksheet: Object, cells: Object, oldValues: 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 spreadsheet gets the focus.
onblur	`onblur(worksheet: Object) => void` When the spreadsheet loses the focus.
onmerge	`onmerge(worksheet: Object, newValue: Object, oldValue: Object) => 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, newValue: [], oldValue: []) => 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.
onchangenested	`onchangenested(worksheet: Object, options: object) => void` When updating the nested headers
onchangenestedcell	`onchangenestedcell(worksheet: Object, x: Number, y: Number, properties: Object) => void` When updating a nested cell
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, newValue: Object, oldValue: Object) => void` When the style of a cell is changed.
onchangemeta	`onchangemeta(worksheet: Object, newValue: Object) => void` When cell meta information is added or updated.
onbeforechangepage	`onbeforechangepage(worksheet: Object, pageNumber: Number, oldPage: Number, quantityPerPage: Number) => Boolean \| void` Before the page is changed. Can cancel the action by returning false.
onchangepage	`onchangepage(worksheet: Object, pageNumber: Number, oldPageNumber: Number, quantityPerPage: Number) => void` When pagination is enabled and the user changes the page.
onbeforecreateworksheet	`onbeforecreateworksheet(worksheetOptions: Object, position: Number) => boolean \| Any` Add or change the options for a new worksheet.
oncreateworksheet	`oncreateworksheet(worksheet: Object, worksheetOptions: Object, position: Number) => void` When the user creates a new worksheet.
onrenameworksheet	`onrenameworksheet(worksheet: Object, position: Number, newValue: String, oldValue: String) => void` When the user renames a worksheet.
ondeleteworksheet	`ondeleteworksheet(worksheet: Object, position: 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, rows: Array) => void` When there is a row id update.
onbeforesearch	`onbeforesearch(worksheet: Object, query: String, results: Array) => Array \| boolean \| void` 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) => void` After a new row is inserted.
onbeforeformula	`onbeforeformula(worksheet: Object, expression: String, x: Number, y: Number) => void \| string \| boolean` Before executing a formula.
onformulachain	`onformulachain(worksheet: Object, expressions: Array) => void` Get the information about the expressions executed from the formula chain.
onopenfilter	`onopenfilter(worksheet: Object, column: number, options: Array) => options \| void` Customize the items available when the filter editor is open.

Special events

Event	description
contextmenu	`contextmenu(worksheet: Object, x: Number, y: Number, e: Event, section: String, section_argument1?: Any, section_argument2?: Any) => Array \| boolean` 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 performing 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 triggered.

NOTE: You can see events in the browser console.

<html>
<script src="https://jspreadsheet.com/v8/jspreadsheet.js"></script>
<script src="https://jsuites.net/v5/jsuites.js"></script>
<link rel="stylesheet" href="https://jspreadsheet.com/v8/jspreadsheet.css" type="text/css" />
<link rel="stylesheet" href="https://jsuites.net/v5/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>

Events

Specific event handlers

Special events

The event dispatcher

Create applications with spreadsheet-like controls