DOCSEARCHbyAlgolia
Submit Docs

PnP Modern Search Documentation

repository·main·Indexed 19 days ago

https://github.com/microsoft-search/pnp-modern-search

An open-source solution for building search-driven experiences in the SharePoint modern experience. Includes guidance on creating custom search results templates using Handlebars, implementing extensibility libraries via @pnp/modern-search-extensibility, and migrating from v1.x to v2.0.0.

Tokens
92.7K
Snippets
143
Records
323
Agent score
65%

What's inside PnP Modern Search

  1. Overview of PnP Modern Search v4

    main

    PnP Modern Search v4 is a collection of SharePoint Online modern Web Parts designed for SharePoint super users, webmasters, and developers. It enables the creation of highly flexible and personalized search-driven experiences.

    Unlike previous versions, v4 is architected to leverage the Microsoft Graph Search APIs and provides a modern extensibility model that allows developers to use web components and custom solutions beyond simple HTML/Handlebars templates.

  2. Overview of PnP Modern Search v3 Components

    main

    The v3 solution is an SPFx-based toolkit for building custom SharePoint search experiences. It consists of four main pillars:

    1. Search Web Parts (search-parts): A complete set of SPFx web parts including Search Box, Search Results, Search Filters, Pagination, and Verticals. It supports Handlebars templating and dynamic data connections.
    2. Search Extensibility Library (search-extensibility-library): An SPFx library used to create custom React components wrapped as web components. These can be embedded directly into Handlebars templates for complex, granular UI behavior.
    3. Search Custom Renderer (search-custom-renderer): An SPFx application customizer that allows you to completely override the results display using a single, unique React component.
    4. Search Query Enhancer (search-query-enhancer): A sample Azure Function project demonstrating how to use Microsoft LUIS and other cognitive services to interpret user intent and enhance queries.

  3. Explore PnP Modern Search implementation scenarios

    main

    The PnP Modern Search solution provides various recipe-based scenarios to help you build specific search experiences in SharePoint. These scenarios range from basic search pages to advanced implementations like multilingual term store support, dynamic URL-driven results, and custom metadata panels.

    Common implementation patterns include:

    • Basic Search: Creating simple search pages using PnP Search Box and PnP Search Results.
    • Filtering: Building pages with refiners (filters) and making column values clickable links to pre-apply filters (requires version 4.22.0 or later).
    • Verticals: Implementing search verticals to segment content (e.g., separating documents from sites) either on a single page or across multiple pages.
    • Specialized Search: Creating People Search experiences, Department web parts, or specialized views for birthdays and work anniversaries.
    • Advanced UI/UX: Adding 'More Info' flyout panels for metadata, using query rules for promoted links, and building dedicated document viewer pages using iframes.

  4. Available builtin layouts for Search Results

    main

    The PnP Modern Search Results web part provides several built-in layouts for displaying search results.

    Important Note: When switching between layouts in the property pane, all previous layout-specific configuration properties are lost. This is intended to prevent the Web Part property bag from being cluttered with unused configurations from other layouts.

    Available Layouts:

    • Cards: A grid-based layout using cards.
    • Details List: A list view providing detailed information.
    • Slider: A carousel-style layout.
    • Simple list: A lightweight, minimal list view.
    • People: Optimized for displaying user/people results.
    • Debug: Used for debugging purposes.
    • Custom: Allows for fully custom templates using Handlebars.

  5. Available builtin layouts for Search Filters

    main

    The PnP Modern Search solution provides several built-in layouts for displaying search filters. These layouts determine how filter options are arranged and how they interact with the search results page. The available built-in layouts are:

    • Vertical: Typically used for a sidebar-style filter arrangement.
    • Horizontal: Suitable for top-of-page filter bars.
    • Panel: A collapsible or overlay-style panel for filters.
    • Debug: A layout intended for troubleshooting and inspecting filter data.
    • Custom: Allows for user-defined layouts when built-in options do not meet specific requirements.

  6. Identify available Search Web Parts in v3

    main

    The PnP Modern Search v3 solution provides several specialized Web Parts for SharePoint modern pages:

    • Search Box Web Part: Enables users to enter free text or KQL (Keyword Query Language) queries. It is designed to connect to a Search Results Web Part.
    • Search Results Web Part: Executes static or dynamic search queries. It supports customizable parameters, sorting, and templating.
    • Search Refiners: Provides users with the ability to configure and use refiners to filter results from a Search Results Web Part.
    • Search Verticals: Allows users to switch between predefined search scopes.

  7. Available search result layouts in v3

    main

    The search results Web Part in v3 provides several built-in layouts that rely on Handlebars templates. Note that some layouts use web components wrapping Office UI Fabric React controls (like DetailsList or DocumentCard), which means you can only customize them via provided template options and placeholders rather than direct HTML markup manipulation.

    Available layouts include:

    • Simple List: A basic list with previews.
    • Details List: A tabular view using the Office UI Fabric DetailsList control.
    • Document Card: A card-based view using the Office UI Fabric DocumentCard control.
    • Carousel/Slider: A slider view powered by the Flickity library.
    • Debug View: A read-only view displaying search result items and the global Handlebars context.
    • People View: A layout specifically designed to display people/personas.

  8. Understand available built-in data sources

    main

    PnP Modern Search provides several built-in data sources that can be selected via the web part property pane. The primary available data sources are:

    • SharePoint Search: Uses the SharePoint search engine to retrieve results from SharePoint sites.
    • Microsoft Search: Uses the Microsoft Search API to retrieve results.

    Important Note on Configuration: When you switch the data source in the property pane, all previously configured properties for the old data source are lost. This behavior is intentional to prevent the web part property bag from being cluttered with unused configurations from different data sources.

  9. Understand PnP Modern Search authentication and permissions

    main

    PnP Modern Search does not use a dedicated Azure AD/Entra ID App Registration or Enterprise Application. Instead, it leverages existing authentication flows:

    • SharePoint Search API: Uses FedAuth cookies from SharePoint.
    • Graph APIs: Uses the existing SharePoint Online Client Extensibility app registrations.

    Security Model: The solution uses Delegated Permissions only. It does not elevate permissions; all API calls are bound to the permissions of the current user interacting with the web part, not the solution itself.

  10. Understand 'Static' vs 'Refiner' filter types

    main

    The Filters Web Part supports two distinct logic types:

    1. Refiner Filter: The filter values are dynamically retrieved from the data source. If the search results contain no values for a specific field, no refiner values will be displayed. These require a connection to a Search Results Web Part.
    2. Static Filter: The filter provides its own arbitrary values regardless of the data source results. Examples include date range pickers. Static filters do not strictly require a Search Results connection to display their options.

  11. Configure Result Types in templates

    main

    Instead of using complex conditional logic in a single template, you can use the Result Types feature to split templates based on result characteristics (e.g., file type, category). This can be configured via the property pane in 'inline' mode or using an external file.

    Supported operators for defining result types:

    • Equals, Not equals, Contains, StartsWith, Greater Or Equal, Less Or Equal, Less than, Greater than, Is not null.

    To implement this in your template, use the {{#> resultTypes}} partial. The block inside will act as the default template if no specific result type conditions are met.

    Note: The order of evaluation is determined by the sorting option in the web part configuration.

    {{#> resultTypes}}
  {{!-- Default item template if no result types matched --}}
  <div class="template_result">
      <!-- Your default template markup -->
  </div>
{{/resultTypes}}

  12. Process values as filters vs tokens in item selection

    main

    When connecting web parts, you must choose how the selected values are passed to the data source:

    Process values as filters

    Values are sent as standard filters, identical to how the Search Filters Web Part operates.

    • Requirement: The selected source field must be a valid filter for the current data source.
    • Example: If using SharePoint Search or Microsoft Search, the field must be a refinable managed property.

    Process values as tokens

    Values are injected manually into the data source query using the token {filter.source_field.valueAsText}. This is useful when you want to filter by a property that is not a refinable managed property.

    KQL Token Examples (SharePoint/Microsoft Search)

    ScenarioToken SyntaxResulting KQL Example
    Single ValueTitle:{filters.Title.valueAsText}Title:docx
    Multi-Value (OR){|Title:{filters.Title.valueAsText}}(Title:docx) OR (Title:pdf)
    Multi-Value (AND){&Title:{filters.Title.valueAsText}}(Title:docx) AND (Title:pdf)
    // Single Value
Title:{filters.Title.valueAsText}

// Multi Values (OR condition)
{|Title:{filters.Title.valueAsText}}

// Multi Values (AND condition)
{&Title:{filters.Title.valueAsText}}