Migration to 3.x

Before you start, make sure that you don't have any console log warnings (most of the deprecated code from 2.x are already displaying console warnings to advise you of what's being removed). It will be easier to fix console warnings first, then move on to the list of changes below.

Biggest Breaking Changes

1. Export to File & Export to Excel are now decoupled and opt-in (see Export Services)
2. Backend Service APIs are now decoupled and opt-in (see Backend Service API)
3. Remove event name prefixes asg, sg (in other words asg-on-aurelia-grid-created becomes on-aurelia-grid-created)
   • You can however put the prefixes back (see Grid Events)
4. Styling (css/sass) main files are now under the @slickgrid-universal/common monorepo (see Stylings)

@deprecated Code (removed)

note: most of the deprecated code should already send you console warnings, so first check your console.

• removed all Grid Service methods having the word "toDatagrid" in their names
  • for example, addItemToDatagrid, deleteDataGridItem, ...
  • simply use the newer methods (named as addItem, deleteItemById, updateItem, ...), which have a lot more features and options.
• removed registerPlugins Grid Option since all useful plugins/controls already exist in the lib.
• removed hideColumn(column) please use hideColumnById or hideColumnByIds instead
• removed hideColumnByIndex(idx) please use hideColumnById or hideColumnByIds instead
• removed BackendServiceOption property named columnDefinitions, this is no longer a valid property which means that you cannot use it anymore with OData/GraphQL. This is no longer necessary since the Services can get the columns definition directly from the grid object.
• removed SASS variables
  • $large-editor-textarea-height
  • $large-editor-textarea-width

Changes

3rd Party Libs

The 3rd party lib named multiple-select.js is no longer included within Aurelia-Slickgrid, it is now a separate npm package named multiple-select-modified

You might have referenced this library in your main.ts or index.html, you will need to adjust the path to the library

# main.ts
- import 'aurelia-slickgrid/dist/lib/multiple-select/multiple-select.css';
- import 'aurelia-slickgrid/dist/lib/multiple-select/multiple-select.js';
+ import 'multiple-select-modified/src/multiple-select.css';
+ import 'multiple-select-modified/src/multiple-select.js';

or in the View (with RequireJS)

- <link rel="stylesheet" type="text/css" href="../node_modules/aurelia-slickgrid/dist/lib/multiple-select/multiple-select.css">
+ <link rel="stylesheet" type="text/css" href="../node_modules/multiple-select-modified/src/multiple-select.css">

Interfaces

• renamed CheckboxSelector interface to CheckboxSelectorOption
• renamed EditorValidatorOutput interface to EditorValidationResult
• renamed Sorter interface to SortComparer
• renamed Sorters to SortComparers (often used when using the Grouping feature)

Backend Service APIs

Note that the BackendServiceApi is no longer exposed in the AureliaGridInstance, so if you wish to reference it (for example when you want to use it with an external export button), then create a reference while instantiating it or get it via the grid option this.gridOptions.backendServiceApi.service

Column Definitions

• headerKey was replaced by nameKey (to align with SlickGrid name property when using I18N with translations)

Grid Events

Changed grid events prefixes Aurelia-Slickgrid (asg) and SlickGrid (sg). However please note that you can always add them back to avoid having to refactor all your grids at once, the main changes is in the global grid options:

export const GlobalGridOptions: Partial<GridOption> = {
-  defaultAureliaEventPrefix: 'asg',
-  defaultSlickgridEventPrefix: 'sg',
+  defaultAureliaEventPrefix: '',
+  defaultSlickgridEventPrefix: '',
+  eventNamingStyle: EventNamingStyle.kebabCase,
}

So if you wish to keep asg and sg prefixes, then just add back the following in your grid options:

this.gridOptions = {
  defaultAureliaEventPrefix: 'asg',
  defaultSlickgridEventPrefix: 'sg',
  // ...
}

Event Naming Convention (defaults to kebab case)

You might have notice the eventNamingStyle grid option, it is indeed a new option and with it you can change the names of the events following a defined naming convention. The default is kebab case (separated by hyphens) but you could also use the lower case option (which is an acceptable ES6 syntax), if you take that for example that would become:

So the default is kebab case event naming:

<aurelia-slickgrid on-click.delegate="handleOnClick($event.detail)">

But if you wish to use all lower case, you can do change the grid option

this.gridOptions {
+  eventNamingStyle: EventNamingStyle.lowerCase,
}

That would result in all lower case names

<aurelia-slickgrid 
-  on-click.delegate="handleOnClick($event.detail)">
+  onclick.delegate="handleOnClick($event.detail)">

Again note that all the documentation is written with event names following the default kebab case format (on-click).

Grid Options

• Grid Height/Width should now be passed through the Grid Options instead of the View, for example:

<aurelia-slickgrid grid-id="grid1" column-definitions.bind="columnDefinitions" grid-options.bind="gridOptions" dataset.bind="dataset"
-                   grid-height="225"
-                   grid-width="800">
</aurelia-slickgrid>

was moved to the Grid Options in the ViewModel

this.gridOptions = {
+   gridHeight: 225,
+   gridWidth: 800
};

Header Menu

• renamed hideFilterCommands to singular hideFilterCommand since there can only be 1 filter per column

Stylings

The CSS/SASS Stylings now come from the @slickgrid-universal/common monorepo package, you need to adjust your imports

# with CSS (main.ts)
- import 'aurelia-slickgrid/dist/styles/css/slickgrid-theme-bootstrap.css';
+ import '@slickgrid-universal/common/dist/styles/css/slickgrid-theme-bootstrap.css';

# with SASS 
- @import 'aurelia-slickgrid/dist/styles/sass/slickgrid-theme-bootstrap.scss';
+ @import '@slickgrid-universal/common/dist/styles/sass/slickgrid-theme-bootstrap.scss';

Services

Grid Service

• updateItem() will no longer highlight the row by default (to get back this behavior back just pass the option highlightRow: true)

OData Service

The GridOdataService is now an opt-in Service and is no longer exposed in the AureliaGridInstance, you need create a reference while instantiating it or get it via the grid option this.gridOptions.backendServiceApi.service

- import { GridOdataService, OdataServiceApi, OdataOption } from 'aurelia-slickgrid';
+ import { GridOdataService, OdataServiceApi, OdataOption } from '@slickgrid-universal/odata';

export class MyExample {
  prepareGrid {
    this.columnDefinitions = [ /*...*/ ];
    this.gridOptions = {
      backendServiceApi: {
        service: new GridOdataService(),
        options: { /*...*/ } as OdataServiceApi
    }
  }
}

GraphQL Service

The GraphqlService is now an opt-in Service and is no longer exposed in the AureliaGridInstance, you need create a reference while instantiating it or get it via the grid option this.gridOptions.backendServiceApi.service

- import { GraphqlService, GraphqlPaginatedResult, GraphqlServiceApi, } from 'aurelia-slickgrid';
+ import { GraphqlService, GraphqlPaginatedResult, GraphqlServiceApi, } from '@slickgrid-universal/graphql';

export class MyExample {
  prepareGrid {
    this.columnDefinitions = [ /*...*/ ];
    this.gridOptions = {
      backendServiceApi: {
        service: new GraphqlService(),
        options: { /*...*/ } as GraphqlServiceApi
    }
  }
}

Export Services

Text File Export Service

Export Service was renamed to TextExportService (export extensions are .txt, .csv) and is now an opt-in Servicem it is also no longer exposed in the AureliaGridInstance. You need to use the new @slickgrid-universal/text-export packages and register the service(s) in your grid options as shown below.

Also note that Text Export Service grid options changed as well, a few options got deprecated and renamed to have the word "textExport" instead of just "export". Also to be clear, it's deprecated but still exist, this will give you time to refactor your code. Here's the list

• deprecate exportOptions and renamed to textExportOptions
• deprecate enableExport flag and renamed to enableTextExport
• the onBefore/onAfter events got renamed as well to onBeforeExportToTextFile and onAfterExportToTextFile
  • in the View that would equal to asg-on-before-export-to-text-file and asg-on-after-export-to-text-file

import { Column, GridOption } from 'aurelia-slickgrid';
+ import { ExcelExportService } from '@slickgrid-universal/excel-export';
+ import { TextExportService } from '@slickgrid-universal/text-export';

export class MyExample {
  prepareGrid {
    this.columnDefinitions = [ /*...*/ ];
    this.gridOptions = {
      enableExcelExport: true,
      excelExportOptions: { sanitizeDataExport: true },
-      enableExport: true,
-      exportOptions: { sanitizeDataExport: true },
+      enableTextExport: true,
+      textExportOptions: { sanitizeDataExport: true },

       // add 2x Export Services (you can add a single or both export services, it should always be an array
+      registerExternalServices: [new ExcelExportService(), new TextExportService()], 
    }
  }
}

Excel Export Service

The ExcelExportService is also an opt-in Service and is no longer exposed in the AureliaGridInstance, so if you wish to reference it (for example when you want to use it with an external export button), then create a reference while instantiating it (the excelExportOptions are the same as before).

import { Column, GridOption } from 'aurelia-slickgrid';
+ import { ExcelExportService } from '@slickgrid-universal/excel-export';

export class MyExample {
+  excelExportService = new ExcelExportService(); // create a variable ref when you need to access it later

  prepareGrid {
    this.columnDefinitions = [ /*...*/ ];
    this.gridOptions = {
      enableExcelExport: true,
      excelExportOptions: { sanitizeDataExport: true },
+      registerExternalServices: [this.excelExportService],
    }
  }

  exportToExcel() {
-    this.aureliaGrid.excelExportService.exportToExcel({ filename: 'Export', format: FileType.xlsx });
+    this.excelExportService.exportToExcel({ filename: 'export', format: FileType.xlsx });
  }
}