docs: add Row Based Editing documentation

ghiscoding · ghiscoding · commit 37de936f965d · 2024-01-21T01:41:42.000-05:00
diff --git a/docs/TOC.md b/docs/TOC.md
@@ -71,6 +71,7 @@
 * [Row Detail](grid-functionalities/row-detail.md)
 * [Row Selection](grid-functionalities/Row-Selection.md)
 * [Tree Data Grid](grid-functionalities/Tree-Data-Grid.md)
+* [Row Based Editing Plugin](grid-functionalities/Row-based-edit.md)
 * [FAQ](grid-functionalities/FAQ.md)
 
 ## Backend Services
diff --git a/docs/column-functionalities/Cell-Menu.md b/docs/column-functionalities/Cell-Menu.md
@@ -7,7 +7,7 @@
 - [UI Sample](#ui-sample)
 
 ### Demo
-[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/context) / [Demo Component](/ghiscoding/angular-slickgrid/blob/master/src/app/examples/grid-contextmenu.component.ts)
+[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/context) / [Demo Component](https://github.com/ghiscoding/Angular-Slickgrid/blob/master/src/app/examples/grid-contextmenu.component.ts)
 
 ### Description
 A Cell Menu, most often used as an Action Menu and is more oriented on a row action (e.g. delete current row), it could be defined on 1 or more columns (defined in a column definition) and is triggered by a cell click or touch. The menu can show a list of Commands (to execute an action) and/or Options (to change the value of a field). Also note that the Commands list is following the same structure used in the [Context Menu](../grid-functionalities/Context-Menu.md), [Header Menu](../grid-functionalities/Header-Menu-&-Header-Buttons.md) & [Grid Menu](../grid-functionalities/Grid-Menu.md). The Cell Menu is very similar to the [Context Menu](../grid-functionalities/Context-Menu.md), both were create as SlickGrid plugins during the same period, their main difference is that they get triggered differently (cell click vs mouse right+click) and they serve different purposes. The Cell Menu is more oriented on a row action (e.g. delete current row) while the Context Menu is all about actions for the entire grid (e.g. export to Excel).
diff --git a/docs/column-functionalities/Editors.md b/docs/column-functionalities/Editors.md
@@ -571,4 +571,7 @@ onAfterEditCell($event) {
 onBeforeEditCell($event) {
   this.angularGrid.resizerService.pauseResizer(true);
 }
-```
+```
+
+## Turning individual rows into edit mode
+Using the [Row Based Editing Plugin](../grid-functionalities/Row-based-edit.md) you can let the user toggle either one or multiple rows into edit mode, keep track of cell changes and either discard or save them on an individual basis using a custom `onBeforeRowUpdated` hook.
diff --git a/docs/column-functionalities/filters/Autocomplete-Filter-(Kraaden-lib).md b/docs/column-functionalities/filters/Autocomplete-Filter-(Kraaden-lib).md
@@ -68,7 +68,7 @@ export class GridBasicComponent implements OnInit {
 ```
 
 ### Filter Options (`AutocompleterOption` interface)
-All the available options that can be provided as `filterOptions` to your column definitions can be found under this [AutocompleterOption interface](/ghiscoding/angular-slickgrid/blob/master/src/app/modules/angular-slickgrid/models/autocompleterOption.interface.ts) and you should cast your `filterOptions` to that interface to make sure that you use only valid options of the jQueryUI autocomplete library.
+All the available options that can be provided as `filterOptions` to your column definitions can be found under this [AutocompleterOption interface](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/interfaces/autocompleterOption.interface.ts) and you should cast your `filterOptions` to that interface to make sure that you use only valid options of the jQueryUI autocomplete library.
 
 ```ts
 filter: {
diff --git a/docs/grid-functionalities/Grid-State-&-Preset.md b/docs/grid-functionalities/Grid-State-&-Preset.md
@@ -8,16 +8,16 @@
 ### Demo
 Look at your developer console before leaving the page
 #### Regular grid
-[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/clientside) / [Demo Component](/ghiscoding/angular-slickgrid/blob/master/src/app/examples/grid-clientside.component.ts)
+[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/clientside) / [Demo Component](https://github.com/ghiscoding/Angular-Slickgrid/blob/master/src/app/examples/grid-clientside.component.ts)
 
 #### with Backend Service
-[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/gridgraphql) / [Demo Component](/ghiscoding/angular-slickgrid/blob/master/src/app/examples/grid-graphql.component.ts)
+[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/gridgraphql) / [Demo Component](https://github.com/ghiscoding/Angular-Slickgrid/blob/master/src/app/examples/grid-graphql.component.ts)
 
 ## Descriptions
 #### Grid State
 The `Grid State` are what we defined as the currently used `Columns` / `Filters` / `Sorters` / `Pagination` of the actual grid (pagination is only returned when used with Backend Service API). The columns also include their (size, position order & visibility (show/hidden)).
 #### Presets
-Presets can be used to preset a grid with certain `Columns` / `Filters` / `Sorters` / `Pagination`. When we say `Columns`, we actually mean their size, order position and visibility (shown/hidden) in the grid.  
+Presets can be used to preset a grid with certain `Columns` / `Filters` / `Sorters` / `Pagination`. When we say `Columns`, we actually mean their size, order position and visibility (shown/hidden) in the grid.
 #### Combining the two together
 So basically, the idea is to save the `Grid State` in Local Storage (or DB) before the grid gets destroyed and once we come back to that same page we can preset the grid with the exact same state as it was before leaving the page (just like if we were doing a forward/back button with browser history).
 
@@ -26,10 +26,10 @@ You can get the `Grid State` at any point in time. However if you wish to save t
 
 ##### View
 ```html
-<angular-slickgrid 
+<angular-slickgrid
      gridId="grid2"
-     [columnDefinitions]="columnDefinitions" 
-     [gridOptions]="gridOptions" 
+     [columnDefinitions]="columnDefinitions"
+     [gridOptions]="gridOptions"
      [dataset]="dataset"
      (onAngularGridCreated)="angularGridReady($event.detail)"
      (onBeforeGridDestroy)="saveCurrentGridState($event)">
@@ -167,13 +167,13 @@ export class ExampleComponent implements OnInit {
 }
 ```
 
-#### 2. Through `onGridStateChanged` Observable on the GridState Service 
+#### 2. Through `onGridStateChanged` Observable on the GridState Service
 ##### View
 ```html
-<angular-slickgrid 
+<angular-slickgrid
      gridId="grid2"
-     [columnDefinitions]="columnDefinitions" 
-     [gridOptions]="gridOptions" 
+     [columnDefinitions]="columnDefinitions"
+     [gridOptions]="gridOptions"
      [dataset]="dataset"
      (onAngularGridCreated)="angularGridReady($event.detail)"
      (onBeforeGridDestroy)="saveCurrentGridState($event)">
@@ -199,7 +199,7 @@ export class ExampleComponent implements OnInit, OnDestroy {
 ```
 
 ## How to Load Grid with certain Columns Preset (example hide certain Column(s) on load)
-You can show/hide or even change column position all via the `presets`, yes `presets` is that powerful. All you need is to pass all Columns that you want to show as part of the `columns` property of `presets`. Typically you already have the entire columns definition since you just defined it, so you can re-use that and just use `map` to loop through and populate the `columns` according to the structure needed (see [preset structure](#structure)). What you have to know is that whatever array you pass will drive what the user will see and at which order the columns will show (basically the array order does matter). If a Columns is omitted from that array, then it will become a hidden column (you can still show it through Grid Menu or Column Picker). 
+You can show/hide or even change column position all via the `presets`, yes `presets` is that powerful. All you need is to pass all Columns that you want to show as part of the `columns` property of `presets`. Typically you already have the entire columns definition since you just defined it, so you can re-use that and just use `map` to loop through and populate the `columns` according to the structure needed (see [preset structure](#structure)). What you have to know is that whatever array you pass will drive what the user will see and at which order the columns will show (basically the array order does matter). If a Columns is omitted from that array, then it will become a hidden column (you can still show it through Grid Menu or Column Picker).
 
 So let say that we want to hide the last Column on page load, we can just find the column by it's `id` that you want to hide and pass the new column definition to the `presets` (again make sure to follow the correct preset structure).
 
@@ -213,8 +213,8 @@ this.columnDefinitions = [
 // and use `map()` to only pull required field for presets to work
 const mappedColumnDefinitions = this.columnDefinitions.map((col) => {
   return { columnId: col.id, width: col.width };
-}); 
-mappedColumnDefinitions.pop(); 
+});
+mappedColumnDefinitions.pop();
 
 // then pass it to the presets
 this.gridOptions = {
@@ -223,7 +223,7 @@ this.gridOptions = {
   }
 };
 ```
-This would be the easiest way to do it. 
+This would be the easiest way to do it.
 
 As pointed out earlier, the `presets` requires a specific structure where the `columns` is the list of columns to show/hide with their possible widths and also the position in the array is very important as it defines the position shown in the UI
 ```ts
diff --git a/docs/grid-functionalities/Resize-by-Cell-Content.md b/docs/grid-functionalities/Resize-by-Cell-Content.md
@@ -4,7 +4,7 @@
 - [Resize by Content - Column Options](#resize-by-content---column-options)
 
 ### Demo
-[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/resize-by-content) / [Demo Component](/ghiscoding/angular-slickgrid/blob/master/src/app/examples/grid-resize-by-content.component.ts)
+[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/resize-by-content) / [Demo Component](https://github.com/ghiscoding/Angular-Slickgrid/blob/master/src/app/examples/grid-resize-by-content.component.ts)
 
 ### Description
 The default of Slickgrid-Universal is to fit all columns in the container viewport and for the most part that is a good resize to use and it's fast. However if your grid has a lot of columns then doing a fit to viewport is not exactly great, you have lot of columns a few of these columns will become too small (we strongly suggest adding `minWidth` to every column) and you'll start seeing ellipsis to a few of these columns.
diff --git a/docs/grid-functionalities/Row-based-edit.md b/docs/grid-functionalities/Row-based-edit.md
@@ -0,0 +1,71 @@
+#### index
+- [The action column](#the-action-column)
+- [Multiple Row Selections](#multiple-row-selections)
+- [Change Dynamically Single/Multiple Selections](#changing-dynamically-from-single-to-multiple-selections-and-vice-versa)
+- [Mixing Single & Multiple Row Selections](#mixing-single--multiple-row-selections)
+- [Disable Custom Rows Selections via `selectableOverride`](#disable-custom-rows-selections-via-selectableoverride)
+- [Disable External Button when having Empty Selection](#disable-external-button-when-having-empty-selection)
+- [Change Row Selections](#change-row-selections)
+- Troubleshooting
+  - [Adding a Column dynamically is removing the Row Selection, why is that?](#adding-a-column-dynamically-is-removing-the-row-selection-why-is-that)
+
+### Description
+The Row based editing plugin makes it possible to keep the grid readonly except for rows which the user explicitely toggles into edit mode.
+
+**Note:** This plugin enforces the use of the `autoEdit` option and will turn it on with a console warning if its not already.
+
+### Demo
+[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/base-row-editing) / [Demo Component](https://github.com/ghiscoding/Angular-Slickgrid/blob/master/src/app/examples/grid-base-row-editing.component.ts)
+
+## The action column
+A new column is rendered that shows an edit/delete button. If the user clicks on edit, a save and cancel button are shown instead and the row toggles into edit mode. By default as the last column but you can override it with the option `columnIndexPosition`. Additionally it's default column id can be overriden using the opiton `columnId`. Furthermore, you can also override the columns label via the `actionsColumnLabel` property.
+
+### Single or multiple editable rows
+By default you can only toggle a single row into edit mode. If you set the option `allowMultipleRows` to `true` on the other hand, you can toggle as many as you want.
+
+### Configuring the action buttons
+You can override the styling, the hover text as well as whether a prompt — and with what text — should be shown. It is done by overriding the `actionButtons` property of the [plugins options](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/interfaces/rowBasedEditOption.interface.ts).
+
+## Support for the Excel Copy Buffer Plugin
+If the [Excel Copy Buffer Plugin](excel-copy-buffer.md) is configured, the Row based editing pluging will override it's behavior by denying pastes on all cells not within a edit mode row. Nevertheless, any existing `BeforePasteCellHandler` will be respected.
+
+## How the plugin works
+The idea of the plugin is to focus the users editing experience on specific individual rows and and save them individually. This is achieved by letting the user toggle one or more rows into edit mode.
+When a that happens a potentially registered `onBeforeEditMode` callback is executed to handle various preparation or cleanup tasks. Now changes can be made to those rows and will be highlighted and tracked. The user may cancel the edit mode at any time and revert all cells changes. If the save button is pressed on the other hand an `onBeforeRowUpdated` hook, which you define via plugin options, is called and expects a `Promise<boolean>`. In that method you'd typically write the changes to your backend and return either true or false based on the operations outcome. If a negative boolean is returned the edit mode is kept, otherwise the row applies the changes and toggles back into readonly mode. That means, no modifications can be done on the grid.
+
+Here's the respective code shown in Example22:
+
+#### ViewModel
+```ts
+onBeforeRowUpdated(args) {
+  const { effortDriven, percentComplete, finish, start, duration, title } = args.dataContext;
+
+  if (duration > 40) {
+    alert('Sorry, 40 is the maximum allowed duration.');
+    return Promise.resolve(false);
+  }
+
+  return fakeFetch('your-backend-api/endpoint', {
+    method: 'POST',
+    body: JSON.stringify({ effortDriven, percentComplete, finish, start, duration, title }),
+    headers: {
+      'Content-type': 'application/json; charset=UTF-8'
+    }
+  }).catch(err => {
+    console.error(err);
+    return false;
+  })
+  .then(response => {
+    if (response === false) {  // <---- the negative response, e.g validation failed, keep the row as is
+      return false;
+    }
+    if (typeof response === 'object') {
+      return response!.json();
+    }
+  })
+  .then(json => {
+    alert(json.message);
+    return true;  // <--- all good, apply changes in grid and toggle row into readonly mode
+  });
+},
+```
diff --git a/docs/styling/styling.md b/docs/styling/styling.md
@@ -21,7 +21,7 @@ Default compiled `css` (if you use the plain Bootstrap Theme CSS, you could simp
 ```
 
 #### SASS (`.scss`)
-You could also compile the SASS files with your own customization, for that simply take any of the [_variables.scss](/ghiscoding/angular-slickgrid/blob/master/src/app/modules/angular-slickgrid/styles/_variables.scss) (without the `!default` flag) variable file and make sure to import the Bootstrap Theme afterward. For example, you could modify your `style.scss` with the following changes:
+You could also compile the SASS files with your own customization, for that simply take any of the [_variables.scss](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/_variables.scss) (without the `!default` flag) variable file and make sure to import the Bootstrap Theme afterward. For example, you could modify your `style.scss` with the following changes:
 
 ```scss
 /* for example, let's change the mouse hover color */

Original file line number	Diff line number	Diff line change
`@@ -571,4 +571,7 @@ onAfterEditCell($event) {`
`571`	`571`	`onBeforeEditCell($event) {`
`572`	`572`	`this.angularGrid.resizerService.pauseResizer(true);`
`573`	`573`	`}`
`574`		-```
	`574`	+```
	`575`	`+`
	`576`	`+## Turning individual rows into edit mode`
	`577`	+Using the [Row Based Editing Plugin](../grid-functionalities/Row-based-edit.md) you can let the user toggle either one or multiple rows into edit mode, keep track of cell changes and either discard or save them on an individual basis using a custom `onBeforeRowUpdated` hook.