@spflow/grid NPM

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

npm i @spflow/grid

Usage sample

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.

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:

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)
`custom:[CustomRule]`	Where `[CustomRule]` is a callback rule defined in `commandsCustomRules`