angular-slickgrid 8.14.0 → 9.0.0

package/docs/grid-functionalities/frozen-columns-rows.md

@@ -0,0 +1,164 @@
+#### Index
+- [Columns/Rows Pinning Basic](#columnsrows-pinning-basic)
+- [Rows Pinning starting from Bottom](#rows-pinning-starting-from-bottom)
+- [Change Pinning Dynamically](#change-pinning-dynamically)
+- [Animated Gif Demo](#animated-gif-demo)
+
+### Demo
+[Demo Page](https://ghiscoding.github.io/angular-slickgrid-bs4-demo/#/frozen) / [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-frozen.component.ts)
+
+### Introduction
+One of the requested features, columns or rows pinning (aka frozen). You can pin 1 or more Columns and/or 1 or more Rows. Columns can only be pinned starting from the left side, while Rows can be pinned starting from the Top (default) or Bottom. You can also change the pinning dynamically with `setOptions()`.
+
+## Columns/Rows Pinning basic
+To set a pinning for the entire duration of the grid, simply use the Grid Options `frozenColumn` (starting from top) and `frozenRow` (starting from left), which are both `number` types.
+
+```html
+<angular-slickgrid gridId="grid2"
+     [columns]="columnDefinitions"
+     [options]="gridOptions"
+     [dataset]="dataset">
+</angular-slickgrid>
+```
+
+##### Component
+```typescript
+import { Component, OnInit} from '@angular/core';
+
+export class GridBasicComponent implements OnInit {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  ngOnInit(): void {
+      // your columns definition
+    this.columnDefinitions = [];
+
+    this.gridOptions = {
+      alwaysShowVerticalScroll: false, // disable scroll since we don't want it to show on the left pinned columns
+      frozenColumn: 2, // number of pinned columns starting from the left
+      frozenRow: 3,    // number of pinned columns starting from the top
+    }
+  }
+}
+```
+
+## Rows Pinning starting from bottom
+This is basically the same thing as previous code sample, except that you will set the Grid Option property `frozenBottom` to true and that it's.
+##### Component
+```ts
+import { Component, OnInit} from '@angular/core';
+
+export class GridBasicComponent implements OnInit {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  ngOnInit(): void {
+      // your columns definition
+    this.columnDefinitions = [];
+
+    this.gridOptions = {
+      alwaysShowVerticalScroll: false, // disable scroll since we don't want it to show on the left pinned columns
+      frozenColumn: 2,    // number of pinned columns starting from the left
+      frozenRow: 3,       // number of pinned columns (starting from bottom with next property)
+      frozenBottom: true, // this will make rows to be pinned starting from the bottom and the number of rows will be 3
+    }
+  }
+}
+```
+
+## Change Pinning Dynamically
+You can change the number of pinned columns/rows and even the pinning of columns from top to bottom. For a demo of what that could look like, take a look at the [Animated Gif Demo](#animated-gif-demo) below.
+
+```html
+<div class="row col-sm-12">
+    <span>
+        <label for="">Pinned Rows: </label>
+        <input type="number" [(ngModel)]="frozenRowCount">
+        <button class="btn btn-default btn-xs" (click)="changeFrozenRowCount()">
+            Set
+        </button>
+    </span>
+    <span style="margin-left: 10px">
+        <label for="">Pinned Columns: </label>
+        <input type="number" [(ngModel)]="frozenColumnCount">
+        <button class="btn btn-default btn-xs" (click)="changeFrozenColumnCount()">
+            Set
+        </button>
+    </span>
+    <span style="margin-left: 15px">
+        <button class="btn btn-default btn-sm" (click)="toggleFrozenBottomRows()">
+            <i class="mdi mdi-flip-vertical"></i> Toggle Pinned Rows
+        </button>
+        <span style="font-weight: bold;">: {{ isFrozenBottom ? 'Bottom' : 'Top' }}</span>
+    </span>
+</div>
+
+<angular-slickgrid gridId="grid2"
+     [columns]="columnDefinitions"
+     [options]="gridOptions"
+     [dataset]="dataset"
+     (onAngularGridCreated)="angularGridReady($event.detail)">
+</angular-slickgrid>
+```
+
+##### Component
+```ts
+import { Component, OnInit} from '@angular/core';
+import { AngularGridInstance } from 'angular-slickgrid';
+
+export class GridBasicComponent implements OnInit {
+  columnDefinitions: Column[];
+  dataset: any[];
+  gridOptions: GridOption;
+  gridObj: any;
+  isFrozenBottom = false;
+
+  ngOnInit(): void {
+      // your columns definition
+    this.columnDefinitions = [];
+
+    this.gridOptions = {
+      alwaysShowVerticalScroll: false, // disable scroll since we don't want it to show on the left pinned columns
+      frozenColumn: 2, // number of pinned columns starting from the left
+      frozenRow: 3,    // number of pinned columns starting from the top
+    }
+  }
+
+  angularGridReady(angularGrid: AngularGridInstance) {
+    this.gridObj = angularGrid.slickGrid;
+  }
+
+  /** change dynamically, through slickgrid "setOptions()" the number of pinned columns */
+  changeFrozenColumnCount() {
+    if (this.gridObj && this.gridObj.setOptions) {
+      this.gridObj.setOptions({
+        frozenColumn: this.frozenColumnCount
+      });
+    }
+  }
+
+  /** change dynamically, through slickgrid "setOptions()" the number of pinned rows */
+  changeFrozenRowCount() {
+    if (this.gridObj && this.gridObj.setOptions) {
+      this.gridObj.setOptions({
+        frozenRow: this.frozenRowCount
+      });
+    }
+  }
+
+  /** toggle dynamically, through slickgrid "setOptions()" the top/bottom pinned location */
+  toggleFrozenBottomRows() {
+    if (this.gridObj && this.gridObj.setOptions) {
+      this.gridObj.setOptions({
+        frozenBottom: !this.isFrozenBottom
+      });
+      this.isFrozenBottom = !this.isFrozenBottom; // toggle the variable
+    }
+  }
+}
+```
+
+## Animated Gif Demo
+![](https://user-images.githubusercontent.com/643976/50852303-28d57c80-134d-11e9-859c-aeb55af24c24.gif)

package/docs/grid-functionalities/grouping-and-aggregators.md

@@ -0,0 +1,269 @@
+#### index
+- [Demo](#demo)
+- [Description](#description)
+- [Setup](#setup)
+- [Draggable Dropzone Location](#draggable-dropzone-location)
+- [Aggregators](#aggregators)
+- [SortComparers](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/sortComparers/sortComparers.index.ts)
+- [GroupTotalsFormatter](#group-totals-formatter)
+- [Custom GroupTotalsFormatter](#custom-grouptotalsformatter)
+- [Set a Grouping](#set-a-grouping)
+- [Clear Grouping / Collapse All / Expand All](#clear-grouping--collapse-all--expand-all)
+- [Styling - Change Icons](#styling-change-icons)
+
+## Demo
+##### Regular Grouping
+[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/grouping) / [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-grouping.component.ts)
+
+##### Draggable Grouping
+[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/draggrouping) / [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-draggrouping.component.ts)
+
+### Description
+Fully dynamic and interactive multi-level grouping with filtering and aggregates that is achieved with the help of the `DataView` object in `SlickGrid`. Each grouping level can have its own aggregates (over child rows, child groups, or all descendant rows). An aggregate can be seen as sub-totals, totals, average, ... or any defined group(s).
+
+How does it work in `SlickGrid`?
+The important thing to understand while working with `SlickGrid` is that Grouping requires you to provide 2 things, if you omit 1 of them, it will simply not work. These 2 things are
+1. You will need to define which type of aggregate (accumulator) you want to use
+   - Angular-Slickgrid provides the following built-in `Aggregators`: `Avg`, `Min`, `Max`, `Sum`
+2. You need to add a `groupTotalsFormatter` on the column definition you want it to be calculated
+   - this is very similar to a Formatter, except that they are designed to show aggregate results, e.g:: `Total: 142.50$`
+
+These 2 steps go hands in hands, a `groupTotalsFormatter` would have nothing to show if it does not have an `Aggregator`.
+
+### Setup
+One of the very first thing that you need to do is to provide the `SlickGrid DataView` object to your `ViewModel`. The `DataView` is where we will define all of our Grouping. You can get the `dataView` object through an Event Emitter `onDataviewCreated` like so:
+
+##### View
+```html
+<angular-slickgrid
+    gridId="grid2"
+    [columns]="columnDefinitions"
+    [options]="gridOptions"
+    [dataset]="dataset"
+    (onAngularGridCreated)="angularGridReady($event.detail)">
+</angular-slickgrid>
+```
+##### Component
+
+```typescript
+
+@Component({
+  templateUrl: './grid-grouping.component.html'
+})
+export class GridGroupingComponent implements OnInit, OnDestroy {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataviewObj: any;
+
+  angularGridReady(angularGrid: AngularGridInstance) {
+    this.angularGrid = angularGrid;
+    this.gridObj = angularGrid.slickGrid;
+    this.dataViewObj = angularGrid.dataView;
+  }
+}
+```
+
+### Draggable Dropzone Location
+
+The Draggable Grouping can be located in either the Top-Header or the Pre-Header as described below.
+
+#### Pre-Heaader
+Draggable Grouping can be located in either the Pre-Header of the Top-Header, however when it is located in the Pre-Header then the Header Grouping will not be available (because both of them would conflict with each other). Note that prior to the version 8.1 of Angular-Slickgrid, the Pre-Header was the default and only available option.
+
+```ts
+this.gridOptions = {
+  createPreHeaderPanel: true,
+  showPreHeaderPanel: true,
+  preHeaderPanelHeight: 26,
+  draggableGrouping: {
+    // ... any draggable plugin option
+  },
+}
+```
+
+#### Top-Heaader
+##### requires v8.1 and higher
+This is the preferred section since the Top-Header is on top of all headers (including pre-header) and it will always be the full grid width. Using the Top-Header also frees up the Pre-Header section for the potential use of Header Grouping.
+
+When using Draggable Grouping and Header Grouping together, you need to enable both top-header and pre-header.
+```ts
+this.gridOptions = {
+    // we'll use top-header for the Draggable Grouping
+  createTopHeaderPanel: true,
+  showTopHeaderPanel: true,
+  topHeaderPanelHeight: 35,
+
+  // pre-header will include our Header Grouping (i.e. "Common Factor")
+  createPreHeaderPanel: true,
+  showPreHeaderPanel: true,
+  preHeaderPanelHeight: 26,
+}
+```
+
+### Aggregators
+The `Aggregators` is basically the accumulator, the logic that will do the sum (or any other aggregate we defined). We simply need to instantiate the `Aggregator` by passing the column definition `field` that will be used to accumulate. For example, if we have a column definition of Cost and we want to calculate it's sum, we can call the `Aggregator` as follow
+```ts
+new Aggregators.Sum('cost')
+```
+The available built-in `Aggregators` are
+- `Aggregators.Avg` (calculate the Average of a group)
+- `Aggregators.Min` (returns the Minimum value of a group)
+- `Aggregators.Max` (returns the Maximum value of a group)
+- `Aggregators.Sum` (calculate the Sum of a group)
+- `Aggregators.Clone` (will clone the same grouped text and display it in as an aggregated value)
+- `Aggregators.Distinct` (will show distinct value)
+
+### Group Totals Formatter
+When defining your column definitions, you will need to decide which of the column will have an aggregate. Once that decision is made, you will add a `groupTotalsFormatter` to that column definition in question (a Formatter for the group total). For example, let say that we have a cost and we want a total sum grouped by a duration, the code would look like below.
+
+##### Available Group Total Formatters
+You can see the full list under [`groupingFormatters.index.ts`](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/grouping-formatters/groupingFormatters.index.ts)
+Note: the Group Total Formatters named as currency will have these extra `params` (`groupFormatterPrefix`, `groupFormatterSuffix`, `groupFormatterCurrencyPrefix`, `groupFormatterCurrencySuffix`) and also the other common Formatter `params` (`minDecimal`, `maxDecimal`, `decimalSeparator`, `thousandSeparator`, `displayNegativeNumberWithParentheses`).
+
+- `avgTotalsPercentageFormatter`
+- `avgTotalsDollarFormatter`
+- `avgTotalsCurrencyFormatter`
+- `avgTotalsFormatter`
+- `minTotalsFormatter`
+- `maxTotalsFormatter`
+- `sumTotalsColoredFormatter`
+- `sumTotalsCurrencyFormatter`
+- `sumTotalsCurrencyColoredFormatter`
+- `sumTotalsDollarColoredBoldFormatter`
+- `sumTotalsDollarColoredFormatter`
+- `sumTotalsDollarBoldFormatter`
+- `sumTotalsDollarFormatter`
+- `sumTotalsFormatter`
+- `sumTotalsBoldFormatter`
+
+##### ViewModel
+```typescript
+export class GridGroupingComponent implements OnInit, OnDestroy {
+  this.columnDefinitions = [
+      {
+        id: 'title', name: 'Title', field: 'title'
+      },
+      {
+        id: 'duration', name: 'Duration', field: 'duration',
+        type: 'number',
+        groupTotalsFormatter: GroupTotalFormatters.sumTotals,
+        params: { groupFormatterPrefix: 'Total: ' }
+      },
+      {
+        id: 'cost', name: 'Cost', field: 'cost',
+        exportWithFormatter: true,    // for a Dollar Formatter, we also want it to be displayed in the export to file
+        formatter: Formatters.dollar,
+        groupTotalsFormatter: GroupTotalFormatters.sumTotalsDollar,
+        params: { groupFormatterPrefix: '<b>Total</b>: ' /*, groupFormatterSuffix: ' USD'*/ }
+      }
+  ];
+
+    this.gridOptions = {
+      enableGrouping: true,        // don't forget to enable the grouping
+      exportOptions: {
+        sanitizeDataExport: true   // you can also sanitize the exported data (it will remove any HTML tags)
+      }
+    };
+}
+```
+
+#### Prefix/Suffix to a `groupTotalsFormatter`
+We can also pass prefix and/or suffix to each `groupTotalsFormatter` by adding them to the `params` object. Also note that you can also type HTML to be interpreted. For example, let say we would like `Total:` to show as bold and a suffix of 'USD' , you can write it this way:
+
+**Note** prefix/suffix are concatenated without spaces, if you require a space then make sure to add it in accordingly.
+
+##### ViewModel
+```ts
+{
+  id: 'cost', name: 'Cost', field: 'cost',
+  groupTotalsFormatter: GroupTotalFormatters.sumTotalsDollar,
+  params: { groupFormatterPrefix: '<b>Total</b>: ', groupFormatterSuffix: ' USD' }
+}
+```
+
+### Custom `groupTotalsFormatter`
+You can also create a custom `groupTotalsFormatter` similarly to a Formatter, just a create a function that will return a string, for example:
+
+##### ViewModel
+```typescript
+defineGrid() {
+  this.columnDefinitions = [
+      {
+        id: 'cost', name: 'Cost', field: 'cost',
+        groupTotalsFormatter: this.sumTotalsFormatter
+      }
+  ];
+}
+
+sumTotalsFormatter(totals, columnDef) {
+  const val = totals.sum && totals.sum[columnDef.field];
+  if (val != null) {
+    return 'total: ' + ((Math.round(parseFloat(val) * 100) / 100));
+  }
+  return '';
+}
+```
+
+### Set a Grouping
+Once you have added a `groupTotalsFormatter` and defined which aggregate you want to use, you will want to create a grouping function. If we take again our example of a grid with multiple task and we want to group our task by duration and calculate the duration average and the cost total sum, we can write the following function
+
+##### ViewModel
+```ts
+groupByDuration() {
+    this.dataviewObj.setGrouping({
+      getter: 'duration',  // the column `field` to group by
+      formatter: (g) => {
+        // (required) what will be displayed on top of each group
+        return `Duration:  ${g.value} <span style="color:green">(${g.count} items)</span>`;
+      },
+      comparer: (a, b) => {
+        // (optional) comparer is helpful to sort the grouped data
+        // code below will sort the grouped value in ascending order
+        return SortComparers.numeric(a.value, b.value, SortDirectionNumber.asc);
+      },
+      aggregators: [
+        // (optional), what aggregators (accumulator) to use and on which field to do so
+        new Aggregators.Avg('percentComplete'),
+        new Aggregators.Sum('cost')
+      ],
+      aggregateCollapsed: false,  // (optional), do we want our aggregator to be collapsed?
+      lazyTotalsCalculation: true // (optional), do we want to lazily calculate the totals? True is commonly used
+    });
+  }
+```
+
+### Clear Grouping / Collapse All / Expand All
+To "Clear all Grouping", "Collapse all Groups" and "Expand all Groups", we can simply call the associated `DataView` function, like so:
+
+##### ViewModel
+```ts
+  clearGrouping() {
+    this.dataviewObj.setGrouping([]);
+  }
+
+  collapseAllGroups() {
+    this.dataviewObj.collapseAllGroups();
+  }
+
+  expandAllGroups() {
+    this.dataviewObj.expandAllGroups();
+  }
+```
+
+### Styling (change icons)
+The current icons are chevron (right/down), however if you wish to use +/- icons. You can simply update the SASS variables to use whichever SVG icon paths. The SASS variables you can change are
+```css
+$slick-icon-group-color:                    $primary-color;
+$slick-icon-group-expanded-svg-path:        "M19,19V5H5V19H19M19,3A2,2 0 0,1 21,5V19A2,2 0 0,1 19,21H5A2,2 0 0,1 3,19V5C3,3.89 3.9,3 5,3H19M11,7H13V11H17V13H13V17H11V13H7V11H11V7Z";
+$slick-icon-group-collapsed-svg-path:       "M19,19V5H5V19H19M19,3A2,2 0 0,1 21,5V19A2,2 0 0,1 19,21H5A2,2 0 0,1 3,19V5C3,3.89 3.9,3 5,3H19M17,11V13H7V11H17Z";
+$slick-icon-group-font-size:                20px;
+$slick-icon-group-font-weight:              bold;
+$slick-icon-group-margin-right:             2px;
+
+/* Grouping Totals Formatter */
+$slick-group-totals-formatter-color:        gray;
+$slick-group-totals-formatter-bgcolor:      white;
+$slick-group-totals-formatter-font-size:    14px;
+```
+
+For more info on SASS styling and variables, please read the [Wiki - SASS Styling](../styling/styling.md),

package/docs/grid-functionalities/header-footer-slots.md

@@ -0,0 +1,22 @@
+### Description
+You can add Header and/or Footer to your grid by using `ng-template` within your `angular-slickgrid` component, it's as simple as that. Using these slots also has the advantage of being contained in the same container making them the same width as the grid container.
+
+### Demo
+
+[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/header-footer) / [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-header-footer.component.ts)
+
+### Basic Usage
+
+##### Component
+
+```html
+<angular-slickgrid gridId="grid1" [columns]="columnDefinitions" [options]="gridOptions" [dataset]="dataset">
+  <ng-template #slickgridHeader>
+    <h3>Grid with header and footer slot</h3>
+  </ng-template>
+
+  <ng-template #slickgridFooter>
+    <custom-footer></custom-footer>
+  </ng-template>
+</angular-slickgrid>
+```

package/docs/grid-functionalities/infinite-scroll.md

@@ -0,0 +1,150 @@
+## Description
+
+Infinite scrolling allows the grid to lazy-load rows from the server (or locally) when reaching the scroll bottom (end) position.
+In its simplest form, the more the user scrolls down, the more rows will get loaded and appended to the in-memory dataset.
+
+### Demo
+[JSON Data - Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/infinite-json) / [Demo ViewModel](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-infinite-json.component.ts)
+
+[OData Backend Service - Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/infinite-odata) / [Demo ViewModel](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-infinite-odata.component.ts)
+
+[GraphQL Backend Service - Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/infinite-graphql) / [Demo ViewModel](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-infinite-graphql.component.ts)
+
+> ![WARNING]
+> Pagination Grid Preset (`presets.pagination`) is **not** supported with Infinite Scroll
+
+## Infinite Scroll with JSON data
+
+As describe above, when used with a local JSON dataset, it will add data to the in-memory dataset whenever we scroll to the bottom until we reach the end of the dataset (if ever).
+
+#### Code Sample
+When used with a local JSON dataset, the Infinite Scroll is a feature that must be implemented by yourself. You implement by subscribing to 1 main event (`onScroll`) and if you want to reset the data when Sorting then you'll also need to subscribe to the (`onSort`) event. So the idea is to have simple code in the `onScroll` event to detect when we reach the scroll end  and then use the DataView `addItems()` to append data to the existing dataset (in-memory) and that's about it.
+
+##### View
+```html
+<angular-slickgrid
+     gridId="grid2"
+     [columns]="columnDefinitions"
+     [options]="gridOptions"
+     [dataset]="dataset"
+     (onAngularGridCreated)="angularGridReady($event.detail)"
+     (onScroll)="handleOnScroll($event.$detail.args)"
+     (onSort)="handleOnSort()">
+</angular-slickgrid>
+```
+
+```ts
+export class Example implements OnInit {
+  scrollEndCalled = false;
+
+  // add onScroll listener which will detect when we reach the scroll end
+  // if so, then append items to the dataset
+  handleOnScroll(event) {
+    const args = event.detail?.args;
+    const viewportElm = args.grid.getViewportNode();
+    if (
+      ['mousewheel', 'scroll'].includes(args.triggeredBy || '')
+      && !this.scrollEndCalled
+      && viewportElm.scrollTop > 0
+      && Math.ceil(viewportElm.offsetHeight + args.scrollTop) >= args.scrollHeight
+    ) {
+      // onScroll end reached, add more items
+      // for demo purposes, we'll mock next subset of data at last id index + 1
+      const startIdx = this.angularGrid.dataView?.getItemCount() || 0;
+      const newItems = this.loadData(startIdx, FETCH_SIZE);
+      this.angularGrid.dataView?.addItems(newItems);
+      this.scrollEndCalled = false; //
+    }
+  }
+
+  // do we want to reset the dataset when Sorting?
+  // if answering Yes then use the code below
+  handleOnSort() {
+    if (this.shouldResetOnSort) {
+      const newData = this.loadData(0, FETCH_SIZE);
+      this.angularGrid.slickGrid?.scrollTo(0); // scroll back to top to avoid unwanted onScroll end triggered
+      this.angularGrid.dataView?.setItems(newData);
+      this.angularGrid.dataView?.reSort();
+    }
+  }
+}
+```
+
+---
+
+## Infinite Scroll with Backend Services
+
+As describe above, when used with the Backend Service API, it will add data to the in-memory dataset whenever we scroll to the bottom. However there is one thing to note that might surprise you which is that even if Pagination is hidden in the UI, but the fact is that behind the scene that is exactly what it uses (mainly the Pagination Service `.goToNextPage()` to fetch the next set of data).
+
+#### Code Sample
+We'll use the OData Backend Service to demo Infinite Scroll with a Backend Service, however the implementation is similar for any Backend Services. The main difference with the Infinite Scroll implementation is around the `onProcess` and the callback that we use within (which is the `getCustomerCallback` in our use case). This callback will receive a data object that include the `infiniteScrollBottomHit` boolean property, this prop will be `true` only on the 2nd and more passes which will help us make a distinction between the first page load and any other subset of data to append to our in-memory dataset. With this property in mind, we'll assign the entire dataset on 1st pass with `this.dataset = data.value` (when `infiniteScrollBottomHit: false`) but for any other passes, we'll want to use the DataView `addItems()` to append data to the existing dataset (in-memory) and that's about it.
+
+##### View
+```html
+<angular-slickgrid
+     gridId="grid2"
+     [columns]="columnDefinitions"
+     [options]="gridOptions"
+     [dataset]="dataset"
+     (onAngularGridCreated)="angularGridReady($event.detail)">
+</angular-slickgrid>
+```
+
+```ts
+export class Example implements OnInit {
+  initializeGrid() {
+    this.columnDefinitions = [ /* ... */ ];
+
+    this.gridOptions = {
+      presets: {
+        // NOTE: pagination preset is NOT supported with infinite scroll
+        // filters: [{ columnId: 'gender', searchTerms: ['female'] }]
+      },
+      backendServiceApi: {
+        service: new GridOdataService(), // or any Backend Service
+        options: {
+          // enable infinite scroll via Boolean OR via { fetchSize: number }
+          infiniteScroll: { fetchSize: 30 }, // or use true, in that case it would use default size of 25
+
+        preProcess: () => {
+          this.displaySpinner(true);
+        },
+        process: (query) => this.getCustomerApiCall(query),
+        postProcess: (response) => {
+          this.displaySpinner(false);
+          this.getCustomerCallback(response);
+        },
+        // we could use local in-memory Filtering (please note that it only filters against what is currently loaded)
+        // that is when we want to avoid reloading the entire dataset every time
+        // useLocalFiltering: true,
+      } as OdataServiceApi,
+    };
+  }
+
+  // Web API call
+  getCustomerApiCall(odataQuery) {
+    return this.http.get(`/api/getCustomers?${odataQuery}`);
+  }
+
+  getCustomerCallback(data: { '@odata.count': number; infiniteScrollBottomHit: boolean; metrics: Metrics; query: string; value: any[]; }) {
+    // totalItems property needs to be filled for pagination to work correctly
+    const totalItemCount: number = data['@odata.count'];
+    this.metrics.totalItemCount = totalItemCount;
+
+    // even if we're not showing pagination, it is still used behind the scene to fetch next set of data (next page basically)
+    // once pagination totalItems is filled, we can update the dataset
+
+    // infinite scroll has an extra data property to determine if we hit an infinite scroll and there's still more data (in that case we need append data)
+    // or if we're on first data fetching (no scroll bottom ever occured yet)
+    if (!data.infiniteScrollBottomHit) {
+      // initial load not scroll hit yet, full dataset assignment
+      this.angularGrid.slickGrid?.scrollTo(0); // scroll back to top to avoid unwanted onScroll end triggered
+      this.dataset = data.value;
+      this.metrics.itemCount = data.value.length;
+    } else {
+      // scroll hit, for better perf we can simply use the DataView directly for better perf (which is better compare to replacing the entire dataset)
+      this.angularGrid.dataView?.addItems(data.value);
+    }
+  }
+}
+```

package/docs/grid-functionalities/providing-grid-data.md

@@ -0,0 +1,61 @@
+## Overview
+
+The data is passed to the grid via the constructor and can also be accessed using the `setData(data)` and `getData()` methods.  Data itself can be either an array-like object with a `length` property and an indexer (`data[index]`) or a custom data provider implementing the following interface:
+
+* `getLength()` - returns the number of data items in the set
+* `getItem(index)` - returns the item at a given index
+* `getItemMetadata(index)` - returns the metadata for the item at a given index (optional)
+
+## Item Metadata
+
+`getItemMetadata` provides a powerful way of specifying additional information about a data item that let the grid customize the appearance and handling of a particular data item.  The method should return `null` if the item requires no special handling, or an object in the following general format:
+
+    {
+      // properties describing metadata related to the item (i.e. grid row) itself
+      "<property>": value,
+      "<property>": value,
+
+      // properties describing metadata related to individual columns
+      "columns":  {
+        "<column index>":  {
+          // metadata indexed by column index
+          "<property>": value,
+          "<property>": value
+        },
+
+        "<column id>":  {
+          // metadata indexed by column id
+          "<property>": value,
+          "<property>": value
+        }
+      }
+    }
+
+### Row-level properties
+
+* `cssClasses` (string) - One or more (space-separated) CSS classes to be added to the entire row.
+* `focusable` (boolean) - Whether or not any cells in the row can be set as "active".
+* `selectable` (boolean) - Whether or not a row or any cells in it can be selected.
+
+### Column-level properties
+
+* `focusable` (boolean) - Whether or not a cell can be set as "active".
+* `selectable` (boolean) - Whether or not a cell can be selected.
+* `formatter` (Function) - A custom cell formatter.
+* `editor` (Function) - A custom cell editor.
+* `colspan` (number|string) - Number of columns this cell will span.  Can also contain "*" to indicate that the cell should span the rest of the row.
+
+### Order of checks
+
+When looking up a property, the grid checks in the following order:
+
+1. Row-level item metadata.
+2. Column-level item metadata by column id.
+3. Column-level item metadata by column index.
+4. Column definition.
+5. Grid options.
+5. Grid defaults.
+
+## Examples
+
+See [colspan example](https://ghiscoding.github.io/Angular-Slickgrid/#/colspan).