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' fieldTypes 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