Merge branch 'release/4.5.4' into main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -8,15 +8,16 @@ assignees: ''
 ---
 
 ### Check existing issues before logging new ones
+If you are not using the latest version, triage your issue with the latest version before logging as we won't provide patches to older versions.
 
-### Issues related to data mapping, e.g. SharePoint columns to crawled properties to managed properties, will be closed by default and should be asked elsewhere as it's outside the scope of this project. However if you cannot repro the issue with classic web parts, then it's ok as it relates to these web parts 🙂
+### Issues related to data mapping, e.g. SharePoint columns to crawled properties to managed properties should be asked in the discussion section.
 
 **For any question regarding Web Parts usage, please use the ["Discussions"](https://github.com/microsoft-search/pnp-modern-search/discussions) tab instead of creating a new issue.**.
 
 __Remove the above section before submitting, and removal of the below template will result in the issue being closed.__
 
 **Version used**
-Ex: 4.2
+Ex: 4.5
 
 **Describe the bug**
 A clear and concise description of what the bug is. Keep questions and bugs related to the web parts. If the issue relates to KQL or question around crawled and managed properties please use [Microsoft TechCommunity](https://techcommunity.microsoft.com/t5/sharepoint-developer/bd-p/SharePointDev). Which means, if you experience the same behavior in classic web parts, then it's not an issue with PnP Modern Search 😉

docs/scenarios/Create-a-search-page-with-verticals-within-the-same-page.md

@@ -0,0 +1,66 @@
+# Scenario 8 - Create a search page with verticals (within the same page)
+
+!!! note
+    The PnP Modern Search Web Parts must be deployed to your App Catalog and activated on your site. See the [installation documentation](../installation.md) for details.
+
+This scenario describes how to configure multiple Search Verticals on the same page.
+
+## Create a new sharepoint page
+
+To add the Search Web Parts, you must first create a new modern SharePoint page. We will be configure this new page as a search page with the PnP Modern Search Web Parts.
+
+![Create a page](assets/Create-a-search-page-with-verticals-within-the-same-page/Create-a-page.png)
+
+## Add PnP Search Web Parts
+
+On the newly created page, add the PnP Modern Search Web Part Search Box, Search Verticals, and Search Results, twice.
+
+![Add PnP Web Parts](assets/Create-a-search-page-with-verticals-within-the-same-page/Add-PnP-Web-Parts.png)
+
+The Web Parts can be arranged and configured on the page as desired.
+
+![Search Web Parts](assets/Create-a-search-page-with-verticals-within-the-same-page/Search-Web-Parts.png)
+
+## Configure Search Box
+
+You can leave the default configuration.
+
+![Configure Search Box Web Part](assets/Create-a-search-page-with-verticals-within-the-same-page/Configure-Search-Box-Web-Part.png)
+
+## Configure Search Vertical
+
+In the Search Verticals Web Part, the verticals (tabs) must be configured.
+
+![Search Vertical](assets/Create-a-search-page-with-verticals-within-the-same-page/Search-Vertical.png)
+
+Insert the tab name and a fluent icon for e better visualization. The results are on the same page, so a link URL are not necessary.
+
+![Configure Search Vertical Web Part](assets/Create-a-search-page-with-verticals-within-the-same-page/Configure-Search-Vertical-Web-Part.png)
+
+## Configure first Search Result Web Part
+
+The first Results Web Part displays all results. Select the data source SharePoint and the result source "LocalSharePointResults".
+
+![First Result Web Part Vertical Everything](assets/Create-a-search-page-with-verticals-within-the-same-page/First-Result-Web-Part-Vertical-Everything.png)
+
+In the "available connections" section, the connection to the Search Box and the Search Vertical must be configured. The results web part should only be displayed if the vertical "Everything" is active.
+
+![First Result  Web Part connection](assets/Create-a-search-page-with-verticals-within-the-same-page/First-Result-Web-Part-connection.png)
+
+## Configure second Search Result Web Part
+
+The second results web part displays results from the predefined result source knowledge, configures the result source in the SharePoint admin center, and the GUID must be added to the Web Part.
+
+![Second Result Web Part Vertical Knowledge](assets/Create-a-search-page-with-verticals-within-the-same-page/Second-Result-Web-Part-Vertical-Knowledge.png)
+
+In the "available connections" section, the connection to the Search Box and the Search Vertical must be configured again. The Results Web Part should only be displayed if the vertical "Knowledge" is selected.
+
+![Second Result Web Part connection](assets/Create-a-search-page-with-verticals-within-the-same-page/Second-Result-Web-Part-connection.png)
+
+After that, the minimum configuration is complete and the search page must be saved and published. The configuration can be customized, and a different layout can be used for the search results per Results WebPart.
+
+## Testing your configuration
+
+Now the query from the Search Box is sent to the verticals, depending on the choice of the verticals, the results are then displayed in the search result.
+
+![Test Your Search page](assets/Create-a-search-page-with-verticals-within-the-same-page/Test-Your-Search-page.png)

docs/scenarios/index.md

@@ -44,7 +44,12 @@ Storing custom templates as files in a SharePoint site, is great when you want t
 
 When you have your templates in SharePoint, it is easy to setup a way to edit locally on your computer and still get the result in SharePoint almost instantly.
 
+## Scenario 8
 
+[Create a search page with verticals (within the same page)](Create-a-search-page-with-verticals-within-the-same-page.md)
+
+Search verticals can be used to selectively search specific content per vertical. Using the SharePoint provider you can use result sources to limit the content returned,
+or you can add the required KQL in the web part itself. This sample shows how to set up multiple search verticals on the same page.
 
 ---
 

docs/usage/search-filters/index.md

@@ -32,7 +32,7 @@ The filter settings are as follow:
 |------------|-----------------|
 | **Display Name** | A friendly name for the filter |
 | **Filter field** | The internal data source field to use as filter. Here you can select a field from the current data source (if data have been already retrieved) of type your own custom value (press enter to validate).
-| **# of values** | The maximum number of filter values/buckets to return (may be restricted by the API).
+| **# of values** | The maximum number of values to be retrieved for a given filter. This value is useful if you use SharePoint refiners with a lot of refiner values. By default SharePoint will only retreve the first 100 values. To get all refiner values, you must specify an higher number manually (maximum value is 1000).
 | **Template** | The template to use to display filter values. The builtin templates are: </br><ul><li>**Check box** <p align="center">!["Check box"](../../assets/webparts/search-filters/checkbox_template.png)</p></li><li>**Date range** <p align="center">!["Date range"](../../assets/webparts/search-filters/daterange_template.png)</p></li><li>**Date interval** <p align="center">!["Date interval"](../../assets/webparts/search-filters/dateinterval_template.png)</p></li><li>**Combo** <p align="center">!["Combo"](../../assets/webparts/search-filters/combo_template.png)</p></br> You can search a value directly in the list by typing keywords in the combo text field.</li></ul>
 | **Filter type** | Specify if the filter is a 'static' filter or a 'refiner' filter. See below for more information.
 | **Expand by default** | If applicable for the selected template, display values as expanded.

docs/usage/search-results/connections/item-selection.md

@@ -59,6 +59,8 @@
 
 !!! info "Filtering general behavior"
 
-- `null` ou `empty` filters values **are ignored** in the resulting query.
+- If the source selected item field is `null` ou `empty`:
+    * It will be replaced by the FQL expression `string('')` expression if the mode is **Process values as filters**
+    * It will be resolved as an empty string if the mode is **Process values as tokens**.
 - Duplicate values are trimmed (ex: user select items with the same filter values).
 - Filter values should be 'string' values. All other types will be ignored (ex: 'objects' from JSON response).

docs/usage/search-results/data-sources/sharepoint-search.md

@@ -9,11 +9,12 @@ The _'SharePoint Search'_ data source retrieve items from the SharePoint search
 | **Query text** | The input query text to pass to the search engine. This setting is not configurable directly in the data source options. To enable it, go to the third configuration page of the Web Part and select either a static or dynamic value (Ex: from a connected search box Web Part). See [the connection documentation](../../search-results/connections/index.md) for more information on how to configure this option. This value can be then used in the **Query template** using the `{searchTerms}` token. Also this value can be a [Keyword Query Language expression (KQL)](https://docs.microsoft.com/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference). | None.
 | **Query template** | The search query template to use. It allows you to use dynamic tokens according to the context or specifiy conditions that should always apply to the query. | `{searchTerms}`
 | **Result source ID** | Can be either a built-in result source ID listed in the dropdown, or a custom result source that you specify. Type the `GUID` of the result source, or the `SCOPE` and `NAME`, separated by `\|` (pipe character). For this to take effect, you must press _'Enter'_ to save the value. Valid scopes are `SPSiteSubscription`, `SPSite`, `SPWeb`. Examples: <ul><li>SPWeb`\|`Local News</li><li>SPSite`\|`Contracts</li><li>SPSiteSubscription`\|`Intranet</li></ul> | LocalSharePointResults
-| **Selected properties** | The SharePoint managed properties to retrieve from the results. They can be used with the same name in layouts and slots afterwards.<br/><br/>To add other managed properties to the list, clear out the dropdown list field and type or paste the name of your managed property and press return. This will add it to the list of selected properties in the query. Pasting a comma separated list of property names also work. You can validate the property is working by using the [Debug](../layouts/#debug) layout. | <ul><li>Title</li><li>Path</li><li>DefaultEncodingURL</li><li>FileType</li><li>HitHighlightedSummary</li><li>AuthorOWSUSER</li><li>owstaxidmetadataalltagsinfo</li><li>Created</li><li>UniqueID</li><li>NormSiteID</li><li>NormListID</li><li>NormUniqueID</li><li>ContentTypeId</li><li>UserName</li><li>JobTitle</li><li>WorkPhone</ul>
+| **Selected properties** | The SharePoint managed properties to retrieve from the results. They can be used with the same name in layouts and slots afterwards.<br/><br/>To add other managed properties to the list, clear out the dropdown list field and type or paste the name of your managed property and press return. This will add it to the list of selected properties in the query. Pasting a comma separated list of property names also work. You can validate the property is working by using the [Debug](../layouts/#debug) layout. | <ul><li>Title</li><li>Path</li><li>DefaultEncodingURL</li><li>FileType</li><li>HitHighlightedProperties</li><li>HitHighlightedSummary</li><li>AuthorOWSUSER</li><li>owstaxidmetadataalltagsinfo</li><li>Created</li><li>UniqueID</li><li>NormSiteID</li><li>NormListID</li><li>NormUniqueID</li><li>ContentTypeId</li><li>UserName</li><li>JobTitle</li><li>WorkPhone</li><li>SPSiteUrl</li><li>SiteTitle</li><li>CreatedBy</li><li>HtmlFileType</li><li>SiteLogo</li></ul>
 | **Sort order** | The initial results sort order. You will be able to select only _'Sortable'_ managed properties here. Make sure the selected  properties satisfy this criteria in the [SharePoint search schema](https://docs.microsoft.com/sharepoint/technical-reference/crawled-and-managed-properties-overview). | None.
 | **Refinement filters** | The initial refinement filters to apply to the query. Filters has to be written using FQL ([Fast Query Language](https://docs.microsoft.com/sharepoint/dev/general-development/fast-query-language-fql-syntax-reference)) (e.g. `FileType:equals("docx")`). They will be applied every time to the current search query regardless selected filters from connected Web Parts. Note: for string expressions, use `"` instead of `'`. | None.
 | **Language of the search request** | The language to use for the search request. By default the search request will be made using the current user interface language. This parameter is mainly used to process diacritics, plurals, etc. correctly according to the language. | Current UI language.
 | **Enable query rules** | Whether or not apply SharePoint query rules. | False.
 | **Enable audience targeting** | Whether or not results should be targeted according to the audiences that the current user belongs to. [More information about modern audiences and how to configure them](https://support.microsoft.com/office/target-navigation-news-and-files-to-specific-audiences-33d84cb6-14ed-4e53-a426-74c38ea32293). | False.
 | **Enable localization** | If enabled, the Web Part will try to translate the taxonomy term IDs found in result item properties and refinement values to their corresponding label according to the curent UI language. To get it work, you must map a new refinable managed property associated with `ows_taxId_` crawled property and turn this toggle 'on': <a href="../../../../assets/webparts/search-results/localization_crawled_property.png"><img src="../../../../assets/webparts/search-results/localization_crawled_property.png"/></a> If enabled and depending on how many items are currently being displayed, this could slightly decrease the loading performance. </br></br>**To use translated values in your template, you must use the '`Auto + <property_name>`' property format instead of the original property name**. For instance, to use translated values of the '_owstaxidmetadataalltagsinfo_' property, you must use the '**Auto**owstaxidmetadataalltagsinfo' auto created property.   | False.
+| **Hit-highlighted properties** | The list of SharePoint managed properties (separated by a comma) to return hit highlighted information (whether the search query match each specified managed property or not).<p><b>Note:</b> **HitHighlightedProperties** will be null if there is a field in **Hit-highlighted properties** doesn't exist in  **Selected properties** </p> | None. 
 

docs/usage/search-results/layouts/index.md

@@ -42,7 +42,8 @@ For all layouts, some common settings are available:
 
 | Setting | Description | Default value 
 | ------- |---------------- | ---------- |
-| **Show a 'See all' link** | Allows you to specify a 'See all' link at the top right of the Web Part along the Web Part title. You can set the text that will appear plus the link to use. Tokens are supported in the link URL. <p align="center">!["Common options"](../../../assets/webparts/search-results/layouts/see_all_link.png)</p> | Disabled.
+| **Allow items selection** | If enabled, allow items to be selected in default layouts. See [documentation](../connections/item-selection.md) for usage. | Disabled.
+| **Allow multiple selection** | If the item selection is allowed, specifiy if users can select multiple items | Disabled.
 | **Hide this web part if there's nothing to show** | If there is no results, the Web Part will remain blank in display mode (title and 'See all' link included). In edit mode, you will see a message indicating there is no results. <p align="center">!["Common options"](../../../assets/webparts/search-results/layouts/hide_webpart.png)</p> | Disabled.
 | **Show results count** | Hide or display the results count for the current query. | Enabled.
 | **Use Microsoft Graph Toolkit** | Enable or disable the Microsoft Graph Toolkit to be used in Handlebars template. Refer to the [MGT documentation](https://docs.microsoft.com/en-us/graph/toolkit/overview) to see available components.

docs/usage/search-results/tokens.md

@@ -9,8 +9,6 @@ You can use tokens in the following locations:
         - **SharePoint Search**
             - Query template field.
             - Refinement filters field.
-    - Layouts
-        - In the _'See all'_ link.
 
 - **Search Verticals Web Part**
     - In the link URL when the vertical item is a link.