Merge branch 'main' into patch-3

Author: andrewconnell

docs/declarative-customization/formatting-syntax-reference.md

@@ -1,7 +1,7 @@
 ---
 title: Formatting syntax reference
 description: Formatting syntax reference
-ms.date: 02/09/2022
+ms.date: 02/22/2022
 ms.localizationpriority: high
 ---
 
@@ -19,9 +19,22 @@ Specifies the type of element to create. Valid elements include:
 - path
 - button
 - p
+- [filepreview](#filepreview)
 
 Any other value will result in an error.
 
+### filepreview
+
+Use the special elmType `filepreview` in conjunction with the `src` attribute set to [`@thumbnail.<Size>`](#thumbnails) to view thumbnails for files in your document libary. 
+If the thumbnail loads successfully, a small [brand type icon](https://developer.microsoft.com/en-us/fluentui#/styles/web/office-brand-icons) is visible on the bottom left. If the thumbanil fails to load (or if the file type doesn't support thumbnails), a [file type icon](https://developer.microsoft.com/en-us/fluentui#/styles/web/file-type-icons) is shown instead.
+
+```json
+"elmType": "filepreview",
+"attributes": {
+  "src": "@thumbnail.medium"
+ }
+```
+
 ## txtContent
 
 An optional property that specifies the text content of the element specified by `elmType`. The value of this property can either be a string (including special strings) or an Expression object.
@@ -384,6 +397,30 @@ Adds the field editor for the referenced column.
   "txtContent": "[$FieldName]"
 }
 ```
+## filePreviewProps
+
+An optional property, that allows overriding the default styles of file type icon and brand type icon in `filepreview` elmType.
+
+- `fileTypeIconClass` and `brandTypeIconClass` can be used to provide CSS class names to the file type icon and the brand type icon elements respectively.
+
+- `fileTypeIconStyle` and `brandTypeIconStyle` can be used to provide [styles](#style) to the file type icon and the brand type icon respectively. These styles will take precedence over the same styles coming from the CSS classes provided by the above 2 properties.
+
+```json
+"elmType": "filepreview",
+"attributes": {
+  "src": "@thumbnail.medium",
+ },
+"filePreviewProps": {
+  "fileTypeIconClass": "sp-css-borderColor-neutralLight",
+  "fileTypeIconStyle": {
+    "width": "100px"
+  },
+  "brandTypeIconClass": "sp-css-borderColor-neutralLight",
+  "brandTypeIconStyle": {
+    "width": "68px"
+  }
+}
+```
 
 ## Expressions
 

docs/images/image-helper-api-01.png

@@ -0,0 +1,115 @@
+---
+title: Image Helper API
+description: Learn how to use the Image Helper API in the SharePoint Framework to provide web-friendly optimized image links.
+ms.date: 02/08/2022
+ms.prod: sharepoint
+ms.localizationpriority: high
+---
+# Image Helper API
+
+The **ImageHelper** static class (in **\@microsoft\/sp-image-helper**) has been added to allow SPFx developers runtime access to:
+
+- Urls of auto-generated thumbnail images of pages and documents stored in SharePoint
+- More optimized Urls to images stored in SharePoint
+
+The helper method `ImageHelper.convertToImageUrl()` takes a Url to an asset on SharePoint, a width, and an optional height and will perform client-side operations to try to create an optimized Url.
+
+The resulting Url will point to an image that is close to the requested size. The resulting Url will also include using other SharePoint media and graph services. If available for the requested asset, public or private CDN locations to serve the resized images and thumbnails.
+
+> [!IMPORTANT]
+> The Image Helper API was introduced in the SharePoint Framework v1.14 release.
+
+## Benefits to using this API
+
+- The image may be delivered faster because it's potentially served out of a cache.
+- The image will be sized appropriately as width is required and height is optional. This allows for customers to store high-resolution images in SharePoint but not pay the download time penalty when those images are used.
+- The source Url maybe any filetype within SharePoint where a thumbnail can be generated. An image thumbnail Url would then be returned.
+
+## Explained - ImageHelper.convertToImageUrl()
+
+The `convertToImageUrl()` static method accepts a single argument of type **IImageHelperRequest**. This object has two required properties, `sourceUrl` & `width`, and one optional property `height`.
+
+SharePoint's server-side image processing has a list of resolution breakpoints widths it supports, including: 200, 400, 960, 1600, & 2560.
+
+While you can specify any width to resize the image to, SharePoint will pick the nearest largest resolution breakpoint. For example, if you specify `width: 250`, the resized image width will be 400 px.
+
+If you specify the optional `height` property, SharePoint the width isn't adjusted to the nearest breakpoint. But if the `height property is omitted, SharePoint automatically determines the height of the resized image using the width & width breakpoint while maintaining the aspect ratio for the image.
+
+> [!TIP]
+> Omitting the `height` property provides the quickest response from the SharePoint
+
+## Use the Image Helper API
+
+To use the Image Helper API, you must first install it into your project:
+
+```console
+npm install @microsoft/sp-image-helper
+```
+
+Next, import it into your project where you plan to use the API:
+
+```typescript
+import { ImageHelper, IImageHelperRequest } from "@microsoft/sp-image-helper";
+```
+
+Next, use the API to obtain a thumbnail image of an existing file in SharePoint. In this case, we've uploaded a file from the [Microsoft News Image Gallery](https://news.microsoft.com/imagegallery) site. In this example, we're using a file that's 1.2 MB in size with a resolution of 1920x1080... not an ideal web friendly format:
+
+![Screenshot of the details panel of the original image.](../images/image-helper-api-01.png)
+
+The file exists in our site's default **Documents** library:
+
+```typescript
+const originalImageUrl = '/sites/dev002/Shared%20Documents/ignite2021-m365-keynote.jpeg';
+```
+
+Use the Image Helper API to resize the image and use the new link to display the resized & optimized image:
+
+```typescript
+const resizedImage = ImageHelper.convertToImageUrl(
+  <IImageHelperRequest>{
+    sourceUrl: originalImageUrl,
+    width: 400
+  }
+);
+
+this.domElement.innerHTML = `
+  <div class="${ styles.helloWorld }">New Image</div>
+  <div><img src="${ resizedImage }" /></div>
+  <div>
+    <div>Original image URL: <a href="${originalImageUrl}">${originalImageUrl}</a>
+    <div>Resized image URL: <a href="${resizedImage}">${resizedImage}</a>
+  </div>
+`;
+```
+
+![Screenshot of resized image.](../images/image-helper-api-02.png)
+
+This resized image is only 30 kB in size with a resolution of 400x225, a significant improvement on the performance for the user. Notice the UrL of the resized image differs from the original Url we provided the helper method.
+
+## Private CDN support
+
+For the images to be available to be served from a private CDN, the following requirements must be met:
+
+- the private CDN feature must be enabled
+- the source file must be available within an origin to the CDN
+- SharePoint's server-side preprocessing must know that the web part property is an image property
+
+To make SharePoint's server-side processing aware of the image property, list the properties where image Urls are stored in the web part's **manifest.json** `imageLinkPropertyNames` property:
+
+```json
+{
+  "id": "374a1893-9b4d-4c10-bbe3-9411d74093e9",
+  "alias": "HelloWorldWebPart",
+  "componentType": "WebPart",
+  "supportedHosts": [ "SharePointWebPart" ],
+  "imageLinkPropertyNames": [ "defaultBannerImage" ],
+  "preconfiguredEntries": [{
+    "title": { "default": "HelloWorld" },
+    "properties: {
+      "defaultBannerImage": "..."
+    }
+  }]
+}
+```
+
+This allows for SharePoint's server-side rewrite logic to include the mapping of that file to private CDN when rendering the page to be sent to the client.

docs/images/image-helper-api-02.png

@@ -37,7 +37,6 @@ This release introduces a new component type, Adaptive Card Extensions (ACE), th
 - Update the Microsoft Teams SDK to v1.10.
 - Update React to v16.13.1.
 - Update TypeScript to v3.9.
-- Release of image rendering APIs for optimized performance
 - Numerous additional fixes and improvements based on issues reported by the community at https://aka.ms/spfx-issues
 
 > [!NOTE]

docs/spfx/image-helper-api.md

@@ -155,6 +155,15 @@ The default value of `isGroupNameHidden` is false.
 New property `ipAddress` has been added to `serve.json` configuration. This parameter is helpful when using Docker containers. For example, to set the serve host as '0.0.0.0'.
 This property will be explicitly used to wind up the server, meaning all debug URLs and webpack configurations will not be affected.
 
+#### Image Helper API
+
+The **ImageHelper** static class (in @microsoft/sp-image-helper) has been added to allow SPFx developers runtime access to:
+
+- Urls of auto-generated thumbnail images of pages and documents stored in SharePoint
+- More optimized Urls to images stored in SharePoint
+
+Learn more: [Image Helper API](image-helper-api.md)
+
 ## Preview Features and Capabilities
 
 Following features are still in preview status as part of the 1.14 release and should not be used in production. We are looking into releasing them officially as part of the upcoming 1.15 release.
@@ -291,6 +300,7 @@ The Select Media Action can be used to select Images from your native device. In
 
 ![Screenshot of media panel](../images/release-notes/114/media-panel.jpg)
 
+
 ## Deprecations and removed items in this release
 
 > [!IMPORTANT]

docs/spfx/release-1.13.md

@@ -1,14 +1,17 @@
 ---
 title: Advanced Card View Functionality
 description: "This tutorial builds off the tutorial 'Build your first SharePoint Adaptive Card Extension'."
-ms.date: 10/25/2021
+ms.date: 02/18/2022
 ms.prod: sharepoint
 ms.localizationpriority: high
 ---
 # Advanced Card View Functionality
 
 This tutorial builds off the following tutorial: [Build your first SharePoint Adaptive Card Extension](build-first-sharepoint-adaptive-card-extension.md)
 
+> [!IMPORTANT]
+> This feature is still preview status as part of the 1.14 release and should not be used in production. We are looking into releasing them officially as part of the upcoming 1.15 release.
+
 In this tutorial, you'll implement advanced card view functionality. You'll build off the the previous tutorial and create a card view that's powered by data in a SharePoint list.
 
 ## Create a test list
@@ -410,6 +413,45 @@ Select the **Next** button until you get to the last item in the list. The card
 
 :::image type="content" source="../../../images/viva-extensibility/lab2-ace-6.png" alt-text="Card displaying the last item in the list with only a Previous button":::
 
+## Caching Card view and ACE state
+
+Starting in SPFx v1.14, ACEs have a client-side caching layer that can be configured to store:
+
+1. The latest rendered card.
+2. The state of the ACE.
+
+### Rendering from cached Card view
+
+If the latest rendered card is stored, the Dashboard renders this cached card before the ACE is initialized, improving perceived performance.
+
+The settings for this cache can be configured by overriding the following method:
+
+  ```typescript
+  protected getCacheSettings(): Partial<ICacheSettings> {
+    return {
+      isEnabled: true, // can be set to false to disable caching
+      expiryTimeInSeconds: 86400, // controls how long until the cached card and state are stale
+      cachedCardView: () => new CardView() // function that returns the custom Card view that will be used to generate the cached card
+    };
+  }
+  ```
+  
+### Rehydrating from cached ACE state
+
+The subset of the ACE state that is cached can be configured by overriding the following method:
+
+  ```typescript
+  protected getCachedState(state: TState): Partial<TState>;
+  ```
+ 
+The object returned by this method will be serialized and cached. By default, no state is cached. In the next call to `onInit`, the deserialized value will be passed to onInit as part of the `ICachedLoadParameters`
+
+  ```typescript
+  public onInit(cachedLoadParameters?: ICachedLoadParameters): Promise<void>;
+  ```
+
+The value can then be used to rehydrate the state of the newly initialized ACE.
+
 ## Conclusion
 
 After this lab you should be familiar with:
@@ -419,3 +461,4 @@ After this lab you should be familiar with:
 - Creating and registering Card views
 - Conditionally rendering Card view elements
 - Advanced Card view manipulation
+- Caching Card view and ACE state

docs/spfx/release-1.14.md

@@ -50,7 +50,11 @@ You can also follow these steps by watching this video on the SharePoint PnP You
       }
     }
     ```
+1. In the console window, enter the following command to bundle your client-side solution:
 
+    ```console
+    gulp bundle
+    ```
 1. In the console window, enter the following command to package your client-side solution that contains the web part:
 
     ```console

docs/spfx/viva/get-started/advanced-card-view-functionality.md

@@ -412,6 +412,8 @@
       href: spfx/use-theme-colors-in-your-customizations.md
     - name: Office UI Fabric integration
       href: spfx/office-ui-fabric-integration.md
+    - name: Image Helper API
+      href: spfx/image-helper-api.md
   - name: Tools & libraries
     items:
     - name: Overview