Panel for ListView Command Set extensions

Summary

This control renders stateful Panel that can be used with ListView Command Set extensions. It may optionally refresh the list view page after the panel is closed. It opens when a List Command button is clicked, and closes using either Panel's close button, or on "light dismiss".

It may be used to replace Dialog component, ensuring the User Interface is consistent with that of SharePoint Online.

Compatibility

As of SPFx 1.16:

• Node.js v12 & v14 are no longer supported. SPFx v1.16 requires Node.js v16.
• @microsoft/office-ui-fabric-react-bundle is DEPRECATED. Use @fluentui/react instead.

Applies to

• SharePoint Framework
• Microsoft 365 tenant

Get your own free development tenant by subscribing to Microsoft 365 developer program

Prerequisites

SPFx development environment compatibility:

SPFx	Node.js (LTS)	NPM	TypeScript	React	@fluentui/react
1.16.1	v16.13+	v5, v6, v7, v8	v4.5	v17.0.1	v8

Important: In order to use React plug-in for Application Insights JavaScript SDK components, set "allowSyntheticDefaultImports": true in tsconfig.json.

Use @fluentui/react v8 for compatibility with React v17

Solution

Solution	Author(s)
spfx-panel	Kinga Kazala

Version history

Version	Date	Comments
1.3	February 02, 2023	Correct version of @fluentui/react
1.2	January 20, 2023	Upgrade to SPFx 1.16 which requires Node.js v16. Application Insights support
1.1	March 28, 2022	Upgrade to SPFx 1.14, Update item using pnp V3
1.0	January 13, 2022	Initial release

Disclaimer

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

---

Minimal Path to Awesome

• Clone this repository
• Ensure that you are at the solution folder
• in the command-line run:
  • nvm use 16.18.x (the 16.x.x node version you have installed)
  • npm install
  • gulp serve --nobrowser (or gulp serve --nobrowser --locale=de-de to test German version)
  • debug

See Debugging SPFx 1.13+ solutions on creating debug configurations.

Features

Opening and closing Panel controls is a no-brainer as long as it is controlled by a parent component. In the case of a ListView Command Set, this requires slightly more effort.

This extension illustrates the following concepts:

• Panel component with an AppInsightsErrorBoundary
• Logging using @pnp/logging Logger, configured to use ConsoleListener and (if application insights connection string is provided), custom AppInsightsLogListener
• page tracking and event tracking with Application Insights
• Example component using Panel, with a Toggle control to refresh the page when the panel is closed

React Error Boundary

As of React 16, it is recommended to use error boundaries for handling errors in the component tree. Error boundaries do not catch errors for event handlers, asynchronous code, server side rendering and errors thrown in the error boundary itself; try/catch is still required in these cases. This solution uses AppInsightsErrorBoundary component.

Avoiding "The security validation for this page is invalid and might be corrupted"

"The security validation for this page is invalid and might be corrupted" issue only occurs when the spfi() object and spfx behavior is instantiated multiple times during the lifecycle of a web part. See: pnp/pnpjs#2304

PnP Logger

Logging is implemented using @pnp/logging module. Log level is defined as an extension property, which allows changing log level of productively deployed solution, in case troubleshooting is required.

Errors returned by @pnp/sp commands are handled using Logger.error(e), which parses and logs the error message. If the error message should be displayed in the UI, use the handleError function implemented based on Reading the Response example.

Application Insights

This solution is using Application Insights for webpages and React plug-in for Application Insights JavaScript SDK to log errors and metrics to application insights.

Deploy

Install solution

# -Scope accepted values: Tenant, Site
$packageInSite = Add-PnPApp -Path "$sppkgPath" -Scope $appCatalogScope -Overwrite -Publish
if ( $null -eq $packageInSite.InstalledVersion ) {
    Write-Host "Installing app $($packageInSite.Id) ..."
    Install-PnPApp -Identity $packageInSite.Id -Scope $appCatalogScope -Wait
}
elseif ($packageInSite.CanUpgrade -eq $true) {
    Write-Host "Updating installed app $($packageInSite.Id) ..."
    Update-PnPApp -Identity $packageInSite.Id -Scope $appCatalogScope
}

In case you are not using the elements.xml file for deployment, you may add the custom action using Add-PnPCustomAction

Add-PnPCustomAction -Title "Panel" -Name "panel" -Location "ClientSideExtension.ListViewCommandSet.CommandBar" -ClientSideComponentId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -ClientSideComponentProperties "{""listName"":""Travel Requests"",""logLevel"":""3"",""appInsightsConnString"":""your-connection-string""}" -RegistrationId 100 -RegistrationType List -Scope Web

Updating the properties in an already deployed solution can be done with:

$ca=Get-PnPCustomAction -Scope Web -Identity "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$ca.ClientSideComponentProperties="{""listName"":""Travel Requests"", ""logLevel"":""1"",""appInsightsConnString"":""your-connection-string""}"
$ca.Update()

References

• Getting started with SharePoint Framework
• Microsoft 365 Patterns and Practices - Guidance, tooling, samples and open-source controls for your Microsoft 365 development
• Debugging SPFx 1.13+ solutions
• Professional SPFx Solutions: Superb solution packages
• PnP Error Handling
• PnP log levels
• https://pnp.github.io/pnpjs/logging/#create-a-custom-listener
• React plug-in for Application Insights JavaScript SDK
• React Error Boundaries in React 16, and React error boundaries
• I Made a Tool to Generate Images Using Office UI Fabric Icons to generate CommandSet icons

React

It is recommended to use function components instead of class components in the new code.

• Understanding Functional Components vs. Class Components in React
• Components and Props
• Understanding the importance of the key prop in React
• Understanding React's key prop