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 section below Export Services
2. Backend Service APIs are now decoupled and opt-in, see section below Backend Service API
3. Remove event name prefixes asg, sg (in other words asg-on-aurelia-grid-created is now on-aurelia-grid-created)
   • You can however put the prefixes back (see Grid Events)
4. CSS/SASS Styling 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.
• remove 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)

Editors

LongText Editor

You could previously add more rows to the textarea via editor: { model: Editors.longText, params: { textAreaRows }}, this is replaced by a new LongTextEditorOption interface which you can define as an editorOptions

this.columnDefinitions = [
  { 
    id: 'title', name: 'Title', field: 'title,
    editor: {
      model: Editors.longText,
-        params: {
-          textAreaRows: 7
-        },
+        editorOptions: { 
+          cols: 50, // add more cols or rows to the textarea
+          rows: 7,
+          buttonTexts: { // provide different buttons texts
+            cancel: 'Close', 
+            save: 'Done'
+          }
+        } as LongTextEditorOption,
      }
    }
  }
];

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 the following:

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

Event Naming Convention

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:

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

You could then use all lower grid event names like so

<aurelia-slickgrid grid-id="grid18"
                     column-definitions.bind="columnDefinitions"
                     grid-options.bind="gridOptions"
                     dataset.bind="dataset"
-                     on-click.delegate="handleOnClick($event.detail)">
+                     onclick.delegate="handleOnClick($event.detail)">
  </aurelia-slickgrid>

Please note that all the documentation is written with event names following the 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

• rename 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 (if you want to get this behavior then change the options 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 });
  }
}