Enhance web part configuration using the PnP Placeholder control

Introduction

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

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

The control is used to display a panel with (or without) the presence of a button that allows the user to open the property pane.

Visual appearance

Starting with the visual appearance of the control I’ve defined a couple of instances of the control to show what are the possible variations available.

In this sample I’ve set the control instances to appear only when the page is in edit mode. If the page is not in edit mode the control will simply show a title and a message.

Once the page enters edit mode the controls will be displayed. In the screenshot there are two instances where, as you can see, there are some small differences.

The first instance has a button to open the property pane. In the second instance I’ve changed the icon, the secondary text, and the presence of the button.

In the following screenshot, just for reference, I want to show how’s the sample property pane.

I would say that’s enough for the visual appearance, let’s switch to the code!

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 Placeholder.

---

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

import { Placeholder } from "@pnp/spfx-controls-react/lib/Placeholder";

Second thing to do is to declare the context property, in the components properties, to pass the web part context to the component. In the sample this is achieved as follows:

import { WebPartContext } from "@microsoft/sp-webpart-base";
import { DisplayMode } from "@microsoft/sp-core-library";

export interface IPnPPlaceholderControlProps {
  context: WebPartContext;
  displayMode: DisplayMode;
}

The context property is used to open the property pane when clicking on the configure button.

Aside of the web part context I also imported DisplayMode to show the control only when the web part is in edit mode. After importing the control and preparing the component properties you can start using it. Let’s cover each of the instances from the sample solution in a little bit more detail.

Show me the code

After specifying the import of the control it’s easy to use it. Simply create an instance of the control and define the needed properties.

The following is the code relative to the first instance of the control:

<Placeholder 
  iconName='CaseSetting'
  iconText={strings.PlaceholderIconText}
  description={strings.PlaceholderDescription}
  buttonLabel={strings.PlaceholderButtonLabel}
  onConfigure={this._onConfigure} />

The properties defined here are the following:

• iconName: the name of the Fluent UI icon to display.
• iconText: this is the text that will be displayed aside of the icon.
• description: this is the text that will be inserted in the body of the control.
• buttonLabel: is the text that will be inserted in the configure button.
• onConfigure: will contain the method to be called when the user clicks on the configure button.

The _onConfigure method define what the button will do. The method will use the web part context’s property propertyPane to open the web part property pane.

private _onConfigure = (): void => {
  this.props.context.propertyPane.open();
}

The second instance is to demonstrate how to hide the configure button. To hide it simply define the hideButton property and set it to false:

<Placeholder 
  iconName='AutoEnhanceOn'
  iconText={strings.PlaceholderIconText}
  description={strings.PlaceholderDescriptionWithoutButton}
  hideButton={true} />

Conclusions

The Placeholder control is a no brainer component that allows you to enhance the user experience when it comes to enhance the web part configuration process.

In the sample I’ve displayed the instances only when the page is in edit mode, but it’s also possible to show the control when the web part is not yet configured. In this fashion a user will know immediately that the web part needs some configuration.

Hope this helps!