Skip to content

Commit 26971d3

Browse files
author
Jin Han
committed
Add docs for @thumbnails, and multi-value field operations.
1 parent 952e1e5 commit 26971d3

File tree

4 files changed

+290
-38
lines changed

4 files changed

+290
-38
lines changed

‎docs/declarative-customization/column-formatting.md

Lines changed: 290 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -337,15 +337,15 @@ This example applies `background-color` and `border-top` styles to create a data
337337

338338
```JSON
339339
{
340-
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
341-
"elmType": "div",
342-
"txtContent": "@currentField",
343-
"attributes": {
344-
"class": "sp-field-dataBars"
345-
},
346-
"style": {
347-
"width": "=if(@currentField > 95, '100%', toString(@currentField * 100 / 95) + '%')"
348-
}
340+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
341+
"elmType": "div",
342+
"txtContent": "@currentField",
343+
"attributes": {
344+
"class": "sp-field-dataBars"
345+
},
346+
"style": {
347+
"width": "=if(@currentField > 95, '100%', toString(@currentField * 100 / 95) + '%')"
348+
}
349349
}
350350
```
351351

@@ -432,33 +432,221 @@ To use the sample below, you must substitute the ID of the Flow you want to run.
432432

433433
```JSON
434434
{
435-
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
436-
"elmType": "span",
437-
"style": {
438-
"color": "#0078d7"
439-
},
440-
"children": [
441-
{
442-
"elmType": "span",
443-
"attributes": {
444-
"iconName": "Flow"
445-
}
435+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
436+
"elmType": "span",
437+
"style": {
438+
"color": "#0078d7"
446439
},
447-
{
448-
"elmType": "button",
449-
"style": {
450-
"border": "none",
451-
"background-color": "transparent",
452-
"color": "#0078d7",
453-
"cursor": "pointer"
454-
},
455-
"txtContent": "Send to Manager",
456-
"customRowAction": {
457-
"action": "executeFlow",
458-
"actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
459-
}
460-
}
461-
]
440+
"children": [
441+
{
442+
"elmType": "span",
443+
"attributes": {
444+
"iconName": "Flow"
445+
}
446+
},
447+
{
448+
"elmType": "button",
449+
"style": {
450+
"border": "none",
451+
"background-color": "transparent",
452+
"color": "#0078d7",
453+
"cursor": "pointer"
454+
},
455+
"txtContent": "Send to Manager",
456+
"customRowAction": {
457+
"action": "executeFlow",
458+
"actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
459+
}
460+
}
461+
]
462+
}
463+
```
464+
465+
## Formatting multi-value fields
466+
You can use column formatting to apply styles to each member of a multi-value field of type Person, Lookup and Choice.
467+
468+
### Basic text formatting
469+
The following image shows an example of multi-value field formatting applied to a Person field.
470+
471+
![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)
472+
473+
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.
474+
475+
```json
476+
{
477+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
478+
"elmType": "a",
479+
"style": {
480+
"display": "=if(length(@currentField) > 0, 'flex', 'none')"
481+
},
482+
"attributes": {
483+
"href": {
484+
"operator": "+",
485+
"operands": [
486+
"mailto:",
487+
"=join(@currentField.email, ';')"
488+
]
489+
}
490+
},
491+
"children": [
492+
{
493+
"elmType": "span",
494+
"style": {
495+
"display": "inline-block",
496+
"padding": "0 4px"
497+
},
498+
"attributes": {
499+
"iconName": "Mail"
500+
}
501+
},
502+
{
503+
"elmType": "span",
504+
"txtContent": {
505+
"operator": "+",
506+
"operands": [
507+
"Send email to ",
508+
{
509+
"operator": "?",
510+
"operands": [
511+
"=length(@currentField) == 1",
512+
"@currentField.title",
513+
"='all ' + length(@currentField) + ' members'"
514+
]
515+
}
516+
]
517+
}
518+
}
519+
]
520+
}
521+
```
522+
523+
### Simple HTML elements formatting
524+
The following image showsn an example of constructing a simple sentence from the values of a multi-value Lookup field.
525+
526+
![Screenshot of a field reads "North America, APAC, and Europe"](../images/sp-columnformatting-multi-value-1.png)
527+
528+
This examples uses operator `loopIndex` and `length` to identify the last member of the field, and attribute `forEach` to duplicate HTML elements.
529+
530+
```json
531+
{
532+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
533+
"elmType": "div",
534+
"style": {
535+
"display": "block"
536+
},
537+
"children": [
538+
{
539+
"elmType": "span",
540+
"forEach": "region in @currentField",
541+
"txtContent": {
542+
"operator": "?",
543+
"operands": [
544+
"=loopIndex('region') + 1 == length(@currentField)",
545+
"=', and ' + [$region.lookupValue]",
546+
{
547+
"operator": "?",
548+
"operands": [
549+
"=loopIndex('region') == 0",
550+
"[$region.lookupValue]",
551+
"=', ' + [$region.lookupValue]"
552+
]
553+
}
554+
]
555+
}
556+
}
557+
]
558+
}
559+
```
560+
561+
### Complex HTML elements formatting
562+
The following image showsn an example of building a list of users with pictures, email addresses and a simple counter at the top.
563+
564+
![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)
565+
566+
This examples uses operator `loopIndex` to control the margins all rows but the first one, and attribute `forEach` to build the list of members.
567+
568+
```json
569+
{
570+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
571+
"elmType": "div",
572+
"style": {
573+
"min-height": "1.5em",
574+
"flex-direction": "column",
575+
"align-items": "start"
576+
},
577+
"children": [
578+
{
579+
"elmType": "div",
580+
"txtContent": "=length(@currentField)",
581+
"style": {
582+
"border-radius": "1.5em",
583+
"height": "1.5em",
584+
"min-width": "1.5em",
585+
"color": "white",
586+
"text-align": "center",
587+
"position": "absolute",
588+
"top": "0",
589+
"right": "1em",
590+
"background-color": "=if(length(@currentField) == 0, '#ddd', '#aaa'"
591+
}
592+
},
593+
{
594+
"elmType": "div",
595+
"forEach": "person in @currentField",
596+
"style": {
597+
"justify-content": "center",
598+
"margin-top": "=if(loopIndex('person') == 0, '0', '1em')"
599+
},
600+
"children": [
601+
{
602+
"elmType": "div",
603+
"style": {
604+
"display": "flex",
605+
"flex-direction": "row",
606+
"justify-content": "center"
607+
},
608+
"children": [
609+
{
610+
"elmType": "img",
611+
"attributes": {
612+
"src": "=[$person.picture]"
613+
},
614+
"style": {
615+
"width": "3em",
616+
"height": "3em",
617+
"border-radius": "3em"
618+
}
619+
},
620+
{
621+
"elmType": "a",
622+
"attributes": {
623+
"href": "='mailto:' + [$person.email]"
624+
},
625+
"style": {
626+
"margin-left": "0.5em"
627+
},
628+
"children": [
629+
{
630+
"elmType": "div",
631+
"txtContent": "[$person.title]",
632+
"style": {
633+
"font-size": "1.2em"
634+
}
635+
},
636+
{
637+
"elmType": "div",
638+
"txtContent": "[$person.email]",
639+
"style": {
640+
"color": "gray"
641+
}
642+
}
643+
]
644+
}
645+
]
646+
}
647+
]
648+
}
649+
]
462650
}
463651
```
464652

@@ -783,9 +971,9 @@ Any other attribute name will result in an error. Attribute values can either be
783971

784972
```JSON
785973
{
786-
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
787-
"target": "_blank",
788-
"href": "='http://finance.yahoo.com/quote/' + @currentField"
974+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
975+
"target": "_blank",
976+
"href": "='http://finance.yahoo.com/quote/' + @currentField"
789977
}
790978
```
791979

@@ -797,6 +985,20 @@ An optional property that specifies child elements of the element specified by `
797985

798986
An optional property that is meant for debugging. It outputs error messages and logs warnings to the console.
799987

988+
### forEach
989+
990+
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]"`.
991+
992+
`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.
993+
994+
The field used in the loop must be in a supported field type with multi-value option enabled: Person, Lookup, and Choice.
995+
996+
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.
997+
998+
`forEach` cannot be applied to the root element, and will render no element if there is no value in the field.
999+
1000+
See [here](#formatting-multi-value-fields) for examples.
1001+
8001002
### Expressions
8011003

8021004
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
8921094
- toLocaleString()
8931095
- toLocaleDateString()
8941096
- toLocaleTimeString()
1097+
- length
1098+
- join
1099+
- loopIndex
8951100

8961101
**Binary operators** - The following are the standard arithmetic binary operators that expect two operands:
8971102

@@ -914,13 +1119,29 @@ Operators specify the type of operation to perform. The following operators are
9141119
- toLocaleString()
9151120
- toLocaleDateString()
9161121
- toLocaleTimeString()
1122+
- length
1123+
- loopIndex
9171124

9181125
**Conditional operator** - The conditional operator is:
9191126

9201127
- ?
9211128

9221129
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.
9231130

1131+
**Multi-value field-related operators** - The following operators are only used in a context with multi-value field of type Person, Lookup, or Choice.
1132+
1133+
- length
1134+
- join
1135+
- loopIndex
1136+
1137+
`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.
1138+
1139+
`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.
1140+
1141+
`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.
1142+
1143+
See [here](#formatting-multi-value-fields) for examples.
1144+
9241145
### operands
9251146

9261147
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
10861307

10871308
This will evaluate to a number equal to the width of the browser window (in pixels) when the list was rendered.
10881309

1310+
#### Thumnails
1311+
1312+
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:
1313+
1314+
- `@thumbnail.small`, `@thumbnail.medium`, and `@thumbnail.large` evaluate to the thumbnail URL in 3 different predefined sizes.
1315+
- `@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.
1316+
- `@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.
1317+
1318+
These tokens will yield no value on non-file items including folders.
1319+
1320+
> [!NOTE]
1321+
> 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.
1322+
1323+
> [!TIP]
1324+
> 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.
1325+
1326+
```json
1327+
{
1328+
"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
1329+
"elmType": "img",
1330+
"attributes": {
1331+
"src": "@thumbnail.200x150",
1332+
"alt": "='Thumbnail of file ' + [$FileLeafRef]"
1333+
},
1334+
"style": {
1335+
"width": "100%",
1336+
"max-width": "100%"
1337+
}
1338+
}
1339+
```
1340+
10891341
## See also
10901342

10911343
- [Column formatting](https://support.office.com/en-us/article/Column-formatting-1f927342-2bed-4745-b727-ff8b7ff96b22?ui=en-US&rs=en-US&ad=US)

‎docs/images/sp-columnformatting-multi-value-0.png

2.7 KB
Loading

‎docs/images/sp-columnformatting-multi-value-1.png

2.29 KB
Loading

‎docs/images/sp-columnformatting-multi-value-2.png

12.4 KB
Loading

0 commit comments

Comments
 (0)