Migration Guide 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
were already displaying some console warnings to advise you of what's being removed). So it will be easier to fix the console warnings first, then move on to the list of changes below.
Biggest Breaking Changes
Export to File & Export to Excel are now decoupled and opt-in (see Export Services)
since both exports are opt-in, they are now also both disabled by default
Backend Service APIs are now decoupled and opt-in (see Backend Service API)
Remove event name prefixes
asg
,sg
(in other wordsasg-on-aurelia-grid-created
becomeson-aurelia-grid-created
)You can however put them back, in your grid options, to avoid having to do too many refactoring (see Grid Events)
Styling (css/sass) main files are now under the
@slickgrid-universal/common
monorepo (see Stylings)
@deprecated Code (removed)
note: most of the deprecated code already sends you console warnings, so check your console first.
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 usehideColumnById
orhideColumnByIds
insteadremoved
hideColumnByIndex(idx)
please usehideColumnById
orhideColumnByIds
insteadremoved
BackendServiceOption
property namedcolumnDefinitions
, 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
or in the View (with RequireJS)
Flatpickr Localization (date picker)
If you use multiple locales, you will need to import Flatpickr Locale yourself and after Aurelia-Slickgrid is ready in your main.ts
file with WebPack or in your App template with RequireJS. The reason we now have to do this, is to avoid bundling all the Flatpickr Locales (60+) in your prod build (the previous Aurelia-Slickgrid version was actually doing just that since I found that out recently).
with WebPack
with RequireJS
Interfaces
renamed
CheckboxSelector
interface toCheckboxSelectorOption
renamed
EditorValidatorOutput
interface toEditorValidationResult
renamed
Sorter
interface toSortComparer
renamed
Sorters
toSortComparers
(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 bynameKey
(to align with SlickGridname
property when using I18N with translations)
Aurelia CLI with RequireJS
If you use RequireJS it might not autodetect properly the new Slickgrid-Universal packages (this might be fixed in the future) and so you will need to modify your aurelia-json
file to properly run.
Take a look at the config of Aurelia-Slickgrid-Demos with RequireJS aurelia.json config file.
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 are in the global grid options:
So if you wish to keep asg
and sg
prefixes, then just add them back in your grid options:
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:
But if you wish to use all lower case, you can change your grid options with
That would result in all lower case names
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:
were moved to the Grid Options in the ViewModel
Header Menu
renamed
hideFilterCommands
to singularhideFilterCommand
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
or with CSS in the index.html
file
Services
Grid Service
updateItem()
will no longer highlight the row by default (to get back this behavior add the optionhighlightRow: 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
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
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 totextExportOptions
deprecate
enableExport
flag and renamed toenableTextExport
the onBefore/onAfter events got renamed as well to
onBeforeExportToTextFile
andonAfterExportToTextFile
in the View that would equal to
on-before-export-to-text-file
andon-after-export-to-text-file
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).
Last updated