This solution supports different levels of customizations depending your requirements:
- 'Basic' customizations: these include custom settings for data sources, search box, verticals and filters Web Parts + minor updates to existing layouts by adding custom HTML markup (ex: add a custom field in the UI from a data source), updates to builtin layouts fields ('Cards','Details List' and 'People'), etc. They only require HTML, CSS and Handlebars skills to be done. Typically a super user or a webmaster could do that.
- 'Advanced' customizations: these include major updates like adding a new data source, layout, component or suggestions provider. These are build from scratch and require SharePoint Framework development skills to be done. Typically, a front-end/SharePoint developer could do that.
Extensibility samples are centralized in a dedicated repository: https://github.com/microsoft-search/pnp-modern-search-extensibility-samples/tree/main
'Basic' customizations cover the layout templates updates with HTML, CSS and Handlebars. Refer to the templating documentation to know more.
The solution uses the concept of 'extensibility libraries'. Basically, these are SharePoint Framework library components you put in the global or site collection app catalog that will be loaded automatically by Web Parts to enhance the experience and options (ex: new data source with new options, custom layout, etc.). Simple as that!
As a demonstration of capabilities, all builtin data sources, layouts, web components or suggestions providers are built using the same exact interfaces and methods that are publicly available in the
@pnp/modern-search-extensibilitySPFx library project.
All documentation procedures for extensions are based on the demo extensibility library available in the same repository that you can use as reference.
For your project to be a valid extensibility library, you must have the following prerequisites:
- Your project must be an SPFx library component.
- The main entry point of your library must implement the
IExtensibilityLibraryinterface from the
- You library manifest ID must be registered in the Web Part where you want to use the extension.
The SPFx library project must use the same SPFx version as the main solution (currently
1.12.1). Owherwise you may face issues at build time. See GitHub issue #1893
Each Web Part type in the solution supports several extensions or no extension at all. It means even your extensibility library contains all possible extensions, they won't be loaded if the Web Part does not support them.
|Web Part type||Supported extensions|
Register your extensibility library with a Web Part¶
When a Web Part type supports one or multiple extensions, you can register them going to the last property pane confguration page in the 'Extensibility configuration' section:
From here, you can add the manifest IDs of your libraries and decide to enable or disabled certain libraries. The manifest ID can be found in the
Multiple librairies can be registred for a single Web Part instance allowing you to split your extensions into multiple projects (in the end, they will be all concatenated). For instance, this could be convenient when extensions come from different IT providers.
Create an extensibility library¶
To create an extensibility library, you have the choice to reuse the one provided in the GitHub repository or start from scratch. In this case:
- Create a new SharePoint Framework project of type 'Library' with
- Add an npm reference to
npm i @pnp/modern-search-extensibilitycmd.
- In the main entry point, implement the
IExtensibilityLibraryinterface. Provide all method implementations (return empty arrays if you don't implement specific extensions).
Implement your extension(s) depending of the type:
Creation process always follows more or less the same pattern:
- Create the extension data logic or render logic.
- Register the information about the extension to be discovered and instanciated by the target Web Part by implementing the corresponding method according to the
gulp bundle --shipand package
gulp package-solution --shipand add the solution to the global or site collection catalog (for this one, it must be the same site collection where the Web Part loading that extension(s) is present).
- Register your manifest ID in the target Web Part instance.
Debug a library component¶
Debugging a library component is exactly the same as debugging an SPFx Web Part. Run
gulp serve in the hosted workbench and put a 'Search Results','Search Filters' or 'Search Box' Web Part depending the extension you want to test. If registered correctly, your breakpoints will be triggerred by the main Web Part loading your extension.