Explore the PnP FieldPicker Control for SharePoint Framework solutions

Introduction

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

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

The FieldPicker control is used to display a dropdown that contains a list of SharePoint fields to allow the user to select the desired one/s.

The default behavior of the control is to load all the available site columns defined in the current SharePoint site, this means also all the hidden and read only ones will be included. It’s also possible to filter the fields by list or specifying a custom filter.

As usual I’ve prepared a sample solution to demonstrate the different configuration of the PnP control.

Starting with the list of the control instances from the sample solution this is how the web part looks like:

Let’s have a look at the control instances, starting with the minimal configuration instance, when clicking on the dropdown, a list of selectable fields appears:

When the field is selected it will be displayed in the dropdown control:

With the list configured instance the available fields are restricted to those belonging to the specified list:

As usual there are some strings that are customizable, the custom strings instance demonstrate those possibilities. The available customization are a label over the control (Custom label) and also the placeholder inside the dropdown control (Click to select a field):

Another useful option is the ability to support multiple selection, this is achieved with a checkbox aside of each of the selectable field. The multi selection instance shows how the control appears:

After selecting the fields they will appear inside the dropdown control as following:

An useful option is the ability to add a blank option at the top of the selectable options, this is pretty handy in case you want to allow the user to clear an already done selection.

The group configuration instance allows to filter the displayed fields by a specific SharePoint site columns group:

There is also the ability to order the fields by title:

The filter fields instance shows how it’s possible to define a filtering query to display only the needed fields:

Another possible operation is to filter the fields after they are retrieved from SharePoint, in this sample I’ve filtered the fields that contains the word Date:

The last instance is used to show how to automatically select fields:

I didn’t cover all the instances here because the UI wouldn’t be that different, so let’s proceed with the code in the next session!

Show me the code

Prerequisites

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 to use the FieldPicker control.

To use the control you first need to import it and that can be done as following:

import { FieldPicker } from '@pnp/spfx-controls-react';

After the import of the control you can start to use it, let’s cover each of the instances in a little bit more detail.

Minimal configuration

This instance configuration shows what is the minimal configuration for the control. This minimal configuration is to declare the control and to set the context property:

<FieldPicker
  context={context} />

The property accept the web part context in order to automatically load the fields from the current SharePoint site.

List configured

This instance demonstrate the possibility to restrict the loaded fields to the ones belonging to a specific SharePoint list. In the sample the list is selected through a specific property in the property pane and set the value to the FieldPicker control’s property listId.

<FieldPicker
  context={context}
  listId={selectedList}
/>

OnSelectionChanged

Probably if you want to let the user select a field you also want to retrieve the selected item/s, this can be achieved using the onSelectionChanged event. In the solution, to declare a method to be used by the onSelectionChanged, it’s also useful to import another interface:

import { ISPField } from '@pnp/spfx-controls-react';

This interface is used when defining the method that will handle the on change event. This event is just for example purpose and it will only display, in the browser console, the selected fields.

private onFieldPickerChanged(fields: ISPField | ISPField[]): void {
  console.log("Fields:", fields);
}

The method defined before will be set in the FieldPicker control’s property onSelectionChanged as following:

<FieldPicker
  context={context}
  onSelectionChanged={this.onFieldPickerChanged}
/>

Just for reference, the ISPField interface, as by the time of writing, is declared as following:

export interface ISPField {
    Id: string;
    Title?: string;
    InternalName?: string;
    Hidden?: boolean;
    ReadOnlyField?: boolean;
    Group?: string;
    Format?: string;
    RichText?: boolean;
    SchemaXml?: string;
    LookupDisplayUrl?: string;
    TypeAsString?: string;
    ResultType?: string;
    ValidationFormula?: string;
    ValidationMessage?: string;
    MinimumValue?: number;
    MaximumValue?: number;
    CurrencyLocaleId?: number;
}

Custom strings

Some times it might be needed to specify a label or a custom placeholder. The FieldPicker control exposes two properties that allow you to customize those strings:

• label: this allow the definition of a custom string that will be placed before the control.
• placeholder: allow the definition of a custom string that will be placed inside the control.

<FieldPicker
  context={context}
  label={strings.CustomLabel}
  placeholder={strings.CustomStrings.Placeholder}
/>

Multi selection

Aside of the default single selection it’s possible to allow the user to select multiple options. The multi selection is declared using the multiSelect property and set it to true:

<FieldPicker
  context={context}
  multiSelect={true}
  onSelectionChanged={this.onFieldPickerChanged}
/>

Add blank option

By default, when a user select one or multiple values, it’s not possible to remove the selection. With the showBlankOption property set to true it’s possible to define an empty option to allow the user to remove the selected option.

<FieldPicker
  context={context}
  showBlankOption={true}
  onSelectionChanged={this.onFieldPickerChanged}
/>

When selecting the blank option the value returned to the onSelectionChanged method is undefined.

Group configuration

The property group allows to specify the name of a SharePoint site columns group in order to filter the selectable fields to the ones belonging to the specified group. In the following code snippet I filtered the fields belonging to the Base columns group:

<FieldPicker
  context={context}
  group="Base Columns"
/>

Don’t include hidden fields

By default the hidden fields are returned, if you want to hide those you will have to explicitly specify false as value of the includeHidden property:

<FieldPicker
  context={context}
  includeHidden={false}
/>

Don’t include read only fields

By default also the read only fields are included, if you want to hide those you will have to explicitly set to false the property includeReadOnly:

<FieldPicker
  context={context}
  includeReadOnly={false}
/>

Order by

One useful thing that the control allows is to specify an order by clause, in order to do that you will first have to import the FieldsOrderBy enum, this will help selecting the ordering field:

import { FieldsOrderBy } from '@pnp/spfx-controls-react/lib/services/ISPService';

Once imported the FieldsOrderBy enum you can specify the filtering clause:

<FieldPicker
  context={context}
  orderBy={FieldsOrderBy.Title}
/>

Just for reference, as far as the current implementation, the enum offers two different options:

• Title
• InternalName

Filter fields

The FieldPicker control offers the ability to filter the selectable fields. This filter will be applied when retrieving the fields. To specify the filtering option you will have to specify an OData filter like as following:

<FieldPicker
  context={context}
  filter="Title eq 'Birthday'"
/>

The above code is just an example to show how to use the property, in a real world scenario you can do some more advanced filtering than the one showed here.

After filtering

Aside of the filter property there’s the possibility to apply one more layer of filtering that will be applied after the previous property. To specify this filtering layer you will have to use the filterItems property and to do so you will have to specify a function where you can filter the array of retrieved fields. In the code snippet only the fields that contains the string Date will be shown:

<FieldPicker
  context={context}
  filterItems={(fields: ISPField[]) => {
    return fields
      .filter(f => f.Title !== undefined && 
              f.Title.indexOf("Date") > -1);
  }}
/>

Just for reference the ISPField type is imported with a different statement than the one used to import the FieldPicker control:

import { ISPField } from '@pnp/spfx-controls-react';

Set selected fields

The last property that I want to cover in this blog post is the selectedFields one. This property allows to specify an array of fields that you want to be selected and that’s achieved in the following way:

<FieldPicker
  context={context}
  selectedFields={["Title", "Hobbies", "Nickname"]}
/>

Conclusions

The FieldPicker is a very customizable control, can be very useful and above all is a ready to use control that you can include in your SPFx solution. It can be pretty handy in case you need to allow the user to select a SharePoint field.

I covered most of the control’s properties in this post, but in case you want to know more you can have a look at the official documentation.

Hope this helps!