Jspreadsheet Upgrade from v4 to v5

Overview

The latest update to Jspreadsheet CE introduces significant enhancements, simplifying customization and improving compatibility across all distributions. Key updates include structural refinements, increased extensibility, and standardized functionality. Upgrading from version 4 to version 5 includes breaking changes due to updates in properties, methods, and events. This document outlines the critical adjustments required to transition your existing code to the new version.

Be aware that upgrading from version 4 to version 5 introduces breaking changes resulting from updates to properties, methods, and events.

Spreadsheet vs. Worksheets

Jspreadsheet CE introduces two distinct levels: the spreadsheet level and the worksheet level. This separation avoids redundancy by centralizing elements that should not be duplicated across each worksheet, such as toolbars or event declarations.

Version 4

In version 4, all properties were defined within a single object.

jspreadsheet(document.getElementById('spreadsheet'), {
    toolbar: true,
    minDimensions: [4,4],
    onchange: function() {
        // something
    }
});

Version 5

In version 5, the worksheets attribute allows you to declare multiple worksheets, each with specific properties, while maintaining centralized common configurations at the spreadsheet level.

// Create your spreadsheets
jspreadsheet(document.getElementById('spreadsheet'), {
    toolbar: true,
    worksheets: [
        {
            minDimensions: [4,4],
        },
        // More worksheets
    ],
    onchange: function() {
        // something
    }
});

Instances

When creating a new spreadsheet, Jspreadsheet returns an array of worksheet instances. Each worksheet object includes a parent property, allowing access to spreadsheet-level features.

// Create your spreadsheets
let worksheets = jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [
        {
            minDimensions: [4,4],
        },
    ],
});

// Get the spreadsheet data
worksheets[0].getData();
// Show toolbar
worksheets[0].parent.showToolbar();

Translations

From version 5, translations can be managed globally using jspreadsheet.setDictionary. This method accepts an object where the keys are the original English texts and the values are their translations.

Version 4

In version 4, translations were defined directly within the spreadsheet instance:

jspreadsheet(document.getElementById('spreadsheet'), {
    minDimensions: [4,4],
    text:{
        noRecordsFound: 'Nenhum registro encontrado',
        show: 'Show',
        // many other translations
    }
});

Version 5

In version 5, you define translations globally using setDictionary, making it easier to manage and apply them across all instances:

// Translate all application
jspreadsheet.setDictionary({
    'No records found': 'Nenhum registro encontrado',
    'Show': 'Exibir',
    //...
});

// Create your spreadsheets
jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [{
        minDimensions: [4,4],
    }],
});

Plugin and Editor Support

Jspreadsheet CE now includes plugin support, offering developers enhanced flexibility and the ability to extend functionality. Editors align more closely with the Pro version, ensuring more across the different distributions.

// Create your spreadsheets
jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [{
        minDimensions: [4,4],
        columns: [{ type: myEditor }], // Custom editors
    }],
    plugins: { myPlugin }, // Plugin declaration
});

Library Level

Library Level Property Updates

Status	Property	Description
New	destroyAll	Destroys all spreadsheets across all namespaces.
New	getWorksheetInstanceByName	Retrieves a worksheet by its name and namespace. Can also return a namespace depending on the first argument.
New	setDictionary	Adds a helper for defining new translations.
Removed	tabs	Removed as it is no longer necessary since CE always creates a spreadsheet by default.
Removed	createTabs	Removed as it is no longer necessary since CE now always creates a spreadsheet by default.
Removed	getColumnName	Removed because this functionality already exists in the helpers.

Helpers

Status	Method	Description
New	getCoordsFromRange	Retrieves coordinates from a specified range.
Updated	createFromTable	Now functions like the previous library-level method with the same name.
Updated	getColumnNameFromCoords	Renamed to getCellNameFromCoords.
Updated	getCoordsFromColumnName	Renamed to getCoordsFromCellName.
Removed	injectArray	Removed as it was not documented.

Spreadsheet Level

Settings

Status	Property	Description
New	parseHTML	Similar functionality to the previous stripHTML property.
New	debugFormulas	Enables formula debugging. Debugging was previously always enabled by default but is now disabled.
New	fullscreen	Defines a spreadsheet as fullscreen.

Toolbars

Status	Method	Description
New	hideToolbar	Hides the toolbar.
New	showToolbar	Displays the toolbar using the current settings.

Events

All events are now defined at the spreadsheet level. Except for the onload, onbeforesave, and onsave events, all other events now receive the worksheet instance as their first argument. Additional changes to method arguments have also been introduced.

Status	Event	Description
New	onbeforeformula	Intercepts formulas before they are calculated.
New	onbeforeselection	Intercepts cell selection and cancels it if false is returned.
New	oncreatecell	Triggered when a cell is created.
New	oncreateworksheet	Triggered when a worksheet is created.
New	ondeleteworksheet	Triggered when a worksheet is deleted.
Updated	onafterchanges	All arguments for this event have been updated.
Updated	onbeforedeletecolumn	All arguments for this event have been updated.
Updated	onbeforedeleterow	All arguments for this event have been updated.
Updated	onbeforeinsertcolumn	All arguments for this event have been updated.
Updated	onbeforeinsertrow	All arguments for this event have been updated.
Updated	onbeforepaste	The second argument is a 2D array of objects with a "value" property representing the values to be pasted.
Updated	onbeforesave	The first argument is now the spreadsheet instance.
Updated	onchangeheader	The third and fourth arguments for this event have been swapped.
Updated	onchangemeta	The second argument is now always an object containing the changes. The third and fourth arguments have been removed.
Updated	onchangepage	This event now includes a fourth argument for the number of items per page.
Updated	onchangestyle	All arguments for this event have been updated.
Updated	oncopy	Can cancel the copy action or override the copied value.
Updated	oncreateeditor	The fifth argument is always null, and a new fifth argument has been added for the column configuration.
Updated	ondeletecolumn	All arguments for this event have been updated.
Updated	ondeleterow	All arguments for this event have been updated.
Updated	oninsertcolumn	All arguments for this event have been updated.
Updated	oninsertrow	All arguments for this event have been updated.
Updated	onload	The first argument is now the spreadsheet instance.
Updated	onmerge	All arguments for this event have been updated.
Updated	onmovecolumn	This event now includes a fourth argument indicating the number of columns moved.
Updated	onmoverow	This event now includes a fourth argument indicating the number of rows moved.
Updated	onpaste	All arguments for this event have been updated.
Updated	onredo	The second argument has been updated based on the method the event refers to.
Updated	onsave	The first argument is now the spreadsheet instance.
Updated	onsort	Now includes a fourth argument, an array representing the new order of rows.
Updated	onundo	The second argument has been updated based on the method the event refers to.

Worksheets Updates

Attributes

Status	Property	Description
Updated	highlighted	Now stores records instead of just cell tags.
Updated	csvHeaders	The default value for this property is now false.
Updated	nestedHeaders	Now requires a two-dimensional array.
Updated	ignoreEvents	Now operates at the spreadsheet level.
Updated	options	Updated to no longer set default values for several properties.
Updated	records	Now a 2D array containing objects with cell coordinates and corresponding HTML elements.
Updated	rows	Now an array of objects with the HTML element for each row and index.
Updated	persistance	Renamed to persistence.
Updated	rowResize	The default value for this property is now true.
Updated	tableHeight	Now also accepts a value of type number.
Updated	tableWidth	Now also accepts a value of type number.
Updated	toolbar	Now supports being a function, boolean, or a configuration object for the jSuites toolbar. Array configurations were also updated, and it is now spreadsheet-level.
Removed	contextMenu	Now operates at the spreadsheet level and includes four new arguments.
Removed	fullscreen	Now operates at the spreadsheet level.
Removed	colgroup	Replaced by the new cols property, which functions similarly.
Removed	el	Replaced by the new element property.
Removed	contextMenu	Now operates at the spreadsheet level.
Removed	copyCompatibility	This property has been removed.
Removed	detachForUpdates	This property has been removed.
Removed	imageOptions	Use the column's configuration object instead.
Removed	includeHeadersOnCopy	This property has been removed.
Removed	loadingSpin	This property has been removed.
Removed	method	This property has been removed.
Removed	requestVariables	This property has been removed.
Removed	stripHTML	Use the parseHTML property instead.
Removed	stripHTMLOnCopy	This property has been removed.
Removed	text	Removed as JSS CE now uses jSuites.translate.
Removed	updateTable	This property has been removed.

Comments

Status	Property	Description
New	comments	Represents comments associated with the worksheet.
Updated	allowComments	The default value of this property is now true.
Updated	getComments	The undocumented second argument has been removed. Additionally, the first argument can no longer be an array.
Updated	setComments	The first argument of this method has been updated. Additionally, the undocumented third argument has been removed.

Columns

Status	Property	Description
New	columns.render	Intercepts and modifies visible data before inserting into a grid cell.
Updated	columnDrag	The default value for this property is now true.
Updated	columns.type	Now accepts an object to create custom editors, replacing the old columns.editor. Note: "autocomplete" and "readonly" have been removed; use autocomplete and readOnly properties instead.
Removed	columns.editor	This property has been removed. Its functionality for creating custom editors has been moved to the columns.type property.
Removed	columns.stripHTML	This property has been removed.
Removed	colAlignments	Use the align property in the columns array items instead.
Removed	colHeaders	Use the title property in the columns array items instead.
Removed	colWidths	Use the width property in the columns array items instead.
Updated	hideColumn	The first argument for this method can now also be an array.
Updated	showColumn	The first argument for this method can now also be an array.
Updated	setWidth	Previously undocumented, this method had a third argument, which has now been removed.

Data

Status	Method	Description
New	getDataFromRange	Retrieves data from a specified range.
Updated	getData	This method now accepts two additional arguments.
Updated	setData	No longer emits the onload event, and its first argument can no longer be a JSON object.
Updated	getValue	The first argument must now be a string.
Updated	setValue	The object array in the first argument no longer uses the newValue property; use the value property instead.
Updated	getColumnData	This method now includes a second argument.
Updated	setColumnData	This method now includes a third argument.
Updated	getRowData	This method now includes a second argument.
Updated	setRowData	This method now includes a third argument.
Updated	download	This method now accepts a second argument.
Updated	getLabel	The first argument can no longer be an array with two numbers. Instead, the method now accepts two numeric arguments.
Removed	parseCSV	Use the helper methods instead.
Removed	getJson	Use the getData method instead.

Selection

Status	Method	Description
New	getHighlighted	Retrieves the coordinates of the highlighted selections.
New	getSelected	Retrieves information about selected cells in the worksheet.
New	getSelection	Retrieves the coordinates of the selected range in the worksheet.
New	isSelected	Checks if a cell is part of the current selection.
Updated	updateSelectionFromCoords	Previously undocumented, this method had a fifth argument, which has now been removed. It can now return false if the selection is cancelled.
Updated	getSelectedColumns	This method now accepts an argument.
Updated	getSelectedRows	The first argument for this method has been updated.
Updated	resetSelection	Previously undocumented, this method had an argument, which has now been removed.
Removed	updateSelection	Use the updateSelectionFromCoords method instead.

Editors

Calendar Editor Type

Status	Property	Description
Updated	format	The default value for this property is now "YYYY-MM-DD".
Removed	value	This property has been removed.
Deprecated	months	Still available but should be replaced with the setDictionary method.
Deprecated	weekdays	Still available but should be replaced with the setDictionary method.
Deprecated	weekdays_short	Still available but should be replaced with the setDictionary method.

Removed

The following methods and attributes have been removed from the public scope or the library:

Methods

• col
• conditionalSelectionUpdate
• copyData
• createCell
• createCellHeader
• createNestedHeader
• createRow
• createTable
• createToolbar
• getColumnOptions
• getDropDownValue
• getFreezeWidth
• getJsonRow
• getLabelFromCoords
• hash
• historyProcessColumn
• historyProcessRow
• init
• isColMerged
• isRowMerged
• loadDown
• loadPage
• loadUp
• loadValidation
• onafterchanges
• parseNumber
• parseValue
• prepareJson
• prepareTable
• refresh
• refreshSelection
• removeCopySelection
• removeCopyingSelection
• row
• save
• scrollControls
• setCheckRadioValue
• setFooter
• setHistory
• updateCell
• updateCopySelection
• updateCornerPosition
• updateFormula
• updateFormulaChain
• updateFormulas
• updateFreezePosition
• updateMeta
• updateNestedHeader
• updateOrder
• updateOrderArrow
• updatePagination
• updateResult
• updateScroll
• updateTable
• updateTableReferences
• wheelControls

Attributes

• setExtensions;
• formula;
• build;
• keyDownControls;
• mouseDownControls;
• mouseUpControls;
• mouseMoveControls;
• mouseOverControls;
• doubleClickControls;
• copyControls;
• cutControls;
• pasteControls;
• contextMenuControls;
• touchStartControls;
• touchEndControls;
• fromSpreadsheet;
• validLetter;
• injectArray;
• getIdFromColumnName;
• getColumnNameFromId;
• getElement;
• doubleDigitFormat;
• createFromTable;

Elements

Changes in HTML element properties:

Status	Property	Description
Removed	worksheetElement.jexcel	Use the worksheetElement.jspreadsheet property instead.