@spflow/grid

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