Merge branch 'microsoft-search:main' into main

davemehr · Feb 7, 2024 · 3f828be · 3f828be
2 parents 4e17636 + 4331f4f
commit 3f828be
Show file tree

Hide file tree

Showing 130 changed files with 65,608 additions and 67,347 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -18,10 +18,10 @@ jobs:
               with:
                   ref: develop
             # setup nodejs
-            - name: Use Node.js 14
+            - name: Use Node.js 16
               uses: actions/setup-node@v2
               with:
-                  node-version: 14
+                  node-version: 16
                   registry-url: "https://registry.npmjs.org"
             # cache node modules
             - name: Cache node modules

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -21,7 +21,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [16.x]
 
     outputs: 
       majorMinorPatch: ${{ steps.setoutputs.outputs.majorMinorPatch }}

diff --git a/README.md b/README.md
@@ -24,6 +24,15 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 
 ## "Sharing is Caring"
 
+## "PnP Modern Search Office Hours"
+If you are stuck on an issue or just need a peer review of your PnP Modern Search based idea, we have Office Hours.
+
+You can sign up for a 15 min timeslot and a member of the community will set up a Teams call, where you can show and tell about the issue.
+Office hours is every second Tuesday at mid afternoon UTC(0). 
+
+Sign up [here](https://aka.ms/pnp/modernsearchofficehours), and please note that not all requests might be granted if there are more requests than timeslots.
+
+
 ## Disclaimer
 
 **THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
diff --git a/docs/assets/NoAccessError.png b/docs/assets/NoAccessError.png
diff --git a/docs/assets/extensibility/web_components/breadcrumb_component.png b/docs/assets/extensibility/web_components/breadcrumb_component.png
diff --git a/docs/assets/installation-enable-app.png b/docs/assets/installation-enable-app.png
diff --git a/...emplate/custom_search-results-example.png → ...emplate/custom_search-results-example.png b/...emplate/custom_search-results-example.png → ...emplate/custom_search-results-example.png
diff --git a/...sert_external-url-for-custom-template.png → ...sert_external-url-for-custom-template.png b/...sert_external-url-for-custom-template.png → ...sert_external-url-for-custom-template.png
diff --git a/...plate/myfirsttemplate_file-screenshot.png → ...plate/myfirsttemplate_file-screenshot.png b/...plate/myfirsttemplate_file-screenshot.png → ...plate/myfirsttemplate_file-screenshot.png
diff --git a/...arepoint/open_htmlfile-in-text-editor.png → ...arepoint/open_htmlfile-in-text-editor.png b/...arepoint/open_htmlfile-in-text-editor.png → ...arepoint/open_htmlfile-in-text-editor.png
diff --git a/...s-in-sharepoint/save_the-changed-file.png → ...s-in-sharepoint/save_the-changed-file.png b/...s-in-sharepoint/save_the-changed-file.png → ...s-in-sharepoint/save_the-changed-file.png
diff --git a/...nedrive/open-template-folder-onedrive.png → ...nedrive/open-template-folder-onedrive.png b/...nedrive/open-template-folder-onedrive.png → ...nedrive/open-template-folder-onedrive.png
diff --git a/...search-page-and-see-result-of-changes.png → ...search-page-and-see-result-of-changes.png b/...search-page-and-see-result-of-changes.png → ...search-page-and-see-result-of-changes.png
diff --git a/...drive/sync-or-addshortcut-to-onedrive.png → ...drive/sync-or-addshortcut-to-onedrive.png b/...drive/sync-or-addshortcut-to-onedrive.png → ...drive/sync-or-addshortcut-to-onedrive.png
diff --git a/...int/central-repository-multiple-sites.png → ...int/central-repository-multiple-sites.png b/...int/central-repository-multiple-sites.png → ...int/central-repository-multiple-sites.png
diff --git a/...int/custom-template-external-url-edit.png → ...int/custom-template-external-url-edit.png b/...int/custom-template-external-url-edit.png → ...int/custom-template-external-url-edit.png
diff --git a/...n-sharepoint/sharepoint-resources-lib.png → ...n-sharepoint/sharepoint-resources-lib.png b/...n-sharepoint/sharepoint-resources-lib.png → ...n-sharepoint/sharepoint-resources-lib.png
diff --git a/...rios/create-your-first-custom-template.md → ...outs/create-your-first-custom-template.md b/...rios/create-your-first-custom-template.md → ...outs/create-your-first-custom-template.md
diff --git a/...os/edit-custom-templates-in-sharepoint.md → ...ts/edit-custom-templates-in-sharepoint.md b/...os/edit-custom-templates-in-sharepoint.md → ...ts/edit-custom-templates-in-sharepoint.md
diff --git a/...it-templates-using-vscode-and-onedrive.md → ...it-templates-using-vscode-and-onedrive.md b/...it-templates-using-vscode-and-onedrive.md → ...it-templates-using-vscode-and-onedrive.md
diff --git a/...o-store-custom-templates-in-sharepoint.md → ...o-store-custom-templates-in-sharepoint.md b/...o-store-custom-templates-in-sharepoint.md → ...o-store-custom-templates-in-sharepoint.md
diff --git a/docs/create-custom-layouts/index.md b/docs/create-custom-layouts/index.md
@@ -0,0 +1,24 @@
+
+
+
+If you are looking for inspiration, you can find a selection of custom layouts in the 
+[Custom layouts repository](https://github.com/microsoft-search/pnp-modern-search-layouts/blob/main/README.md)
+
+If you have a custom layout you want to share, please submit a PR to the repository.
+
+
+## [Scenario Create your first custom template](create-your-first-custom-template.md)
+
+Create your first custom template
+
+## [Store custom templates in SharePoint](howto-store-custom-templates-in-sharepoint.md)
+
+Storing custom templates as files in a SharePoint site, is great when you want to use them across sites and want some control.
+
+## [Edit custom templates in SharePoint](edit-custom-templates-in-sharepoint.md)
+
+Storing custom templates as files in a SharePoint site, is great when you want to use them across sites and want some control.
+
+## [Edit custom templates locally in Visual Studio Code](edit-templates-using-vscode-and-onedrive.md)
+
+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.
diff --git a/docs/extensibility/index.md b/docs/extensibility/index.md
@@ -54,7 +54,7 @@ From here, you can add the manifest IDs of your libraries and decide to enable o
 
 [!["Extensibility manifests registration"](../assets/extensibility/extensibility_configuration_manifest.png){: .center}](../assets/extensibility/extensibility_configuration_manifest.png)
 
-> 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.
+> Multiple librairies can be registered 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
 
@@ -179,4 +179,4 @@ export class MyCustomLibraryComponent implements IExtensibilityLibrary {
 }
 ```
 
-In order to run the above sample code, you will need to import in your library the following npm packages: `@microsoft/sp-component-base`, `@microsoft/sp-core-library`, and `@microsoft/sp-webpart-base`.  
+In order to run the above sample code, you will need to import in your library the following npm packages: `@microsoft/sp-component-base`, `@microsoft/sp-core-library`, and `@microsoft/sp-webpart-base`.  
diff --git a/docs/extensibility/templating.md b/docs/extensibility/templating.md
@@ -237,7 +237,7 @@ If no placeholder is present in the template, a default one will be loaded.
 
 > The Microsoft Graph Toolkit is a collection of reusable, framework-agnostic web components and helpers for accessing and working with Microsoft Graph. The components are fully functional right of out of the box, with built in providers that authenticate with and fetch data from Microsoft Graph.
 
-In the solution, you can use Graph Tookit components whitout the need to re-authenticate against Microsoft Graph because the Web Parts already use the [SharePoint provider](https://docs.microsoft.com/en-us/graph/toolkit/providers/sharepoint).
+In the solution, you can use Graph Tookit components without the need to re-authenticate against Microsoft Graph because the Web Parts already use the [SharePoint provider](https://docs.microsoft.com/en-us/graph/toolkit/providers/sharepoint).
 
 Refer to the official documentation to see [all available components](https://docs.microsoft.com/en-us/graph/toolkit/components/login). For instance, we use the Microsoft Graph Toolkit for the [people layout](../usage/search-results/layouts/people.md) via `<mgt-person>`.
 

diff --git a/docs/extensibility/web_components_list.md b/docs/extensibility/web_components_list.md
@@ -10,6 +10,7 @@ Here are the list of all **reusable** web components you can use to customize yo
 - [&lt;pnp-collapsible&gt;](#ltpnp-collapsiblegt)
 - [&lt;pnp-persona&gt;](#ltpnp-personagt)
 - [&lt;pnp-img&gt;](#ltpnp-imggt)
+- [&lt;pnp-breadcrumb&gt;](#ltpnp-breadcrumbgt)
 
 > All other web components you will see in builtin layout templates are considered **internal** and are not supported for custom use.
 
@@ -189,7 +190,8 @@ Here are the list of all **reusable** web components you can use to customize yo
     data-secondary-text="Unknown"
     data-tertiary-text=""
     data-optional-text="514 928 0000"
-    data-persona-size="" >
+    data-persona-size=""
+    data-native-lpc=true >
 </pnp-persona>
 ```
 
@@ -201,6 +203,7 @@ Here are the list of all **reusable** web components you can use to customize yo
 |**data-tertiary-text**|The tertiary text to display (ex: work phone).
 |**data-optional-text**|The optional text to display.
 |**data-persona-size**|The size of the persona **item** to display (no only the picture). Valid values are <ul><li>tiny = 0</li><li>extraExtraSmall = 1</li><li>extraSmall = 2</li><li>small = 3</li><li>regular = 4</li><li>large = 5</li><li>extraLarge = 6</li></ul>
+|**data-native-lpc**|Enable SharePoint native Live Persona Card on hover.
 
 ## `<pnp-img>` 
 - **Description**: Display an image with support for fallback behavior.
@@ -214,4 +217,51 @@ Here are the list of all **reusable** web components you can use to customize yo
 | Parameter | Description |
 | --------- | ----------- |
 |**errorImage**|URL to the fallback image
-|**hideOnError**|Hide image on error
+|**hideOnError**|Hide image on error
+
+## `<pnp-breadcrumb>` 
+- **Description**: Render a breadcrumb path of a SharePoint entity (file, item, folder, document library etc.).
+
+!["Breadcrumb component"](../assets/extensibility/web_components/breadcrumb_component.png){: .center}
+
+- **Usage**:
+
+Get started with:
+```html
+<pnp-breadcrumb 
+    data-path="{{OriginalPath}}"
+    data-site-url="{{SPSiteURL}}"
+    data-web-url="{{SPWebUrl}}"
+    data-entity-title="{{Title}}"
+    data-entity-file-type="{{FileType}}"
+/>
+```
+Use all properties:
+```html
+<pnp-breadcrumb 
+    data-path="{{OriginalPath}}"
+    data-site-url="{{SPSiteURL}}"
+    data-web-url="{{SPWebUrl}}"
+    data-entity-title="{{Title}}"
+    data-entity-file-type="{{FileType}}"
+    data-include-site-name="false" 
+    data-include-entity-name="true"
+    data-breadcrumb-items-as-links="true"
+    data-max-displayed-items="3"
+    data-overflow-index="0"
+    data-font-size="12"
+/>
+```
+|Parameter|Description|
+|--|--|
+|data-path|Used for creating the breadcrumb path. Component is designed to receive `OriginalPath` or `Path` property. Property is required for rendering the breadcrumb path. `String`|
+|data-site-url|Used for creating the breadcrumb path. Component is designed to receive `SPSiteURL` property. Property is required for rendering the breadcrumb path. `String`|
+|data-web-url|Used for creating the breadcrumb path. Component is designed to receive `SPWebUrl` property. Property is required for rendering the breadcrumb path. `String`|
+|data-entity-title|Used for creating the breadcrumb path. Component is designed to receive `Title` property. Property is required for rendering the breadcrumb path. `String`|
+|data-entity-file-type|Used for creating the breadcrumb path. Component is designed to receive `FileType` property. Property is required for rendering the breadcrumb path. `String`|
+|data-include-site-name|If the site name should be included in the breadcrumb items. Optional, default value `true`. `Boolean`|
+|data-include-entity-name|If the entity name should be included in the breadcrumb items. If the value is set to `false`, not only is the entity name excluded from the breadcrumb path, but also the last item in the breadcrumb path is not highlighted in bold. Optional, default value `true`. `Boolean`|
+|data-breadcrumb-items-as-links|If the breadcrumb items should be clickable links to the path they represent. Optional, default value `true`. `Boolean`|
+|data-max-displayed-items|The maximum number of breadcrumb items to display before coalescing. If not specified, all breadcrumbs will be rendered. Optional, default value `3`. `Int`|
+|data-overflow-index| Index where overflow items will be collapsed. Optional, default value `0`. `Int`|
+|data-font-size|Font size of breadcrumb items. Optional, default value `12`. `Int`|
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,20 +1,21 @@
 # Installation
 
-1. Download the latest SharePoint Framework packages **pnp-modern-search-parts.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
-2. Add **pnp-modern-search-parts.sppkg** to the global tenant app catalog or a site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one. 
+1. Download the latest SharePoint Framework packages **pnp-modern-search-parts-v4.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
+2. Add **pnp-modern-search-parts-v4.sppkg** to the global tenant app catalog or a site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one. 
 
-    !["App Catalog "](./assets/app_catalog.png){: .center}
+    !["App Catalog "](./assets/installation-enable-app.png){: .center}
 
     > * The packages are deployed in the general Office 365 CDN meaning **we don't host any code**.
 
-    > * For the **pnp-modern-search-parts.sppkg** package, you can choose to make the solution available in [all sites](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/tenant-scoped-deployment) or force to install an app to the site every time.
+    > * For the **pnp-modern-search-parts-v4.sppkg** package, you can choose to make the solution available in [all sites](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/tenant-scoped-deployment) or force to install an app to the site every time.
 
     > * The solution asks the following API permissions by default to enhance the experience. These permissions are **not mandatory**. If you don't accept them, you will simply have less available features.
 
     > * You can approve scopes from the API Access screen in the SharePoint Admin Center: https://&lt;tenant&gt;-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx#/webApiPermissionManagement If you'd like more details on this step, please see the [Approving Scopes](#approving-scopes) section below.
 
     | Requested API permission | Used for |
     | -------------- | --------- |
+    | _Presence.Read.All_ | Read presence information of all users in your organization.
     | _User.Read_ | The Microsoft Graph Toolkit [persona card](https://docs.microsoft.com/en-us/graph/toolkit/components/person-card#microsoft-graph-permissions) in the people layout.  |
     | _People.Read_ | Same as above.
     | _Contacts.Read_ | Same as above.
@@ -27,9 +28,9 @@
     | _Bookmark.Read.All_ | Allow search for Bookmarks in Microsoft Search in your organization.
     | _Acronym.Read.All_ | Allow search for Acronyms in Microsoft Search in your organization.
     | _Chat.Read_ | Allow search for Teams messages.
-    | _ChannelMessage.Read.All_ | Same as above.
+    | _ChannelMessage.Read.All_ | Read user channel messages.
 
-3. Add the Web Parts to a SharePoint and start building!
+4. Add the Web Parts to a SharePoint and start building!
 
 !["Available Web Parts"](./assets/webparts.png){: .center}
 
@@ -44,3 +45,14 @@ You'll need to approve each request one at a time. If you have questions about w
 After you approve each request your view will be as shown in the screenshot below.
 
 !["App Catalog"](./assets/api-access-approved.jpg){: .center}
+
+
+## Note about Guest users
+
+By default guest users do not have access to the App Catalog. So if you are not using the CDN option, any SPFx web part from the App Catalog will show an error message for guest users:
+![No Access Error](./assets/NoAccessError.png){: .center}
+
+There are basicly two options to solve this issue,
+give guest users access to the App Catalog (read) or use the CDN option.
+
+see [this](https://laurakokkarinen.com/sharepoint-online-guest-user-troubles-and-how-to-get-past-them/) for more information.
diff --git a/docs/scenarios/Setup-Results-web-part-to-show-birthdays.md b/docs/scenarios/Setup-Results-web-part-to-show-birthdays.md
@@ -0,0 +1,37 @@
+
+A common requirement for intranets is to show birthdays of employees and as the SharePoint User Profile Application has a property for birthdays, it is a natural choice to use search to show birthdays of employees. In addition, at the time of writing (2023), the Graph API does not have a property for birthdays, so we can't use the Graph API to get the information.
+
+
+The tricky part is that in the User profile application the birthday value is store is a rather unusual datatype: "date no year"
+
+![Birthday in the User Provisioning Service](../scenarios/assets/Setup-Results-web-part-to-show-birthdays/BirthdayUPA.png)
+
+
+In my tenant the SPS-Birthday property was mapped to RefinableDate00 and the actual value in the property is 2000-[the date]:
+
+![Managed Property value](../scenarios/assets/Setup-Results-web-part-to-show-birthdays/RefinableDate00.png)
+
+(use the magnificent [SP Editor tool](https://chrome.google.com/webstore/detail/sp-editor/ecblfcmjnbbgaojblcpmjoamegpbodhd) or [SP Search Query Tool](https://github.com/pnp/PnP-Tools/blob/master/Solutions/SharePoint.Search.QueryTool/README.md) to inspect the managed properties)
+
+
+
+So, the query had to be something like "those accounts where RefinableDate00 = 2000 + the value of today's date
+
+
+
+In KQL we have the token "today" that will give us today's date, but as far as I know, we can't get the components the date consist of, like Month and Day.
+
+Luckily, the PnP Modern search provides additional Tokens, see [Tokens](https://microsoft-search.github.io/pnp-modern-search/usage/search-results/tokens/)
+
+
+
+So the final query is:
+
+**RefinableDate00=2000-{CurrentMonth}-{CurrentDate}T00:00:00Z**
+
+
+
+( and of cause a criteria to exclude former employees, like SPS-HideFromAddressLists<>1) 
+
+![Birthday web part](../asserts/../scenarios/assets/Setup-Results-web-part-to-show-birthdays/birthdays.png)
+