Events

The JSS data grid offers a range of custom events that allow for greater customization of applications. These events can be used in different ways, 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.

Documentation

Specific event handlers

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

Event description
onload This method is called when the data in the spreadsheet is ready.
onload(spreadsheet: Object) => void
onclick When the spreadsheet is clicked. Sections: nested | header | row | cell | select-all | tabs | cloning | toolbar | footer
onclick(worksheet: Object, section: String, x: Number, y: Number, event: Object) => void
onundo When undo is applied
onundo(worksheet: Object, historyRecord: Object) => void
onredo When redo is applied
onredo(worksheet: Object, historyRecord: Object) => void
onbeforesave Before any data is sent to the backend. Can be used to overwrite the data or to cancel the action when return false.
onbeforesave(spreadsheet: Object, worksheet: Object, data: Object) => Boolean | Object
onsave After the data is sent to the server.
onsave(spreadsheet: Object, worksheet: Object, data: Object) => void
onerror When a new error happens.
onerror(spreadsheet: Object, result: Object) => void
onbeforechange Before a column value is changed. It is possible to overwrite the original value, by returning a new value.
onbeforechange(worksheet: Object, cell: DOMElement, x: Number, y: Number, value: Any) => Boolean | Any
onchange After a column value is changed.
onchange(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, oldValue: Any) => void
onafterchanges After all changes are applied in the table.
onafterchanges(worksheet: Object, records: Array)
oncopy 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.
oncopy(worksheet: Object, selectedCells: Array, data: String, cut: boolean) => String
onbeforepaste Before the paste action is performed. Can return parsed or filtered data, can cancel the action when return false.
onbeforepaste(worksheet: Object, data: Array, x: Number, y: Number, properties: Object[]) => boolean | Array
onpaste After a paste action is performed in the spreadsheet.
onpaste(worksheet: Object, data: Array) => void
onbeforeinsertrow Before a new row is inserted. Return false to cancel the user action.
onbeforeinsertrow(worksheet: Object, rows: Object[]) => Boolean | Object[] | void
oninsertrow After a new row is inserted.
oninsertrow(worksheet: Object, rows: Object[]) => void
onbeforedeleterow Before a row is deleted. Return false to cancel the user action.
onbeforedeleterow(worksheet: Object, rows: Number[]) => Number[] | Boolean | void
ondeleterow After a row is deleted.
ondeleterow(worksheet: Object, rows: Number[]) => void
onbeforeinsertcolumn Before a new column is inserted. Return false to cancel the user action.
onbeforeinsertcolumn(worksheet: Object, columns: Object[]) => Boolean | Object[] | void
oninsertcolumn After a new column is inserted.
oninsertcolumn(worksheet: Object, column: Object[]) => void
onbeforedeletecolumn Before a column is excluded. Return false to cancel the user action.
onbeforedeletecolumn(worksheet: Object, cols: Number[]) => boolean | Number[] | void
ondeletecolumn After a column is excluded.
ondeletecolumn(worksheet: Object, cols: Number[]) => void
onmoverow After a row is moved to a new position.
onmoverow(worksheet: Object, origin: Number, destination: Number) => void;
onmovecolumn After a column is moved to a new position.
onmovecolumn(worksheet: Object, origin: Number, destination: Number) => void
onresizerow After a height change for one or more rows.
onresizerow(worksheet: Object, row: Mixed, height: Mixed, oldHeight: Mixed) => void
onresizecolumn After a column width change for one or more columns.
onresizecolumn(worksheet: Object, column: Mixed, width: Mixed, oldWidth: Mixed) => void
onbeforeselection Before a selection happens.
onbeforeselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin?: Object) => void
onselection When the selection is changed.
onselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin?: Object) => void
onbeforecomments Before a new comment is added or updated. Return false to cancel the event.
onbeforecomments(worksheet: Object, newValues: Object) => Boolean | void
oncomments After a new comment is added or updated.
oncomments(worksheet: Object, cells: Object, oldValues: Object) => void
onbeforesort It runs before sorting a column. It should return an array with a custom sorting or false to cancel the user action.
onbeforesort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => Any
onsort When a column is sorted.
onsort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => void
onfocus When the spreadsheet gets the focus.
onfocus(worksheet: Object) => void
onblur When the spreadsheet loses the focus.
onblur(worksheet: Object) => void
onmerge When merge cells is executed.
onmerge(worksheet: Object, newValue: Object, oldValue: Object) => void
onchangeheader When the header title is changed.
onchangeheader(worksheet: Object, column: Number, newValue: String, oldValue: String) => void
onchangefooter When the footers are created or updated.
onchangefooter(worksheet: Object, newValue: [], oldValue: []) => void
onchangefootervalue When the value in a cell footer is changed.
onchangefootervalue(worksheet: Object, x: Number, y: Number, value: String) => void
onchangenested When updating the nested headers
onchangenested(worksheet: Object, options: object) => void
onchangenestedcell When updating a nested cell
onchangenestedcell(worksheet: Object, x: Number, y: Number, properties: Object) => void
oncreateeditor When an editor is created.
oncreateeditor(worksheet: Object, cell: DOMElement, x: Number, y: Number, element: DOMElement, options: Object) => void
oneditionstart When the editor is opened.
oneditionstart(worksheet: Object, cell: DOMElement, x: Number, y: Number) => void
oneditionend When the editor is closed.
oneditionend(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, save: Boolean) => void
onchangestyle When the style of a cell is changed.
onchangestyle(worksheet: Object, newValue: Object, oldValue: Object) => void
onchangemeta When cell meta information is added or updated.
onchangemeta(worksheet: Object, newValue: Object) => void
onbeforechangepage Before the page is changed. Can cancel the action by returning false.
onbeforechangepage(worksheet: Object, pageNumber: Number, oldPage: Number, quantityPerPage: Number) => Boolean | void
onchangepage When pagination is enabled and the user changes the page.
onchangepage(worksheet: Object, pageNumber: Number, oldPageNumber: Number, quantityPerPage: Number) => void
onbeforecreateworksheet Add or change the options for a new worksheet.
onbeforecreateworksheet(worksheetOptions: Object, position: Number) => boolean | Any
oncreateworksheet When the user creates a new worksheet.
oncreateworksheet(worksheet: Object, worksheetOptions: Object, position: Number) => void
onrenameworksheet When the user renames a worksheet.
onrenameworksheet(worksheet: Object, position: Number, newValue: String, oldValue: String) => void
ondeleteworksheet When the user deletes a worksheet.
ondeleteworksheet(worksheet: Object, position: Number) => void
onmoveworksheet When the user updates the worksheet tab position.
onmoveworksheet(worksheet: Object, from: Number, to: Number) => void
onopenworksheet When the user opens a worksheet.
onopenworksheet(worksheet: Object, worksheet: Number) => void
onchangerowid When there is a row id update.
onchangerowid(worksheet: Object, rows: Array) => void
onbeforefilter Action to be executed before filtering rows. It can cancel the action by returning false.
onbeforefilter(worksheet: Object, filters: Array, data: Array) => void
onfilter After the filter has been applied to the rows.
onfilter(worksheet: Object, filters: Array, data: Array) => void
oncreatecell When a new cell is created.
oncreatecell(worksheet: Object, element: HTMLElement, x: Number, y: Number, value: String) => void
oncreaterow After a new row is inserted.
oncreaterow(worksheet: Object, rowNumber: Number, tr: HTMLElement) => void
onbeforeformula Before executing a formula.
onbeforeformula(worksheet: Object, expression: String, x: Number, y: Number) => void | string | boolean
onformulachain Get the information about the expressions executed from the formula chain.
onformulachain(worksheet: Object, expressions: Array) => void
onopenfilter Customize the items available when the filter editor is open.
onopenfilter(worksheet: Object, column: number, options: Array) => options | void
onresize Viewport dimensions has changed.
onresize(worksheet: Object, w: number, h: number) => void
onchangedefinednames When definedNames is updated.
onchangedefinednames(worksheet: Object, data: []) => void
oninput New char is entered on editor.
oninput(worksheet: Object, event: Object) => void
onchangerowvisibility When the visibility of rows changes.
onchangerowvisibility(worksheet: Object, state: boolean: affected: []]) => void
onchangecolumnvisibility When the visibility of cols changes.
onchangecolumnvisibility(worksheet: Object, state: boolean: affected: []]) => void
onsearchstart It happens before all the search events.
onsearchstart(worksheet: Object, terms: String)
onsearchrow It helps to customize the searching process.
onsearchrow(worksheet: Object, rowNumber: number, terms: String)
onbeforesearch Action to be executed before the search. It can be used to cancel or to intercept and customize the search process.
onbeforesearch(worksheet: Object, terms: String, results: Array, search: Object)
onsearch After the search process is completed.
onbeforesearch(worksheet: Object, terms: String, rowNumber: Array, search: Object)
oncreatecolumn When a new column is created.
oncreatecolumn(worksheet: Object, columnNumber: number, td: HTMLElement, options: Object)
oncreaterow After a new row is inserted.
oncreaterow(worksheet: Object, rowNumber: Number, tr: HTMLElement)
ongrouprow When the user creates a group of rows
oncreaterowgroup?: (worksheet: object, row: number, elements: number|undefined) => void
onopenrowgroup When the user opens a group of rows
onopenrowgroup?: (worksheet: object, row: number) => void
oncloserowgroup When the user closes a group of rows
oncloserowgroup?: (worksheet: object, row: number) => void
ongroupcolumn When the user creates a group of columns
oncreatecolumngroup?: (worksheet: Object, column: Number, elements: Number|undefined) => void
onopencolumngroup When the user opens a group of columns
onopencolumngroup?: (worksheet: Object, column: Number) => void
onclosecolumngroup When the user closes a group of columns
onclosecolumnroup?: (worksheet: object, Object: Number) => void
onchangemedia When a media object is added, removed or updated.
(worksheet: object, newValue: object[], oldValue: object, affectedRecords: object[]) => void
onchangereferences When there is a reference update.
onchangereferences?: (worksheet: object, affected: object, deletedTokens: string[], deletedColumns: string[], deletedRows: string[]) => void;

Special events

Event description
onevent General method to handler any event. The number of arguments depends on each event.
onevent(worksheet: Object, method: Object, a?: any, b?: any, c?: any, d?: any, e?: any, f?: any) => any
contextmenu Return false to cancel the contextMenu event, or return custom elements for the contextmenu.
contextMenu(worksheet: Object, x: Number, y: Number, e: Object, items: [], section: String, a1: Any, a2: Any) => []

The global event handler

The onevent is a global and centralized method that handles all events. It's essential to note that the number of arguments required will depend on the specific event that has been triggered. NOTE: You can see events in the browser console.

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

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Material+Icons" />

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

<script>
// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('MDU1NDU5ZWY2ZTJjMWVjMDJiNTExOTMzZWE0OTY4MjQ1N2M5NmQ5MGJiZmQxZjRkMTljZWFiZDM1MTZmMGEyNDRhNTVjYzk0OGM3ZjY1OGQ5ZDYxMzgzZTBlYzNjMjA0ZmQ4NmJhYzQwMmUyMzRlMmExNmZjYTQ2ZWZlZTRjNzEsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpFek5qY3lPVGc0TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==');

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

import React, { useRef } from "react";
import { Spreadsheet, Worksheet } from "@jspreadsheet/react";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

const license = 'MDU1NDU5ZWY2ZTJjMWVjMDJiNTExOTMzZWE0OTY4MjQ1N2M5NmQ5MGJiZmQxZjRkMTljZWFiZDM1MTZmMGEyNDRhNTVjYzk0OGM3ZjY1OGQ5ZDYxMzgzZTBlYzNjMjA0ZmQ4NmJhYzQwMmUyMzRlMmExNmZjYTQ2ZWZlZTRjNzEsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpFek5qY3lPVGc0TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==';

export default function App() {
    // Spreadsheet array of worksheets
    const spreadsheet = useRef();
    // Data
    const data = [
        ['Mazda', 2001, 2000],
        ['Peugeot', 2010, 5000],
        ['Honda Fit', 2009, 3000],
        ['Honda CRV', 2010, 6000],
    ];
    const columns = [
        { title:'Model', width:'300px' },
        { title:'Year', width:'80px' },
        { title:'Price', width:'100px' },
    ];

    // Event handler
    const onevent = (event,a,b,c,d,e,f) => {
        console.log(event,a,b,c,d,e,f);
    };

    // Render data grid component
    return (
        <Spreadsheet ref={spreadsheet} license={license} onevent={onevent}>
            <Worksheet data={data} columns={columns} />
        </Spreadsheet>
    );
}

<template>
    <Spreadsheet ref="spreadsheet" :license="license" :onevent="onevent">
        <Worksheet :data="data" :columns="columns" />
    </Spreadsheet>
</template>

<script>
import { Spreadsheet, Worksheet } from "@jspreadsheet/vue";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

const license = 'MDU1NDU5ZWY2ZTJjMWVjMDJiNTExOTMzZWE0OTY4MjQ1N2M5NmQ5MGJiZmQxZjRkMTljZWFiZDM1MTZmMGEyNDRhNTVjYzk0OGM3ZjY1OGQ5ZDYxMzgzZTBlYzNjMjA0ZmQ4NmJhYzQwMmUyMzRlMmExNmZjYTQ2ZWZlZTRjNzEsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpFek5qY3lPVGc0TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==';

export default {
    components: {
        Spreadsheet,
        Worksheet,
    },
    methods: {
        // Event handler
        onevent (event,a,b,c,d,e,f) {
            console.log(event,a,b,c,d,e,f);
        };
    },
    data() {
        // Data
        const data = [
            ['Mazda', 2001, 2000],
            ['Peugeot', 2010, 5000],
            ['Honda Fit', 2009, 3000],
            ['Honda CRV', 2010, 6000],
        ];
        const columns = [
            { title:'Model', width:'300px' },
            { title:'Year', width:'80px' },
            { title:'Price', width:'100px' },
        ];

        return {
            data,
            columns,
            license,
        };
    }
}
</script>

import { Component, ViewChild, ElementRef } from "@angular/core";
import * as jspreadsheet from "jspreadsheet";

// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('MDU1NDU5ZWY2ZTJjMWVjMDJiNTExOTMzZWE0OTY4MjQ1N2M5NmQ5MGJiZmQxZjRkMTljZWFiZDM1MTZmMGEyNDRhNTVjYzk0OGM3ZjY1OGQ5ZDYxMzgzZTBlYzNjMjA0ZmQ4NmJhYzQwMmUyMzRlMmExNmZjYTQ2ZWZlZTRjNzEsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpFek5qY3lPVGc0TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==');

@Component({
    selector: "app-root",
    template: `<div #spreadsheet></div>`
})
export class AppComponent {
    @ViewChild("spreadsheet") spreadsheet: ElementRef;
    // Worksheets
    worksheets: jspreadsheet.worksheetInstance[];
    // Create a new data grid
    ngOnInit() {
        // Create spreadsheet
        this.worksheets = jspreadsheet(this.spreadsheet.nativeElement, {
            worksheets: [{
                data: [
                    ['Mazda', 2001, 2000],
                    ['Peugeot', 2010, 5000],
                    ['Honda Fit', 2009, 3000],
                    ['Honda CRV', 2010, 6000],
                ],
                columns:[
                    { title:'Model', width:'300px' },
                    { title:'Year', width:'80px' },
                    { title:'Price', width:'100px' },
                ],
            }],
            onevent: function(event,a,b,c,d,e,f) {
                console.log(event,a,b,c,d,e,f);
            }
        });
    }
}

Edit this page on GitHub