npm package: @spflow/grid
Description: SharePoint Grid
Author: ARVO Systems
Latest version: 0.2.2

# SPFlow Grid for SharePoint

Reusable declarative grid component for SharePoint List views applications.

The component is based on Fluent UI (former Office UI Fabric).

## Supported platforms

- SharePoint Online
- SharePoint On-Prem (2019, 2016, 2013)

## Main features

- Declarative settings for most use-cases scenarios
  - List data source
  - OData, REST API projection (select, filter, top, expand, orderBy)
  - Columns model
- Custom cell renderers
- Embed and custom commands
- Data enrichment
- Columns runtime sorting
- Grid columns customizable filter pane
- True pagination
- Export to Excel

## Install

```bash
npm i @spflow/grid
```

## Usage sample

```typescript
import * as React from 'react';
import { GridView } from '@spflow/grid';

export const Component = (): JSX.Element => {

  return (
    <GridView
      listUri='_catalogs/masterpage'
      select='Id,Title,Editor/Title'
      expand='Editor'
      columns={[
        {
          key: 'Id',
          fieldName: 'Id',
          name: 'ID',
          minWidth: 40,
          maxWidth: 50
        },
        {
          key: 'Title',
          fieldName: 'Title',
          name: 'Title',
          minWidth: 150,
          maxWidth: 250
        },
        {
          key: 'Editor',
          fieldName: 'Editor/Title',
          name: 'Editor',
          minWidth: 150,
          maxWidth: 250
        }
      ]}
      commands={[
        { key: 'view' }
      ]}
      top={10}
    />
  );

};
```

## Grid API Reference

### Required properties

Parameter      | Description
---------------|------------
`listUri`        | SharePoint List URL, e.g. 'Lists/MyList', should not contain web relative URL
`select`         | OData (REST API) field names to select and use in the grid, not necessarily should be presented in a view explicitly

### List API query properties (optional)

Parameter        | Description
-----------------|------------
`filter`         | OData (REST API) `filter` condition applied to grid view
`expand`         | OData (REST API) `expand` fields, e.g. a lookup field 'Editor' if 'Editor/Id,Editor/Title' is considered in `select` property
`top`            | OData (REST API) `top` number defines view page size
`orderBy`        | OData (REST API) fields default sort constructor array, each object is `{ fieldName: string; ascending: boolean; }`

### Grid properties (optional)

Parameter       | Description
-----------------|------------
`title`          | View title, a text shown above grid component
`showBackButton` | If `true` view back button is rendered
`columns`        | Columns configuration model (see more below)
`commands`       | Command bar actions configuration model (see more below)
`filterFields`   | Enabled grid filters configuration model (see more below)
`renders`        | Custom cell renderers collection object
`onSelectionChanged` | Grid items selection change callback handler
`reloadKey`      | When a new unique key is provided externally, grid refreshes itself
`viewMode`       | When `true` default edit commands are blocked
`selectionMode`  | FluentUI selection mode property bypass
`enrichDataOnPageLoad` | Data enrichment callback, can be used to request additional data after a page items loaded, e.g. request external API or something which is not possible to retrieve using standard OData approach
`commandsCustomRules` | Custom rules callback collection, the rules can be used in Commands enable option, allows action enable based on metadata or external conditions
`emptyGridMessage` | Message shown when no items are in the grid view response
`viewStorageKey` | Unique string used for local storage to persist grid state (applied filters, sort conditions, etc.) so these can be kept after a page reload

### Columns model properties

Extends FluentUI `IColumn` interface.

Parameter        | Description
-----------------|------------
`fieldName`      | OData field name, maps API data and default view cell renderer, e.g. `Title` or `Lookup/Title` (required)
`type`           | Type renderers helper, allows rendering Boolean, Date, DateTime values without providing a custom renterer but reusing default embed helpers
`disableSort`    | If `true` sorting by a column is disabled, must to applied for column types which do not support sorting (e.g. Note field)

Other properties are a bypass of FluentUI Details List IColumn interface, [see more](https://developer.microsoft.com/en-us/fluentui#/controls/web/detailslist#IColumn).

The required by FluentUI columns are: `key`, `name`, `minWidth`.

### Filters model properties

Parameter        | Description
-----------------|------------
`label`          | Filter label
`fieldName`      | OData (REST API) field name, some cases might also require adding corresponding `expand` and `select` values to the grid properties
`fieldType`      | Can be one of the following: 'string', 'number', 'date', 'lookup', 'boolean'
`dictionary`     | A dictionary of values which can be selected in the filter, can be used together with 'string', 'number' and 'boolean' `fieldType`s
`lookupProps`    | Lookup configuration object, is relevant only with 'lookup' `fieldType`, lookup props allows not only define which list to use, but also provide some options

### Commands model properties

Extends FluentUI `ICommandBarItemProps` interface.

Parameter        | Description
-----------------|------------
`enableRule`     | String of \|-separated rules which define if an action is enabled for the selected item(s) in a view
`showRule`       | Same as `enableRule` but hides an action button instead of disabling
`onClickHandler` | Action handler

There are some predefined actions, such as 'add', 'copy', 'view', 'edit', 'delete'. These commands can be added in a simplified way by a shortcut declaration, e.g. `{ key: 'view' }` will add the default view action button.

A sample of a rule:

```typescript
enableRule: `onSingleSelection|permissions:${PermissionKind.EditListItems}|custom:myRule`
```

To operate with permissions, `EffectiveBasePermissions` property should be selected along with other fields in a grid definition.

#### Enable/show rules

Rules are declarative, within default rules are the following:

Rule                  | Description
----------------------|------------
`onSingleSelection`   | When only a single item is selected in a view
`onMultipleSelection` | When multiple items are selected in a view
`onAnySelection`      | When one or many items are selected in a view
`permissions:[PermissionKind]` | Based on permissions where `[PermissionKind]` is permissions bit ([see more](https://github.com/pnp/pnpjs/blob/version-2/packages/sp/security/types.ts#L246))
`custom:[CustomRule]` | Where `[CustomRule]` is a callback rule defined in `commandsCustomRules`