Skip to content

Migration to 5.x

Jump to bottom
Ghislain B edited this page Apr 30, 2024 · 24 revisions

Version 5 - Better UI and Dark Mode with Pure CSS SVG icons

This new release brings a lot of changes oriented towards better UI/UX, our SVG icons are now pure CSS and can be colorized like any other text via the native CSS color property (which helps a lot improving the Dark Mode Theme).

Another noticeable UI change is the migration from Flatpickr to Vanilla-Calendar-Picker (which is in fact a fork of Vanilla-Calendar-Pro and we'll hopefully drop the fork in the near future if possible), there are multiple reasons to migrate our date picker to another library:

  • Flatpickr cons:
    • barely supported (lots of opened PR but nothing merged for the past 2 years)
    • not fully ESM ready (it's only partially ESM, for example it is detected as CJS in Angular-Slickgrid and requires to be added to allowedCommonJsDependencies)
    • styling could be a bit more modern (the use of native select/input to change year/month/time is a bit outdated and rudimentary)
    • date range selection is not very user friendly (UX)
  • Vanilla-Calendar pros:
    • ESM ready
    • modern styling and also include Dark Mode theme
    • date range becomes a lot more easy by displaying a picker with 2 months
  • Vanilla-Calendar cons:
    • build size is slightly larger but its UI/UX is awesome
    • settings are named differently and are not using flat config (complex object settings)
      • for example Flatpickr minDate: 'today' is instead range: { min: 'today' }
    • some settings were missing, like the 'today' shortcut which is why I forked the project
      • I did open a few PRs on the main project, so the hope is to drop the fork in the future while being a totally transparent change to you when it happens.

With this release, I believe that I have achieved all goals and even more than I originally expected to accomplish (I'm not expecting to roll new major releases as often anymore). The recent goals was to improve UI/UX but also make it full ESM ready and this release is improving on that goal. Also, at this point, the project has a smaller size in comparison to what it was in v2.x (that is when the user had to install jQuery/jQueryUI separately). So, considering that we're no longer using jQuery/jQueryUI in the project, and also considering that these 2 dependencies were well over a total of 200Kb, then our project build size is in fact a lot smaller than it was 2 years ago in v2.x. This is really nice to see especially since we keep adding features (like Dark Mode and others) while still maintainging or slightly decreasing its size :)

Major Changes - Quick Summary

  • minimum requirements bump
    • Node 18 is required
    • Bootstrap 5 or higher (or any other UI framework)
    • SASS 1.35 or higher (dart-sass)
    • migrated from Flatpickr to Vanilla-Calendar (visit Vanilla-Calendar-Pro for demos and docs)

Note for the entire list of tasks & code changes applied in this release, you may want to take a look at the Roadmap to 5.0 Discussion.

NOTE: if you come from an earlier version, please make sure to follow each migrations in their respected order (review previous migration guides)

Changes

Styling

CSS classes .color-xx are all removed (use .text-color-xx or native color instead)

Note these extra colors are only available in the Material and Salesforce Themes (not in the Bootstrap Theme since Bootstrap has its own coloring utils).

Since the SVG icons are now pure CSS, we can now colorize any of them the same way that we would do for any other text via the color CSS property. For that reason, we no longer need any of the .color-xx CSS classes (which were created via CSS filter). They were useful to override the SVG icon colors, but since we can now use the regular color property, the color-xx are no longer necessary and are all removed (just use text-color-xx instead or use plain colors).

<button class="button is-small">
- <span class="icon"><i class="mdi mdi-undo color-primary"></i></span>
+ <span class="icon"><i class="mdi mdi-undo text-color-primary"></i></span>
  <span class="text-color-primary">Undo Last Edit</span>
</button>

or move the class to the parent container and have both the icon & the text inherit the color :)

+ <button class="button is-small text-color-primary">
- <span class="icon"><i class="mdi mdi-undo color-primary"></i></span>
+ <span class="icon"><i class="mdi mdi-undo"></i></span>
- <span class="text-color-primary">Undo Last Edit</span>
</button>

SASS variables

A lot of SASS variables were changed, we recommend that you take a look at the _variables.scss file to compare them with yours SASS overrides and fix any SASS build issues. For example a lot of the ms-select variables and all Flatpickr related variables were deleted. Also a lot of the icon related variables got updated (icons now have the suffix -icon-svg-path for the SVG vector path). If you want create your own SVGs in pure CSS, you can use the generateSvgStyle() function from our sass-utilities.scss (take a look at the slickgrid-icons.scss on its usage)

SASS (dart-sass) math polyfills are removed

When Dart-SASS released their version 1.33, it caused a lot of console warnings (and lot of unhappy users) in projects that were using / in their SASS files (for math division) instead of their new math.div function. To avoid seeing all these warnings, I added a temporary polyfill at the time (that piece of code was actually copied from the Bootstrap project). This change happened 3 years ago, so I'm assuming that most users have already upgraded their SASS version and already fixed all of these warnings. So, I think it's time to remove this polyfill because it was always meant to be a temp patch. If you see these warnings coming back, you can use the SASS option --quiet-upstream.

For reference, below is an example of these old Math warnings when we used to compile it with SASS CLI

Recommendation: math.div($m, $columns)
More info and automated migrator: https://sass-lang.com/d/slash-div
╷
94 │ margin-right: $m / $columns * 100%
│ ^^^^^^^^^^^^^^^^^^

No more Font-Awesome references

Since this release now has pure CSS SVG icons, I decided to delete any Font-Awesome references (mostly in the Bootstrap Theme) because all the built-in icons are now all SVG icons (sort, grouping, row detail, row move, row selection) (you can change them using SASS). However, there are a few plugins that use external icons via CSS classes (mostly all menu plugins like Header Menu, Grid Menu, Content Menu, ...) and for that reason all Styling Themes now include default SVG icons (even the Bootstrap Theme).

If you no longer need Font-Awesome, then consider removing it completely

# package.json
{
  dependencies: {
-   "font-awesome": "^4.7.0"
  }
}

What if you don't want to use the Slickgrid-Universal icons subset and want to use a different font/SVG library? In that case, it's suggested to use the "lite" Theme(s) and then make sure to update all the menu plugins with the correct CSS classes, for example the global grid options of the Grid Menu is now configured with the following (notice that we no longer provide any Font-Awesome "fa" icon references in our global grid options):

// default global grid options
export const GlobalGridOptions = {
  gridMenu: {
    iconCssClass: 'mdi mdi-menu',
    iconClearAllFiltersCommand: 'mdi mdi-filter-remove-outline',
    iconClearAllSortingCommand: 'mdi mdi-sort-variant-off',
    iconClearFrozenColumnsCommand: 'mdi mdi-pin-off-outline',
    iconExportCsvCommand: 'mdi mdi-download',
    iconExportExcelCommand: 'mdi mdi-file-excel-outline',
    iconExportTextDelimitedCommand: 'mdi mdi-download',
    iconRefreshDatasetCommand: 'mdi mdi-sync',
    iconToggleDarkModeCommand: 'mdi mdi-brightness-4',
    iconToggleFilterCommand: 'mdi mdi-flip-vertical',
    iconTogglePreHeaderCommand: 'mdi mdi-flip-vertical',
  }
}

and here's the file size difference with the "lite" version

image

jQueryUI CSS class leftovers

We had a few .ui-state-default and other jQueryUI CSS classes leftovers in the core lib, they were all removed in this release. If you were querying any of them for styling purposes, you can simply rename them to .slick-state-*

- .ui-state-default, .ui-state-hover {
+ .slick-state-default, .slick-state-hover {
}

Deprecated code removed/renamed

getHTMLFromFragment() removed

The function getHTMLFromFragment() was removed in favor of getHtmlStringOutput(), the new function will auto-detect if it's a DocumentFragment, an HTMLElement or an HTML string and will execute the appropriate action.

Formatters Cleanup & Removals

Since we now only use SVG and we got rid of any Font usage (no more Font-Awesome code anywhere), the checkmark Formatter no longer has any reason to exist and was removed. If you were using and still use Font-Awesome in your project, you'll have to either recreate the Formatter yourself or use alternatives. You could use the Formatters.icon or Formatters.iconBoolean which require the CSS classes to be provided via params. As a last alternative, and if you are importing the optional SVG icons .mdi, then we recommend you simply use the checkmarkMaterial Formatter.

this.columnDefinitions = [
  {
    id: 'isActive', name: 'Active', field: 'isActive',
-   formatter: Formatters.checkmark
+   formatter: Formatters.checkmarkMaterial
  },
];

or create a Custom Formatter

// create a custom Formatter and returning a string and/or an object of type FormatterResultObject
const myCheckmarkFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any) => {
  const iconElm = document.createElement('i');
  iconElm.className = value ? 'mdi mdi-check' : '';
  return iconElm;

  // simple HTML string
  return value ? '<i class="mdi mdi-check"></i>' : '';
}

Grid Functionalities

Native Select Filter (removed)

I would be surprised if anyone uses the Filters.select and so it was removed, you should simply use the Filters.singleSelect or Filters.multipleSelect

prepareGrid() {
  this.columnDefinitions = [{
    id: 'isActive', name: 'Active', field: 'isActive',
    filter: {
-      model: Filters.select,
+      model: Filters.singleSelect,
       collection: [ { value: '', label: '' }, { value: true, label: 'true' }, { value: false, label: 'false' } ],
    }
  }];
}

Date Editor/Filter

We migrated from Flatpicker to Vanilla-Calendar and this require some changes since the option names are different. The changes are the same for both the Filter and the Editor.

The biggest change that you will have to do is the min/max date setting when using the 'today' shortcut as shown below:

- import { type FlatpickrOption } from '@slickgrid-universal/common';
+ import { type VanillaCalendarOption } from '@slickgrid-universal/common';

prepareGrid() {
  this.columnDefinitions = [{
    id: 'finish', name: 'Finish', field: 'finish',
    editor: {
      model: Editors.date,
-      editorOptions: { minDate: 'today' } as FlatpickrOption,
+      editorOptions: { range: { min: 'today' } } as VanillaCalendarOption,
    }
  }];
}

Note the 'today' shortcut currently only exist in Vanilla-Calendar-Picker fork, however the rest of the settings should be similar, visit Vanilla-Calendar-Pro settings website for all other options. The hope is to drop the fork whenever the original project receives all missing features.

Multiple-Select

Please note that in previous version we were simply re-exporting the MultipleSelectOption interface from the Multiple-Select-Vanilla library for convenience, however re-exporting is typically discouraged by the TypeScript team and so it was removed in this release. The change is quite simple, you simply need to import the MultipleSelectOption interface from the multiple-select-vanilla external library.

- import { MultipleSelectOption } from '@slickgrid-universal/common';
+ import { MultipleSelectOption } from 'multiple-select-vanilla';

prepareGrid() {
  this.columnDefinitions = [{
    id: 'isActive', name: 'Active', field: 'isActive',
    editor: {
      model: Editors.singleSelect,
      collection: [ { value: '', label: '' }, { value: true, label: 'true' }, { value: false, label: 'false' } ],
      editorOptions: { maxHeight: 400 } as MultipleSelectOption
    }
  }];
}
Clone this wiki locally