Add docs for thumbnails, and multi-value field operations in custom formatter.

docs/declarative-customization/column-formatting.md

@@ -337,15 +337,15 @@ This example applies `background-color` and `border-top` styles to create a data
 
 ```JSON
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-  "elmType": "div",
-  "txtContent": "@currentField",
-  "attributes": {
-    "class": "sp-field-dataBars"
-  },
-  "style": {
-    "width": "=if(@currentField > 95, '100%', toString(@currentField * 100 / 95) + '%')"
-  }
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "div",
+    "txtContent": "@currentField",
+    "attributes": {
+        "class": "sp-field-dataBars"
+    },
+    "style": {
+        "width": "=if(@currentField > 95, '100%', toString(@currentField * 100 / 95) + '%')"
+    }
 }
 ```
 
@@ -432,33 +432,221 @@ To use the sample below, you must substitute the ID of the Flow you want to run.
 
 ```JSON
 {
-	"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-	"elmType": "span",
-	"style": {
-		"color": "#0078d7"
-	},
-	"children": [
-    {
-		"elmType": "span",
-		"attributes": {
-			"iconName": "Flow"
-		}
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "span",
+    "style": {
+        "color": "#0078d7"
     },
-    {
-		"elmType": "button",
-		"style": {
-			"border": "none",
-			"background-color": "transparent",        
-			"color": "#0078d7",    
-			"cursor": "pointer"
-		},
-		"txtContent": "Send to Manager",
-		"customRowAction": {
-			"action": "executeFlow",
-			"actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
-		}          
-    }        
-  ]
+    "children": [
+        {
+            "elmType": "span",
+            "attributes": {
+                "iconName": "Flow"
+            }
+        },
+        {
+            "elmType": "button",
+            "style": {
+                "border": "none",
+                "background-color": "transparent",
+                "color": "#0078d7",
+                "cursor": "pointer"
+            },
+            "txtContent": "Send to Manager",
+            "customRowAction": {
+                "action": "executeFlow",
+                "actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
+            }
+        }
+    ]
+}
+```
+
+## Formatting multi-value fields
+You can use column formatting to apply styles to each member of a multi-value field of type Person, Lookup and Choice.
+
+### Basic text formatting
+The following image shows an example of multi-value field formatting applied to a Person field.
+
+![List of buttons that notifies all assignees of each item, first row is empty, second row reads "Send email to Loyd Barham", third row reads "Send email to all 3 members"](../images/sp-columnformatting-multi-value-0.png)
+
+This example uses the `length` operator to detect the number of members of the field, and used `join` operator to concatenate the email addresses of all members. This example hides the button when no member is found, and takes care of plurals in the text.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "a",
+    "style": {
+        "display": "=if(length(@currentField) > 0, 'flex', 'none')"
+    },
+    "attributes": {
+        "href": {
+            "operator": "+",
+            "operands": [
+                "mailto:",
+                "=join(@currentField.email, ';')"
+            ]
+        }
+    },
+    "children": [
+        {
+            "elmType": "span",
+            "style": {
+                "display": "inline-block",
+                "padding": "0 4px"
+            },
+            "attributes": {
+                "iconName": "Mail"
+            }
+        },
+        {
+            "elmType": "span",
+            "txtContent": {
+                "operator": "+",
+                "operands": [
+                    "Send email to ",
+                    {
+                        "operator": "?",
+                        "operands": [
+                            "=length(@currentField) == 1",
+                            "@currentField.title",
+                            "='all ' + length(@currentField) + ' members'"
+                        ]
+                    }
+                ]
+            }
+        }
+    ]
+}
+```
+
+### Simple HTML elements formatting
+The following image showsn an example of constructing a simple sentence from the values of a multi-value Lookup field.
+
+![Screenshot of a field reads "North America, APAC, and Europe"](../images/sp-columnformatting-multi-value-1.png)
+
+This examples uses operator `loopIndex` and `length` to identify the last member of the field, and attribute `forEach` to duplicate HTML elements.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "div",
+    "style": {
+        "display": "block"
+    },
+    "children": [
+        {
+            "elmType": "span",
+            "forEach": "region in @currentField",
+            "txtContent": {
+                "operator": "?",
+                "operands": [
+                    "=loopIndex('region') + 1 == length(@currentField)",
+                    "=', and ' + [$region.lookupValue]",
+                    {
+                        "operator": "?",
+                        "operands": [
+                            "=loopIndex('region') == 0",
+                            "[$region.lookupValue]",
+                            "=', ' + [$region.lookupValue]"
+                        ]
+                    }
+                ]
+            }
+        }
+    ]
+}
+```
+
+### Complex HTML elements formatting
+The following image showsn an example of building a list of users with pictures, email addresses and a simple counter at the top.
+
+![List with name "Owners" and 3 rows where each user in the field has a profile picture, name and email displayed, and a small gray counter of owners at top left corner that has a different color when it says 0.](../images/sp-columnformatting-multi-value-2.png)
+
+This examples uses operator `loopIndex` to control the margins all rows but the first one, and attribute `forEach` to build the list of members.
+
+```json
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "div",
+    "style": {
+        "min-height": "1.5em",
+        "flex-direction": "column",
+        "align-items": "start"
+    },
+    "children": [
+        {
+            "elmType": "div",
+            "txtContent": "=length(@currentField)",
+            "style": {
+                "border-radius": "1.5em",
+                "height": "1.5em",
+                "min-width": "1.5em",
+                "color": "white",
+                "text-align": "center",
+                "position": "absolute",
+                "top": "0",
+                "right": "1em",
+                "background-color": "=if(length(@currentField) == 0, '#ddd', '#aaa'"
+            }
+        },
+        {
+            "elmType": "div",
+            "forEach": "person in @currentField",
+            "style": {
+                "justify-content": "center",
+                "margin-top": "=if(loopIndex('person') == 0, '0', '1em')"
+            },
+            "children": [
+                {
+                    "elmType": "div",
+                    "style": {
+                        "display": "flex",
+                        "flex-direction": "row",
+                        "justify-content": "center"
+                    },
+                    "children": [
+                        {
+                            "elmType": "img",
+                            "attributes": {
+                                "src": "=[$person.picture]"
+                            },
+                            "style": {
+                                "width": "3em",
+                                "height": "3em",
+                                "border-radius": "3em"
+                            }
+                        },
+                        {
+                            "elmType": "a",
+                            "attributes": {
+                                "href": "='mailto:' + [$person.email]"
+                            },
+                            "style": {
+                                "margin-left": "0.5em"
+                            },
+                            "children": [
+                                {
+                                    "elmType": "div",
+                                    "txtContent": "[$person.title]",
+                                    "style": {
+                                        "font-size": "1.2em"
+                                    }
+                                },
+                                {
+                                    "elmType": "div",
+                                    "txtContent": "[$person.email]",
+                                    "style": {
+                                        "color": "gray"
+                                    }
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
 }
 ```
 
@@ -783,9 +971,9 @@ Any other attribute name will result in an error. Attribute values can either be
 
 ```JSON
 {
-        "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-	"target": "_blank",
-	"href": "='http://finance.yahoo.com/quote/' + @currentField"
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "target": "_blank",
+    "href": "='http://finance.yahoo.com/quote/' + @currentField"
 }
 ```
 
@@ -797,6 +985,20 @@ An optional property that specifies child elements of the element specified by `
 
 An optional property that is meant for debugging. It outputs error messages and logs warnings to the console. 
 
+### forEach
+
+An optional property that allows an element to duplicate itself for each member of a specific multi-value field. The value of `"forEach"` property should be in the format of either `"iteratorName in @currentField"` or `"iteratatorName in [$FieldName]"`.
+
+`iteratorName` represents the name of iterator variable that is used to represent the current member of the multi-value field. The name of the iterator can be any combination of alphanumeric characters and underscore (`_`) that does not start with a digit.
+
+The field used in the loop must be in a supported field type with multi-value option enabled: Person, Lookup, and Choice.
+
+In the element with `forEach` or its childern elements, the iterator variable can be referred as if it is a new field. The index of the iterator can be accessed with `loopIndex` operator.
+
+`forEach` cannot be applied to the root element, and will render no element if there is no value in the field.
+
+See [here](#formatting-multi-value-fields) for examples.
+
 ### Expressions
 
 Values for `txtContent`, style properties, and attribute properties can be expressed as expressions, so that they are evaluated at runtime based on the context of the current field (or row). Expression objects can be nested to contain other Expression objects. 
@@ -892,6 +1094,9 @@ Operators specify the type of operation to perform. The following operators are
 - toLocaleString()
 - toLocaleDateString()
 - toLocaleTimeString()
+- length
+- join
+- loopIndex
 
 **Binary operators** - The following are the standard arithmetic binary operators that expect two operands: 
 
@@ -914,13 +1119,29 @@ Operators specify the type of operation to perform. The following operators are
 - toLocaleString()
 - toLocaleDateString()
 - toLocaleTimeString()
+- length
+- loopIndex
 
 **Conditional operator** - The conditional operator is:
 
 - ?
 
 This is to achieve an expression equivalent to a ? b : c, where if the expression a evaluates to true, then the result is b, else the result is c.
 
+**Multi-value field-related operators** - The following operators are only used in a context with multi-value field of type Person, Lookup, or Choice.
+
+- length
+- join
+- loopIndex
+
+`length`, when provided with a field name, returns the number of members in a multi-valued field. When a single-value field is provided, `length` will return 1 when there is a value in that field.
+
+`join` concatenates values in a multi-value field with a specified separator. The first operand shall point to a value in a multi-value field, e.g. `"@currentField.lookupValue"`, `"[$AssignedTo.title]"`.  The second operand shall be a string literal that is the separator that joins the values together.
+
+`loopIndex`, when provided with a name of iterator variable, returns the current index (starting from 0) of the iterator. The name of iterator must be provided as a string literal. `loopIndex` would only work within the element with respective `forEach` enabled or its children elements.
+
+See [here](#formatting-multi-value-fields) for examples.
+
 ### operands
 
 Specifies the parameters, or operands for an expression. This is an array of Expression objects or base values.
@@ -1086,6 +1307,37 @@ This will evaluate to a number equal to the height of the browser window (in pix
 
 This will evaluate to a number equal to the width of the browser window (in pixels) when the list was rendered.
 
+#### Thumnails
+
+In a document library, there is a series of tokens that can be used to retrieve the URL to the thumbnail of a file, including:
+
+- `@thumbnail.small`, `@thumbnail.medium`, and `@thumbnail.large` evaluate to the thumbnail URL in 3 different predefined sizes.
+- `@thumbnail.<bounding size>` evaluates to the URL to the largest thumbnails that is not larger than the bounding size in both width and height. For example, `@thumbnail.150` evaluates to the URL to a thumbnail not larger than 150×150 pixels.
+- `@thumbnail.<bounding width>x<bounding height>` evaluates to the URL to the largest thumbnail that is not larger than the bounding width and bounding height. For example, `@thumbnail.100x200` evaluates to the URL to a thumbnail not wider than 100 pixels and not higher than 200 pixels.
+
+These tokens will yield no value on non-file items including folders.
+
+> [!NOTE]
+> The aspect ratio of thumbnail generated is the same as how the file looks like, changing the bounding sizes will not affect the aspect ratio of the thumbnail.
+
+> [!TIP]
+> Thumbnails are only available for a list of supported file formats. It means that sometimes the URL generated is not accessible due to lack of support on certain formats. However, if a valid thumbnail token is set as the _only_ `src` attribute of an `img` tag, we will take care of it and hide the image when it is not available.
+
+```json
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "img",
+   "attributes": {
+      "src": "@thumbnail.200x150",
+      "alt": "='Thumbnail of file ' + [$FileLeafRef]"
+   },
+   "style": {
+      "width": "100%",
+      "max-width": "100%"
+   }
+}
+```
+
 ## See also
 
 - [Column formatting](https://support.office.com/en-us/article/Column-formatting-1f927342-2bed-4745-b727-ff8b7ff96b22?ui=en-US&rs=en-US&ad=US)