How to use the PnP FieldCollectionData control

Proceeding with the appointments with the PnP React controls today I want to talk about the FieldCollectionData control.

If you’re interested you can find the code of this sample here.

The FieldCollectionData control is used to display a button that the user can click, once the button is clicked it will opens a panel where the user can manage an array of object in a tabular view.

Each object in the array, or row in the table, can contain multiple properties and each instance of the PnP FieldCollectionData can display a specific set of the properties defined in the objects (the table columns).

Let me explain some of the possible configurations for the FieldCollectionData control.

How it looks like?

Starting with the resulting UI, here is the initial representation of the control instances that I’ve created for this sample:

As said before the FieldCollectionData control renders a button and as you can see there are five buttons, each one renders a different panel and the resulting UI will be something like the following:

By default in the panel there are some available actions:

• In the last row it’s possible to insert a new item.
• In the rows, where there are already some values, it’s provided the ability to update the value.
• At the further right side there is an x button that enables the deletion of the selected row.

Aside of the CRUD operations the control enables, by default, the pagination which is a very useful feature!

As said, there are five different instances in this sample so let’s dive into each one.

The first one is the “Various fields”, this instance renders a panel that enables the CRUD (Create Read Update Delete) operations on the object array. In this panel there are various field types:

• string : renders a simple textbox to handle a string value.
• number : renders a textbox which handles a numeric value.
• boolean : renders a checkbox to handle a boolean value.
• fabric icon : this is an out of the box control that allows the rendering of an Office UI Fabri icon, in this sample it renders the icon with the name specified in the text box.

The following instance “Selection fields” gives the ability to select values from two different controls:

• dropdown : renders a dropdown control to enable the user to select a value from a predefined set of options.
• Multi select dropdown : renders a combobox to enable the selection of multiple options.

In details the combobox will render the following:

Proceeding with the “Search” instance, there are other possible out of the box controls in the panel and those are:

• People picker : allows the selection of a user.
• URL : allows the insertion of an URL string, if the string is not an URL the control will render an error.
• Date : renders a date picker panel and allows the user to select a date.

The following instance is called “Search” and that’s because it shows the search capability in fact the user can provide a custom filter query, in this case it will filter the available rows that contains the inserted value using a specified query method (I will explain it later in the code section):

The next instance is the “Sorting” one, this instance adds a dropdown at the further left side of each line allowing the user to define what is the index of each line:

Here I’ve changed the values of the index field and you can see the updated values:

The last instance, the “Custom field” one, is used to display a customized field which, in this case, renders an icon and a slider:

Another customization of this instance is that, if all the lines got deleted, a label is displayed and the displayed text is customizable:

Show me the code

To use the PnP React controls first you need to install the package:

npm install @pnp/spfx-controls-react --save --save-exact

After the installation of the package you can proceed with the following instructions for the FieldCollectionData control.

Just to understand all the code that I will show you I need to briefly explain how the items in the array are defined. The array that the controls will be using is of type ISampleData[] and the type is defined as following:

export interface ISampleData {
  StringField: string;
  NumberField: number;
  BooleanField: boolean;
  DropdownField: string;
  MultiSelectComboboxField: string[];
  FabricIconField: string;
  PeoplePickerField: string;
  URLField: string;
  DateField: Date;
  CustomField: string;
}

With this type defined I’ve created an array of sample objects to work with.

Now we can proceed with the code of the various instances, keep in mind that some of the control properties are required and if you want to know which ones you can have a look here on the official documentation.

Various fields

This control instance is defined as follow:

<FieldCollectionData
  key={"VariousFieldCollectionData"}
  label={strings.VariousFieldTitle}
  panelDescription={strings.VariousFieldDescription}
  manageBtnLabel={strings.Manage}
  onChanged={(value) => { 
    this.setState({ sampleData: value });
  }}
  panelHeader={strings.Header}
  context={this.props.context as any}
  itemsPerPage={3}
  fields={[
   { id: "StringField", title: "String field", type: CustomCollectionFieldType.string, required: true },
   { id: "NumberField", title: "Number field", type: CustomCollectionFieldType.number },
   { id: "BooleanField", title: "Boolean field", type: CustomCollectionFieldType.boolean },
   { id: "FabricIconField", title: "FabricIcon field", type: CustomCollectionFieldType.fabricIcon },
  ]}
  value={this.state.sampleData}
/>

One of the important properties to use this control is the fields one, this property define an array of objects representing which fields from the array of objects will be enabled in the panel. For each of the field object there is the ability to define what type of control will be rendered in the panel and there are many out of the box available options:

• string
• number
• boolean
• dropdown
• combobox
• peoplepicker
• fabricIcon
• url
• date
• custom

Other useful properties are the value and the onChanged properties, the first one enables the binding of the array of objects and the second one allows to define what action to execute when saving the values.

Selection fields

This control has a similar configuration of the previous one but has a different fields property defined in the following fashion:

fields={[
  { 
    id: "DropdownField",
    title: "Dropdown field", 
    type: CustomCollectionFieldType.dropdown, 
    options: [
      { key: "1", text: "One" },
      { key: "2", text: "Two" }, 
      { key: "3", text: "Three" }
    ]
  }, 
  { 
    id: "MultiSelectComboboxField", 
    title: "MultiSelectDropdown field",
    type: CustomCollectionFieldType.combobox, 
    multiSelect: true, 
    options: [
      { key: "1", text: "Multi One" }, 
      { key: "2", text: "Multi Two" }, 
      { key: "3", text: "Multi Three" }
    ]
  },
]}

This configuration renders a dropdown and a combobox controls, for each one an options property define what are the available selectable options.

In the combobox control the multiSelect property enables the ability to select multiple options instead of the default single selection mode.

Search

This instance is used to show, aside of other possible fields types (people picker, URL and Date fields), the ability to search by a specific query. In order to achieve this you can specify a custom query using the executeFiltering property, this property define a method that accept a searchFilter and item parameters. The searchFilter returns the input query defined by the user, the item parameter on the other hand represent the current item from the object array on which you can perform the query that you want.

In the sample I’ve compared the URL field with the searched text:

executeFiltering={(searchFilter: string, item: any) => {  
  return item.URLField.indexOf(searchFilter) !== -1;
}} 

Sorting

This instance demonstrates how to sort the item from the object array, to achieve this you have to simply define the enableSorting property and set it to true:

enableSorting={true}

As displayed in the screenshots above this renders a new column where you can define the sorting index of each item in the object array.

Custom Field

The custom field instance shows how you can create and use a custom field, because the out of the box controls type are pre defined you may need to create a different behavior or render a different control. To define the custom control you can define it while defining the available fields, in this sample it’s defined in the following way:

fields={[
  { 
    id: "StringField", 
    title: "String field", 
    type: CustomCollectionFieldType.string, 
    required: true 
  },
  { 
    id: "CustomField", 
    title: "Custom field", 
    type: CustomCollectionFieldType.custom, 
    onCustomRender: this._fieldCustomRenderer 
  }
]} 

As you can see the second field is the custom one, to define the custom control you have to set the type property of the field to the CustomCollectionFieldType.custom one and the onCustomRender method defines how the control is created, in this sample I defined a method which returns the control to be rendered:

private _fieldCustomRenderer = (field: ICustomCollectionField, value: any, onUpdate: (fieldId: string, value: any) => void, item: any, rowUniqueId: string, onCustomFieldValidation: (fieldId: string, errorMessage: string) => void) => {
  if (!value) {
    value = JSON.stringify({ "sliderValue": "" });
  }

  const v = JSON.parse(value);

  return (
    <div>
      <Icon iconName="Emoji2" />
      <Slider
        min={0}
        max={100}
        step={5}
        value={v.sliderValue}
        onChange={(value) => { onUpdate(field.id, JSON.stringify({ "sliderValue": value })) }}
      />
    </div>
  );
}

The custom component renders an icon with a slider just to demonstrate how you can achieve the creation of a custom component.

Wrap up

The FieldCollectionData control is one of the PnP React controls that I like the most, it is pretty useful, very customizable and offers many out of the box features. If you’re interested in knowing more I suggest that you take a look at the official documentation here.

Hope this helps!