Merge pull request #2969 from microsoft-search/develop

v4.9

docs/extensibility/custom_query_modifications.md

@@ -4,7 +4,7 @@ Custom query modifier can be added to a search result Web Part to modify search
 
 A query modifier supports:
 
-- **Modification of query text and query template**: a query modifier can alter the query text and/or the query template.
+- **Modification of query text**: a query modifier can alter the query text.
 - **Sorted modifications**: modifier can be sorted and are executed in order - but you can set a modifier to stop further modifications.
 
 ## Custom modifier creation process
@@ -38,9 +38,9 @@ Custom modifier creation process comes in two distinct steps:
 | Method | Description |
 | --------- | ---------- |
 | `onInit()`| The initialization method of your query modifier (ex: initialize your properties, etc.). You can perform asynchronous calls here. This method will be called when the provider is instanciated by the main Web Part. This is a good place to initialize any consumed services if any.
-| `modifyQuery()` | Method called to get a query modification when a search is requested(in paramter).
+| `modifyQuery()` | Method called to get a query modification when a search is requested.
 | `getPropertyPaneGroupsConfiguration()` | Returns the property pane fields to display when your query modifier is selected. These are regular SPFx property fields and groups. Query modifier properties are isolated from the other general Web Part properties under the property `queryModifierProperties`. It means you must include that path in your property pane controls get the value persisted. Defining fields or groups is not mandatory for a provider. If you don't want to expose any option, just return an empty array.
-| `onPropertyUpdate()` | The method will be called when a property pane value is updated. The main Web Part in `Reactive` mode for property pane fields.
+| `onPropertyUpdate()` | The method will be called when a property pane value is updated. The main Web Part is in `Reactive` mode for property pane fields.
 
 #### BaseQueryModifier - Properties
 
@@ -67,7 +67,7 @@ The next step is to fill information about your new query modifier. In the libra
           name: 'Custom Query Modifier',
           key: 'CustomQueryModifier',
           description: 'A demo custom query modifier from the extensibility library',
-          serviceKey: ServiceKey.create<ISuggestionProvider>('MyCompany:CustomQueryModifier', CustomQueryModifier)
+          serviceKey: ServiceKey.create<IQueryModifier>('MyCompany:CustomQueryModifier', CustomQueryModifier)
       }
     ];
   }

docs/extensibility/custom_web_component.md

@@ -126,3 +126,10 @@ public getCustomWebComponents(): IComponentDefinition<any>[] {
     ];
 }
 ```
+
+### Consume services from BaseWebComponent
+
+```typescript
+const msGraphClientFactory = this._serviceScope.consume<MSGraphClientFactory>(MSGraphClientFactory.serviceKey);
+const msGraphClient = await msGraphClientFactory.getClient();
+```

docs/extensibility/index.md

@@ -29,15 +29,15 @@ For your project to be a valid extensibility library, you must have the followin
 - You library **manifest ID** must be registered in the Web Part where you want to use the extension.
 
 !!! important "SPFx version"
-    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](https://github.com/microsoft-search/pnp-modern-search/issues/1893)
+    The SPFx library project must use the same SPFx version as the main solution (currently `1.15.2`). Owherwise you may face issues at build time. See [GitHub issue #1893](https://github.com/microsoft-search/pnp-modern-search/issues/1893)
 
 ### 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** | <ul><li>Custom web components.</li><li>Custom Handlebars [customizations](https://handlebarsjs.com/api-reference/runtime.html) (ex: helpers, partials ,etc.).</li><li>Custom event handlers for adaptive cards actions</li><li>Custom Data Sources</li></ul>
+| **Search Results** | <ul><li>Custom web components.</li><li>Custom Handlebars [customizations](https://handlebarsjs.com/api-reference/runtime.html) (ex: helpers, partials ,etc.).</li><li>Custom event handlers for adaptive cards actions</li><li>Custom Data Sources</li><li>Custom query modifier</li></ul>
 | **Search Filters** |  <ul><li>Custom web components (_not directly but via the 'Search Results' Web Part extensibility library registration_).</li></ul>
 | **Search box** | <ul><li>Custom suggestions providers.</li></ul>
 | **Search Verticals** | None.

docs/extensibility/templating.md

@@ -72,6 +72,8 @@ By default, several components are available ([see the complete list](./web_comp
 
 ### Custom CSS styles
 
+#### Default Behaviour
+
 Inside an HTML template (or layout field), you can write your own CSS styles using a <style> tag. Even better, you can inject Handlebars variables, helpers, conditional blocks, etc. right inside it and get dynamic classes or attributes
 
 ```html
@@ -90,6 +92,44 @@ Inside an HTML template (or layout field), you can write your own CSS styles usi
 
 However, all CSS rules (including `@media` rules) will be all prefixed automatically by an unique ID (**pnp-template_<Web Part instance ID>**) to make sure styles are isolated from other Web Parts on the page. We do this to avoid conflicts between classes in the global context.
 
+#### Use of CSS Layers
+
+In contrast to the automatically prefixing all styles with the web part instance id's, the style can live in its own so called layer. This way the style bleeding to the rest of the page can get avoided.
+
+Layered style in contrast to the default behavior allows mechanisms such as [container queryies](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries) and other future improvements such as [CSS Nesting](https://developer.chrome.com/articles/css-nesting/).
+
+CSS support a mechanism for isolation CSS declarations in layers. To use this mechanism specify on the style tag the data property `data-cssscope` as layer.
+
+```html
+<content id="data-content">
+    <style data-cssscope="layer">
+        .example-themePrimary a {
+            color: {{@root.theme.palette.themePrimary}};
+        }
+        ...
+    </style>
+
+    <div class="template">
+        ...
+    ...
+```
+
+This convert the CSS into the following form:
+
+```css
+    <style data-cssscope="layer">
+    @layer {
+        .example-themePrimary a {
+            color: {{@root.theme.palette.themePrimary}};
+        }
+
+        ...
+    }
+    </style>
+```
+
+Browser support for [CSS Layer](https://caniuse.com/css-cascade-layers) on can-i-use.
+
 ### Hide error message using CSS
 By default the web parts will output an error message if something goes wrong on for example API calls.
 
@@ -108,7 +148,7 @@ If you want to hide the error message you can add the following CSS in your cust
     ...
 ```
 
-### Use SharePoint theme in your templates
+### Use SharePoint contexts and theme in your templates
 
 If you need to use current site theme colors, fonts and so on you can use the `theme` property available in the `@root` Handlebars context like this:
 
@@ -131,11 +171,20 @@ If you need to use current site theme colors, fonts and so on you can use the `t
 </content>
 ```
 
+If you want to reference the current user, you can get that from a context variable like this:
+
+```html
+<div>
+Login: {{@root.context.user.loginName}}
+</div>
+```
+
+
 > You can also use this variable in the 'Details List' and 'Cards' layouts in field expresions.
 
 ![Theme usage in fields](../assets/theme_field.png)
 
-A good way to see all available values for the current theme is to switch to the debug layout and inspect these values:
+A good way to see all available context values is to switch to the debug layout and inspect the values:
 
 ![Theme properties](../assets/theme_debug.png)
 
@@ -202,7 +251,7 @@ The available data attributes you can use in your HTML template are:
 
 - `data-selection-toggle`: this boolean flag would be set on the element which should handle toggles.This could be a checkbox or a div.
 
-- `data-selection-toggle-all`: this boolean flag indicates that clicking it should toggle all selection.
+- `data-selection-all-toggle`: this boolean flag indicates that clicking it should toggle all selection.
 
 - `data-selection-disabled`: allows a branch of the DOM to be marked to ignore input events that alter selections.
 

docs/index.md

@@ -75,7 +75,11 @@ With these available customizations options, you can do pretty much anything!
 
 ## Troubleshooting
 
-If you encounter an issue, please use the GitHub issues list of [this repository](https://github.com/microsoft-search/pnp-modern-search/issues). Also, to help us to resolve your issue, you can include screenshots or error messages coming from:
+If you encounter an issue, please use the GitHub issues list of [this repository](https://github.com/microsoft-search/pnp-modern-search/issues). 
+
+However, we will ask you to verify your issue as descripted here: [Using Query tools to verify issues](/using-query-tools-to-verify-issues/)
+
+Also, to help us to resolve your issue, you can include screenshots or error messages coming from:
 
 - The faulty Web Part itself.
 - Errors displayed in the browser console (typically pressing F12).
@@ -85,6 +89,7 @@ If you encounter an issue, please use the GitHub issues list of [this repository
 
 For any issue, question or feedback, please the [official GitHub repository](https://github.com/microsoft-search/pnp-modern-search/issues). We will be happy to help you!
 
+
 ## About
 
 PnP Modern Search version 4 initially made by [Franck Cornu](https://twitter.com/FranckCornu) based on a fork of the [@aequos 'Modern Data Visualizer'](https://www.aequos.ca/) solution.
@@ -104,4 +109,4 @@ Here is the list of main contributors of the PnP Modern Search (all versions inc
 - Fabio Franzini (Apvee) - [@franzinifabio](https://twitter.com/franzinifabio)
 - Paolo Pialorsi (PiaSys.com) - [@PaoloPia](https://twitter.com/paolopia)
 - Patrtik Hellgren (SherparsGroupAB) - [@PatrikHellgren](https://twitter.com/patrikhellgren)
-- Erfan Darroudi (https://github.com/edarroudi)
+- Erfan Darroudi [@edarroudi](https://github.com/edarroudi)

docs/scenarios/Create-a-useful-People-Search.md

@@ -32,13 +32,49 @@ Connect your Search Filters Web Part to the existing Results Web Part under "Use
 ### Customize filters
 Add your own filter properties to the Search Filters. This are the properties from the UPS (= SharePoint User Profile Service), check the propertiy settings in your SharePoint Search Schema.
 
+
+
 ![configure customize filters](assets/create-a-useful-people-search/configure-customize-filters.png)
 
 ## Configure Search Results
 Use the SharePoint Search as source and configure the Search Results Web Part to show only people. Choose the existing default result source LocalPeopleResults. With the query template you can exclude admin oder system accounts. In this example, only show user with an email addess this contains mehr365.
 
 ![configure search results](assets/create-a-useful-people-search/configure-search-results.png)
 
+
+<h2>Additional options to include or exclude User Profiles</h2>
+
+*User Profiles must have a valid Email address":<br>
+<i>(WorkEmail:Mehr365.com OR WorkEmail:thebankoflondon.com)</i><br>
+This will include only those two email domains and thereby exclude everybody else, like guest users and Cloud Only users<br>
+
+*User Profiles that have been marked as "Do not show":<br>
+Try searching for <i>"SPS-HideFromAddressLists":1</i> in a tool like SP Editor or SP Query Tool ( or just use the editor for the Search Result Source )
+<br>If you see any hit then those User Profiles should most like <b>not</b> be shown in the Directory.
+The HideFromAddressLists field is actually set in MSExchange and is used to hide users in the Global Address List.
+
+*Exclude User Profiles based on text based field:<br>
+
+<i>-preferredname:admin*</i><br>
+<i>-preferredname:test*</i><br>
+<i>-preferredname:Foreign Principal*</i><br>
+<i>-accountname:spo*</i><br>
+
+
+*Exclude User Profiles that does not have a value is certain properties:<br>
+
+The requirement is that User Profiles should be excluded if the Department field is empty.<br> This can be handled by using 
+<i>owstaxIdSPShDepartment:"#8ed8c9ea-7052-4c1d-a4d7-b9c10bffea6f"</i>  <br>
+This query selects every User Profile where that has a value anywhere in the Termset "Department" in the Global Termstore. Please ensure that the GUID of the root item of the Department Termset in your tenant matches the GUID shown above.
+
+The same approach can be used for the remaining peroperties that are based on a TermSet.<br><br>
+
+*Exclude User Profiles that does have a phonenumber<br>
+
+<i>(MobilPhone:0* OR MobilPhone:1* OR MobilPhone:2* OR MobilPhone:3* OR MobilPhone:4* OR MobilPhone:5* OR MobilPhone:6* OR MobilPhone:7* OR MobilPhone:8* OR MobilPhone:9*)</i> <br>
+
+Unfortunately it is difficult to filter on a text property. The query above works but it is not pretty.
+
 ### Layout configuration
 It is a predefined people layout available for the people search. Use People as Search Results layout.
 

docs/scenarios/assets/use-query-string-in-url/readme

@@ -0,0 +1 @@
+

docs/scenarios/index.md

@@ -42,10 +42,16 @@ or you can add the required KQL in the web part itself. This sample shows how to
 ## [Create a useful People Search](Create-a-useful-People-Search.md)
 With the Modern Search Web Parts you can create a simple and useful People Search. You can search or filter people and you can show informations on the People Card when you hover.
 
-## [Use query rules for promoted links](Use-query-rules-for-promoted-links.md)
+## [Use PnP Results web part as a Department Web Part](use-search-as-a-department-webpart.md)
+With the Modern Search Web Parts you can create a simple and useful Department Web part.
 
+## [Use query rules for promoted links](Use-query-rules-for-promoted-links.md)
 With the Modern Search Web Parts you can show promoted links for important results. They will be configured with query rules in the SharePoint Search Admin Center. Promoted results will show users more informations and direct links about specific, predefined, terms they searching for.
 
+## [Use query string from URL for dynamic search](use-query-string-in-url.md)
+This scenario describes how to use query string as value in the URL from the current page. You can use URL query string parameters to build dynamic search pages.
+Use a library with metadata that you can use the query string parameter in the URL.
+
 ---
 
 More to come!

docs/scenarios/use-query-string-in-url.md

@@ -0,0 +1,59 @@
+# Use query string from url for dynamic results
+
+!!! 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 use query string as value in the URL from the current page. You can use URL query string parameters to build dynamic search pages.
+Use a library with metadata that you can use the query string parameter in the URL. The value in the query string need to match with the metadata in the library.
+
+## 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/use-query-string-in-url/Create-a-page.png)
+
+## Add PnP Search Web Parts
+On the newly created page, add an SharePoint Quick links Web Part and one PnP Modern Search Web Part - Search Results. 
+
+![Add Web Parts](assets/use-query-string-in-url/add-web-parts.png)
+
+The Web Parts can be arranged and configured on the page as desired.
+
+## Configure Search Results
+Use the SharePoint Search as source and configure a query template. In this case i will show only documents from one library with metadata in the search results. Choose the existing default result source LocalSharePointResults.
+
+![configure search results query](assets/use-query-string-in-url/configure-search-results-query.png)
+
+### Layout configuration
+You can use the default configuration.
+
+## User Query String from URL
+There are two options available to use the Query String parameter from the URL. You only need one of the options.
+
+### Option 1
+#### Configure Web Part Connections
+Activate the "use input query text" connection in the existing Results Web Part. Configure "Page environment" as source, "Query string" as page environment property, "Query parameters" as query string property. 
+You will miss the "Event" Query String from the URL on this time. Add your query string to the URL manually and your query string is available in the configuration. Use the query string "Event" in the queryParameters properties drop down in the Web Part configuration.
+
+As example:
+Full URL: https://[TENANT]/sites/[SITEURL]/SitePages/[PAGE].aspx?Event=Teams Nation&Mode=Edit
+Query String: Event=
+Value: Teams Nation
+
+![configure query string parameter](assets/use-query-string-in-url/query-string-parameter.png)
+
+### Option 2
+#### Query String in Query template
+In Option two you can use Query template to "read" the Query string parameter direct from the URL. You don't need a configured web part connection as in option one.
+
+![configure query string parameter](assets/use-query-string-in-url/query-template.png)
+
+## Add links with query string
+After the Web Part configuration create quick links in the existing SharePoint Quicklinks Web Part and use links with the query string in the URL.
+
+![add quicklinks with query string](assets/use-query-string-in-url/quicklinks-query-string.png)
+
+## Solution
+After the links are created and saved, we are ready to test the scenario.
+
+With a click (1) the URL is passed with the parameter (2) and the PnP Modern Search Results Web Part, with the connection, will read the query string value a show only documents with a matching (3).  
+![people search](assets/use-query-string-in-url/solution.png)