feat: adding more selection examples

Author: afshinm

docs/examples/row-selection.md

@@ -16,35 +16,15 @@ keywords:
 import { LiveExample } from "../../lib/liveExample.js";
 import { RowSelection } from "gridjs-selection";
 
-## Install
-
-Install the `gridjs-selection` package using yarn/npm:
-
-```bash
-npm install gridjs-selection --save
-```
-
-or use a CDN:
-
-```html
-<script src="https://unpkg.com/gridjs-selection/dist/gridjs-selection.production.min.js"></script>
-```
-
-then import the `RowSelection` plugin:
-
-```js
-import { RowSelection } from "gridjs-selection";
-```
-
-In UMD, `gridjs-selection` plugin globally exposed `gridjs.selection`, e.g:
-
-```js
-gridjs.selection.RowSelection
-```
+:::tip
+Install the `gridjs-selection` plugin if you haven't already. 
+Follow the [installation manual](./examples/selection.md).
+:::
 
 ## Example
 
-Add a new column to your table definition and install the plugin:
+Add a new column to your table definition and install the plugin. You need to define an `id` function for your selection
+plugin. The `id` function must return a unique `string` for each row and is called to determine the identifier for each row.
 
 <LiveExample children={
 `
@@ -70,6 +50,7 @@ const grid = new Grid({
       'Email',
   ],
   sort: true,
+  search: true,
   data: Array(5).fill().map(x => [
     faker.name.findName(),
     faker.internet.email(),
@@ -83,17 +64,21 @@ In the example above, the 3rd cell (which is `row.cell(2).data`) has been select
 the "Email" field. Note that the first cell is the checkbox column.
 :::
 
-## Events
 
-You can also subscribe to the `RowSelection` store and receive updates as soon as a row is checked or unchecked:
+## Selected rows
+
+The selection plugin uses a Redux architecture and that means each selection instance has its own unique Store which keeps
+the list of selected rows.
 
 <LiveExample children={
 `
 const grid = new Grid({
   columns: [
       {
-        id: 'awesomeCheckbox',
+        id: 'selectRow',
         name: 'Select',
+        // select all rows by default!
+        data: () => true, 
         plugin: {
           component: RowSelection,
           props: {
@@ -113,17 +98,95 @@ const grid = new Grid({
     faker.internet.email(),
   ])
 });
-  
+ 
 grid.on('ready', () => {
   // find the plugin with the give plugin ID
-  const checkboxPlugin = grid.config.plugin.get('awesomeCheckbox');
-  
-  // subscribe to the store events
-  checkboxPlugin.props.store.on('updated', function (state, prevState) {
-    console.log('checkbox updated', state, prevState);
-  });
+  const checkboxPlugin = grid.config.plugin.get('selectRow');
+  // read the selected rows from the plugin's store
+  console.log('selected rows:', checkboxPlugin.props.store.state);
 })
 `
 } scope={{RowSelection}} />
 
+## Row selection extension
+
+Grid.js enables you to write custom plugins and extend the core functionality. In this example, we are developing a custom
+plugin which listens to the Selection plugin events and populates a list of selected rows.
+
+
+<LiveExample children={
+`
+class SelectionsList extends BaseComponent {
+  constructor(props, context) {
+    super(props, context);
+    
+    this.state = {
+      selectedRows: []
+    };
+  }
+  
+  componentDidMount() {
+     const grid = this.config.instance;
+     
+     grid.on('ready', () => {
+       // find the plugin with the give plugin ID
+       const checkboxPlugin = this.config.plugin.get('selectRow');
+       
+       // subscribe to the store events
+       checkboxPlugin.props.store.on('updated', (state) => {
+         this.setState({
+           selectedRows: state.rowIds
+         });
+       });
+    });
+  }
+  
+  render() {
+    if (!this.state.selectedRows.length) {
+      return h('b', {}, 'Select some rows...');
+    }
+    
+    return h(
+      'ul', 
+      {}, 
+      this.state.selectedRows.map((rowId) => h('li', {}, rowId))
+    );
+  }
+}
+  
+const grid = new Grid({
+  columns: [
+      {
+        id: 'selectRow',
+        name: 'Select',
+        plugin: {
+          component: RowSelection,
+          props: {
+            id: (row) => row.cell(2).data
+          }
+        }
+      },
+      { 
+        name: 'Name',
+        formatter: (cell) => \`Name: \${cell}\`
+      },
+      'Email',
+  ],
+  sort: true,
+  data: Array(5).fill().map(x => [
+    faker.name.findName(),
+    faker.internet.email(),
+  ])
+});
+ 
+grid.plugin.add({
+  id: 'selectionsList',
+  component: SelectionsList,
+  position: PluginPosition.Footer,
+});
+`
+} scope={{RowSelection}} />
 
+:::tip
+Follow the [Advanced Plugin](./plugin/advanced-plugins.md) article to learn more about writing Grid.js plugins!
+:::

docs/examples/selection-events.md

@@ -0,0 +1,59 @@
+---
+id: selection-events
+title: Selection events
+keywords:
+ - javascript
+ - table
+ - javascript table
+ - gridjs
+ - grid js
+ - checkbox
+ - cell checkbox
+ - row selection 
+ - selection events
+ 
+---
+
+import { LiveExample } from "../../lib/liveExample.js";
+import { RowSelection } from "gridjs-selection";
+
+You can also subscribe to the `RowSelection` store and receive updates as soon as a row is checked or unchecked:
+
+<LiveExample children={
+`
+const grid = new Grid({
+  columns: [
+      {
+        id: 'awesomeCheckbox',
+        name: 'Select',
+        plugin: {
+          component: RowSelection,
+          props: {
+            id: (row) => row.cell(2).data
+          }
+        }
+      },
+      { 
+        name: 'Name',
+        formatter: (cell) => \`Name: \${cell}\`
+      },
+      'Email',
+  ],
+  sort: true,
+  data: Array(5).fill().map(x => [
+    faker.name.findName(),
+    faker.internet.email(),
+  ])
+});
+  
+grid.on('ready', () => {
+  // find the plugin with the give plugin ID
+  const checkboxPlugin = grid.config.plugin.get('awesomeCheckbox');
+  
+  // subscribe to the store events
+  checkboxPlugin.props.store.on('updated', function (state, prevState) {
+    console.log('checkbox updated', state, prevState);
+  });
+})
+`
+} scope={{RowSelection}} />

docs/examples/selection.md

@@ -0,0 +1,43 @@
+---
+id: selection
+title: Selection 
+keywords:
+ - javascript
+ - table
+ - javascript table
+ - gridjs
+ - grid js
+ - checkbox
+ - cell checkbox
+ - row selection 
+ 
+---
+
+Selection plugin enables users to select rows or cells. You can then retrieve the selected rows/cells from the plugin store.
+
+## Install
+
+Install the `gridjs-selection` package using yarn/npm:
+
+```bash
+npm install gridjs-selection --save
+```
+
+or use a CDN:
+
+```html
+<script src="https://unpkg.com/gridjs-selection/dist/gridjs-selection.production.min.js"></script>
+```
+
+then import the `RowSelection` plugin:
+
+```js
+import { RowSelection } from "gridjs-selection";
+```
+
+In UMD, `gridjs-selection` plugin globally exposed `gridjs.selection`, e.g:
+
+```js
+gridjs.selection.RowSelection
+```
+

docs/plugin/advanced-plugins.md

@@ -60,7 +60,7 @@ const grid = new Grid({
 
 grid.plugin.add({
   id: 'salaryplugin',
-  component: h(TotalSalaryPlugin, {}),
+  component: TotalSalaryPlugin,
   position: PluginPosition.Footer,
 });
 `
@@ -93,7 +93,7 @@ const grid = new Grid({
 
 grid.plugin.add({
   id: 'bonjour',
-  component: h(HelloPlugin, {}),
+  component: HelloPlugin,
   position: PluginPosition.Header,
 });
 `

sidebars.js

@@ -93,7 +93,9 @@ module.exports = {
       type: 'category',
       label: 'Selection',
       items: [
+        'examples/selection',
         'examples/row-selection',
+        'examples/selection-events',
       ]
     }, {
       type: 'category',