Post
Ask Question

PnP Placeholder Control For SPFx

Overview

 
SharePoint Framework web part usually offers configurable web part properties to configure itself. The values for web part properties can be set up later by the end-user to configure it as per the need. If the needed properties are not set on the web part, the same should be notified to the end-user in a graceful way. PnP (Patterns and Practices) offers Placeholder control to show the message for pending configurations.
 
During this article, we will explore the Placeholder control from PnP on how to use and configure it in SPFx web part. We will develop a practical scenario to integrate Placeholder control in SPFx web part.
 

Develop SharePoint Framework Web Part

 
Open a command prompt. Create a directory for SPFx solution.
  1. md spfx-pnp-placeholder  
Navigate to the above-created directory.
  1. cd spfx-pnp-placeholder  
Run the Yeoman SharePoint Generator to create the solution.
  1. yo @microsoft/sharepoint  
Yeoman generator will present you with the wizard by asking questions about the solution to be created.
 
 
Solution Name: Hit Enter to have default name (spfx-pnp-placeholder in this case) or type in any other name for your solution.
Selected choice - Hit Enter
 
Target for the component: Here we can select the target environment where we are planning to deploy the client web part; i.e. SharePoint Online or SharePoint On-Premises (SharePoint 2016 onwards).
Selected Choice: SharePoint Online only (latest)
 
Place of files: We may choose to use the same folder or create a sub-folder for our solution.
Selected Choice: Same folder
 
Deployment option: Selecting Y will allow the app to be deployed instantly to all sites and will be accessible everywhere.
Selected Choice: N (install on each site explicitly)
 
Permissions to access web APIs: Choose if the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant.
Selected choice: N (solution contains unique permissions)
 
Type of client-side component to create: We can choose to create a client-side web part or an extension. Choose web part option.
Selected Choice: WebPart
 
Web part name: Hit Enter to select the default name or type in any other name.
Selected Choice: PnPPlaceholder
 
Web part description: Hit enter to select the default description or type in any other value.
Selected Choice: Use PnP Placeholder control in SPFx solution
 
Framework to use: Select any JavaScript framework to develop the component. Available choices are No JavaScript Framework, React, and Knockout.
Selected Choice: React
 
Yeoman generator will perform a scaffolding process to generate the solution. The scaffolding process will take a significant amount of time.
 
Once the scaffolding process is completed, lock down the version of project dependencies by running the below command.
  1. npm shrinkwrap  
In the command prompt type below command to open the solution in the code editor of your choice.
  1. code .  

NPM Packages Dependency

 
@pnp/spfx-controls-react (https://sharepoint.github.io/sp-dev-fx-controls-react/)
 
SharePoint framework React control is an open-source library which offers a reusable set of React controls to be used in SPFx solution.
On the command prompt, run below command to include the npm package.
  1. npm install @pnp/spfx-controls-react --save  

Pass the context from web part to React Component

 
We will have to pass the SharePoint context from our web part to the React component to be used in Placeholder control.
 
Open React component properties at “src\webparts\pnPPlaceholder\components\IPnPPlaceholderProps.ts”
 
Add below properties.
  1. import { WebPartContext } from '@microsoft/sp-webpart-base';  
  2. import { DisplayMode } from '@microsoft/sp-core-library';  
  3.   
  4. export interface IPnPPlaceholderProps {  
  5.   description: string;  
  6.   displayMode: DisplayMode;  
  7.   context: WebPartContext;  
  8. }  
From our web part (src\webparts\pnPPlaceholder\PnPPlaceholderWebPart.ts) pass the context to React component,
  1. export default class PnPPlaceholderWebPart extends BaseClientSideWebPart<IPnPPlaceholderWebPartProps> {  
  2.   
  3.   public render(): void {  
  4.     const element: React.ReactElement<IPnPPlaceholderProps> = React.createElement(  
  5.       PnPPlaceholder,  
  6.       {  
  7.         description: this.properties.description,  
  8.         displayMode: this.displayMode,  
  9.         context: this.context  
  10.       }  
  11.     );  
  12.   
  13.     ReactDom.render(element, this.domElement);  
  14.   }  
  15.      .  
  16.      .  
  17.      .  
  18. }  

Use Placeholder Control in the SPFx Web Part

 
During the implementation, we will use Placeholder control to notify the user for missing configuration, if the out of box description property is not set. We will show the description when set instead of Placeholder control.
 
On the command prompt, type below command to open the solution in the code editor of your choice.
  1. code .  
Open the React component file at “src\webparts\pnPPlaceholder\components\PnPPlaceholder.tsx”
 
Add below imports.
  1. import { Placeholder } from "@pnp/spfx-controls-react/lib/Placeholder";  
  2. import { DisplayMode } from '@microsoft/sp-core-library';  
Use the Placeholder control in the render method as follows.
  1. export default class PnPPlaceholder extends React.Component<IPnPPlaceholderProps, {}> {  
  2.   public render(): React.ReactElement<IPnPPlaceholderProps> {  
  3.     return (  
  4.       <div className={styles.pnPPlaceholder}>  
  5.         <div className={styles.container}>  
  6.           <div className={styles.row}>  
  7.             <div className={styles.column}>  
  8.               <span className={styles.title}>Welcome to SharePoint!</span>  
  9.               <p className={styles.subTitle}>Customize SharePoint experiences using Web Parts.</p>  
  10.   
  11.               {/* Show Placeholder control, when description web part property is not set */}  
  12.               {this.props.description === "" &&  
  13.                 <Placeholder iconName='Edit'  
  14.                   iconText='Configure your web part'  
  15.                   description='Please configure the web part.'  
  16.                   buttonLabel='Configure'  
  17.                   hideButton={this.props.displayMode === DisplayMode.Read}  
  18.                   onConfigure={this._onConfigure} />  
  19.               }  
  20.   
  21.               {/* Show description web part property, when set */}  
  22.               {this.props.description &&  
  23.                 <p className={styles.description}>{escape(this.props.description)}</p>  
  24.               }  
  25.             </div>  
  26.           </div>  
  27.         </div>  
  28.       </div>  
  29.     );  
  30.   }  
  31.   
  32.   private _onConfigure() {  
  33.     // Context of the web part  
  34.     this.props.context.propertyPane.open();  
  35.   }  
  36. }  
The onConfigure property defines the action to be executed on the button click event (e.g. opening the property pane).
 

Test the PnP Placeholder Control

  1. On the command prompt, type “gulp serve”.
  2. Open SharePoint site.
  3. Navigate to /_layouts/15/workbench.aspx
  4. Locate and add the webpart (named PnPPlaceHolder) to page.
The web part by default is displayed as below (when the description web part property is set).
 
 
When the description web part property is not set, it will prompt the user to configure the web part.
 
 

Summary

 
In this article, we explored the practical use of Placeholder control in SPFx web part. The Placeholder control helps to show a message to the end-user if the web part configuration is pending.


Similar Articles