HyperFormula (v3.1.0)

# Migrating from 0.6 to 1.0

To upgrade your HyperFormula version from 0.6.x to 1.0.x, follow this guide.

# Step 1: Change your license key

If you use the AGPLv3 license, or the free non-commercial license, you need to change your license key.

If you use a commercial license, you don't need to make any changes.

# Open-source license

If you use the open-source version of HyperFormula, in your configuration options, pass the gpl-v3 string instead of the agpl-v3 string:

Before:

const options = {
  licenseKey: 'agpl-v3',
}

After:

const options = {
  // use `gpl-v3` instead of `agpl-v3`
  licenseKey: 'gpl-v3',
}

# Free non-commercial license

If you use the free non-commercial license, switch to the GPLv3 license or purchase a commercial license.

For more details on HyperFormula license keys, go here.

# Step 2: Change sheetName to sheetId

Most sheet-related methods now take the sheetID number parameter instead of the sheetName string parameter.

For example, use the clearSheet() method in this way:

Before:

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['=SUM(MySheet2!A1:A2)'] ],
 MySheet2: [ ['10'] ],
});

const changes = hfInstance.clearSheet('MySheet2');

After:

const hfInstance = HyperFormula.buildFromSheets({
 MySheet1: [ ['=SUM(MySheet2!A1:A2)'] ],
 MySheet2: [ ['10'] ],
});

// use `sheetId` instead of `sheetName`
const changes = hfInstance.clearSheet(1);

The only methods still accepting the sheetName string parameter are now:

  • addSheet(): needs sheetName to give a name to the new sheet. Generates the new sheet's sheetId
  • isItPossibleToAddSheet(): needs sheetName to check if it's possible to add a new sheet with that name
  • doesSheetExist(): needs sheetName to check if a sheet with that name exists
  • getSheetId(): needs sheetName to get the sheet's sheetId

Also, these methods still accept the newName string parameter:

  • renameSheet(): needs newName to give a new name to an existing sheet
  • isItPossibleToRenameSheet(): needs newName to check if it's possible to give that new name to an existing sheet

# Step 3: Adapt to the matrix->array name changes

Adapt to the following changes in configuration option names, API method names and exception names:

# Configuration option names

Before After
matrixColumnSeparator arrayColumnSeparator
matrixRowSeparator arrayRowSeparator

# API method names

Before After
matrixMapping arrrayMapping
isCellPartOfMatrix isCellPartOfArray

# Exception names

Before After
SourceLocationHasMatrixError SourceLocationHasArrayError
TargetLocationHasMatrixError TargetLocationHasArrayError

# Step 4: Drop the matrix formula notation

Switch from the matrix formula notation to the array formula notation.

For more information on the array formula notation, go here.

Before:

={ISEVEN(A2:A5*10)}

Now, if the useArrayArithmetic configuration option is set to false, use the ARRAYFORMULA function to enable the array arithmetic mode locally:

=ARRAYFORMULA(ISEVEN(A2:A5*10))

But when the useArrayArithmetic configuration option is set to true, you don't need to use the ARRAYFORMULA function, as the array arithmetic mode is enabled globally:

=ISEVEN(A2:A5*10)

# Step 5: Drop the matrixDetection and matrixDetectionThreshold options

Remove the matrixDetection and matrixDetectionThreshold options from your HyperFormula configuration.

Before:

// define options 
const options = {
    licenseKey: 'gpl-v3',
    matrixDetection: true,
    matrixDetectionThreshold: 150
};

After:

// define options 
const options = {
    licenseKey: 'gpl-v3'
    // remove `matrixDetection` and `matrixDetectionThreshold`
};

# Step 6: Switch to the SimpleCellRange type argument

If you use any of the following methods, update your code to take the SimpleCellRange type argument:

  • copy()
  • cut()
  • getCellDependents()
  • getCellPrecedents()
  • getFillRangeData()
  • getRangeFormulas()
  • getRangeSerialized()
  • getRangeValues()
  • isItPossibleToMoveCells()
  • isItPossibleToSetCellContents()
  • moveCells()

Before:

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
]);

// takes `simpleCellAddress`, `width`, and `height`
// returns: [ [ 2 ] ]
const clipboardContent = hfInstance.copy({ sheet: 0, col: 1, row: 0 }, 1, 1);

After:

const hfInstance = HyperFormula.buildFromArray([
 ['1', '2'],
]);

// takes `simpleCellRange`
// returns: [ [ 2 ] ]
const clipboardContent = hfInstance.copy({ start: { sheet: 0, col: 1, row: 0 }, end: { sheet: 0, col: 1, row: 0 } });

# Step 7: Adapt to the array changes

If you use any of the following methods, adjust your application to the changes in their behavior:

# setCellContents()

The setCellContents() method now can override space occupied by spilled arrays.

# addRows() and removeRows()

The addRows() method now can add rows across a spilled array, without changing the array size.

The removeRows() method now can remove rows from across a spilled array, without changing the array size.

# addColumns() and removeColumns()

The addColumns() method now can add columns across a spilled array, without changing the array size.

The removeColumns() method now can remove columns from across a spilled array, without changing the array size.

← Migrating from 1.x to 2.0 →