Extensibility possibilities

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.

Note

Extensibility samples are centralized in a dedicated repository: https://github.com/microsoft-search/pnp-modern-search-extensibility-samples/tree/main

Basic customizations

'Basic' customizations cover the layout templates updates with HTML, CSS and Handlebars. Refer to the templating documentation to know more.

Advanced customizations

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-extensibility SPFx 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.

Prerequistes

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 IExtensibilityLibrary interface from the @pnp/modern-search-extensibility library.
  • You library manifest ID must be registered in the Web Part where you want to use the extension.

Supported extensions

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
Search Results
  • Custom web components.
  • Custom Handlebars customizations (ex: helpers, partials ,etc.).
Search Filters
  • Custom web components (not directly but via the 'Search Results' Web Part extensibility library registration).
Search box
  • Custom suggestions providers.
Search Verticals None.

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:

"Extensibility configuration"

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 <your_library_name>.manifest.json file:

"Library manifest ID"

"Extensibility manifests registration"

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:

  1. Create a new SharePoint Framework project of type 'Library' with yo @microsoft/sharepoint.
  2. Add an npm reference to @pnp/modern-search-extensibility library using npm i @pnp/modern-search-extensibility cmd.
  3. In the main entry point, implement the IExtensibilityLibrary interface. Provide all method implementations (return empty arrays if you don't implement specific extensions). "Extensibility interface implementation"
  4. Implement your extension(s) depending of the type:

    Creation process always follows more or less the same pattern:

    1. Create the extension data logic or render logic.
    2. Register the information about the extension to be discovered and instanciated by the target Web Part by implementing the corresponding method according to the IExtensibilityLibrary interface.
  5. Bundle gulp bundle --ship and package gulp package-solution --ship and 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).

  6. Register your manifest ID in the target Web Part instance.
  7. Enjoy!

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.