Guido Zambarda

Posted on Feb 10 • Originally published at iamguidozam.blog on Feb 5

Discover how to use the PropertyFieldColumnPicker from the PnP property controls

#pnp #spfx #pnpspfxpropertycontrol

Introduction

Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldColumnPicker control.

The PnP reusable property pane controls is a package that contains a lot of useful controls that can be used in any SharePoint Framework web part’s property pane, if you want to know more about this you can check out the official site here.

To demonstrate the various capabilities of the control I’ve created a sample solution which you can find here. The sample solution contains a simple web part that shows how the PropertyFieldColumnPicker works.

Visual Appearance

Before switching to the code section I want to cover the resulting user interface. Since the PropertyFieldColumnPicker control is used in the web part property pane I will cover only the property pane interface.

The sample solution web part has two properties pages, the first is to select the list from which to load the columns.

Starting with the first page:

The second property pane page, with the actual control instances, looks like the following:

Let’s have a closer look at the control instances present in the second property pane page.

The minimal instance shows how the control displays with the minimal configuration and the default behavior.

The control displays as a dropdown with all the visible fields:

As usual, if needed, there is the possibility to disable the control:

It’s also possible to add a custom validation on the selected value. For example it’s possible to show an error if a certain field is selected. In this instance selecting the Title field results in an error message:

It’s possible to enable the multi selection in two different fashion. It’s possible to show a drop down control with check boxes or a list of check boxes. In the following screenshot there are both of the instances:

I didn’t cover all the control instances here because the visual appearance is pretty much the same. What change is the behavior and the code behind the visual appearance. Let’s cover all the instances in the code section!

Show me the code

Prerequisites

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

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

After the installation of the package you can proceed with the following explanations for the PropertyFieldColumnPicker control.

To use the control you have to import it in the web part file with the following statement:

import {
  IColumnReturnProperty,
  IPropertyFieldRenderOption,
  PropertyFieldColumnPicker,
  PropertyFieldColumnPickerOrderBy,
} from "@pnp/spfx-property-controls";

To enable the control to set the properties of the web part I defined the following interface:

export interface IPnPPropertyColumnPickerWebPartProps {
  list: string;
  minimal: string;
  column: string;
  multiColumn: string;
  multiColumnChoiceGroup: string;
  onErrorColumn: string;
  orderByColumn: string;
  columnReturnProperty: string;
  deferredColumn: string;
}

The list property is used to select the list from which to load the fields. This is achieved using the PropertyFieldListPicker, if you want to know more you can have a look at my previous post here.

Inside the web part getPropertyPaneConfiguration function I defined the various control instances, let’s cover those!

Minimal configuration instance

This instance shows what is the minimal configuration required for the control to work. As you can see from the code there are some required properties, let’s have a look at the control instance and then at each single property:

PropertyFieldColumnPicker("minimal", {
  label: strings.MinimalInstance,
  context: this.context,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "minimalColumnPickerFieldId",
})

Now let’s see what are those required properties:

label: the text that will be displayed as title of the control.
context: the web part context.
listId: the id of the list from where to load the columns.
onPropertyChange: the web part onPropertyPaneFieldChanged method.
properties: the web part properties.
key: a string that represent a unique identifier for the control instance.

Single column instance

This control instance shows how, using a single selection behavior, it’s possible to retrieve the selected value from the web part properties using the selectedColumn control property.

PropertyFieldColumnPicker("column", {
  label: strings.SingleColumnInstance,
  context: this.context,
  selectedColumn: this.properties.column,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "singleColumnPickerFieldId",
}),

The value for the selectedColumn property has to be the column id.

Disabled instance

As usual it’s possible to disable a control if needed. This can be achieved by setting the disabled property to true.

PropertyFieldColumnPicker("column", {
  label: strings.DisabledInstance,
  context: this.context,
  selectedColumn: this.properties.column,
  listId: this.properties.list,
  disabled: true,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "disabledColumnPickerFieldId",
}),

Order by instance

This instance shows how to enable ordering the columns. The ordering can be achieved by setting the orderBy property.

PropertyFieldColumnPicker("orderByColumn", {
  label: strings.OrderByInstance,
  context: this.context,
  selectedColumn: this.properties.orderByColumn,
  listId: this.properties.list,
  orderBy: PropertyFieldColumnPickerOrderBy.Id,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "orderByColumnPickerFieldId",
}),

The possible values that can be set are the following:

Id: order by the Id of the column.
Title: order by the title of the column.

Deferred selection instance

It’s possible to defer the selection of the column by a specific timing. This can be achieved specifying a numeric value (milliseconds) to the deferredValidationTime.

PropertyFieldColumnPicker("deferredColumn", {
  label: strings.DeferredInstance,
  context: this.context,
  selectedColumn: this.properties.deferredColumn,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  deferredValidationTime: 1000,
  key: "deferredColumnPickerFieldId",
}),

Column return property instance

The default behavior of the control, when a column is selected, is to return the column id. This can be not the best approach, maybe what you need is the title of the column. It’s possible, using the columnReturnProperty, and setting the value using the IColumnReturnProperty interface.

PropertyFieldColumnPicker("columnReturnProperty", {
  label: strings.ReturnPropertyInstance,
  context: this.context,
  selectedColumn: this.properties.columnReturnProperty,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "returnPropertyColumnPickerFieldId",
  columnReturnProperty: IColumnReturnProperty["Internal Name"],
}),

The IColumnReturnProperty possible values are the following:

Id: obviously the id of the column, this is the default value.
Title: this is the display name of the column.
Internal Name: the internal name of the column.

On error instance

When needed is possible to perform a custom validation. To perform a custom validation when a column is selected you can use the onGetErrorMessage. This method accepts the selected value and returns a string value. If the returned string is empty, the validation is considered successful. If there is an error, the error message is returned.

PropertyFieldColumnPicker("onErrorColumn", {
  label: strings.OnErrorInstance,
  context: this.context,
  selectedColumn: this.properties.onErrorColumn,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  columnReturnProperty: IColumnReturnProperty["Internal Name"],
  onGetErrorMessage: (value: string) => {
    return value === "Title" ? "Title is not allowed" : "";
  },
  key: "onErrorColumnPickerFieldId",
}),

In the above sample code the validation is performed checking that the selected column is not the Title field.

Multi column instance

Specifying the property multiSelect to true it’s possible to enable the selection of multiple columns. This renders a dropdown with a checkbox for each of the column options.

PropertyFieldColumnPicker("multiColumn", {
  label: strings.MultiColumnInstance,
  context: this.context,
  selectedColumn: this.properties.multiColumn,
  listId: this.properties.list,
  orderBy: PropertyFieldColumnPickerOrderBy.Title,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "multiColumnPickerFieldId",
  multiSelect: true,
}),

Multi selection using choice

When the multi selection is enabled, it’s possible to specify a different display options. Instead of showing the options in a dropdown control it’s possible to display a list of the available columns with a checkbox for each of the options. This can be achieved using the renderFieldAs property.

PropertyFieldColumnPicker("multiColumnChoiceGroup", {
  label: strings.MultiColumnChoiceInstance,
  context: this.context,
  selectedColumn: this.properties.multiColumnChoiceGroup,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  key: "multiColumnChoicePickerFieldId",
  multiSelect: true,
  renderFieldAs: IPropertyFieldRenderOption["Choice Group"],
}),

The property accept an IPropertyFieldRenderOption value, this interface exposes the following options:

Choice Group: this shows the columns in a list with a checkbox for each items.
Multiselect Dropdown: this shows a dropdown control and, for each option, a checkbox to select the item.

Show hidden columns instance

By default the hidden columns are not included in the list of selectable items. This behavior can be changed simply by setting the displayHiddenColumns to true.

PropertyFieldColumnPicker("showHiddenColumn", {
  label: strings.ShowHiddenColumnsInstance,
  context: this.context,
  selectedColumn: this.properties.column,
  listId: this.properties.list,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  displayHiddenColumns: true,
  key: "showHiddenColumnPickerFieldId",
}),

Conclusions

The PropertyFieldColumnPicker is a very useful control when it comes to enable the selection of the columns of a specific SharePoint list. This can be handy if you need to enable the selection of a column in the property pane of a web part.

I didn’t cover all the available properties of the control, if you want to discover more you can visit the official documentation here.

Hope this helps!

DEV Community