You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/declarative-customization/view-formatting.md
+33-23Lines changed: 33 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -9,58 +9,63 @@ ms.date: 06/08/2018
9
9
10
10
# Use view formatting to customize SharePoint
11
11
12
-
You can use view formatting to customize how views in SharePoint lists and libraries are displayed. To do this, you construct a JSON object that describes the elements that are displayed with a row is loaded in a list view, and styles to be applied to those elements. View formatting does not change the data in list items of riles; it only changes how it's displayed to users who browse the list. Anyone who can create and manage views in a list can use view formatting to configure how views are displayed.
12
+
You can use view formatting to customize how views in SharePoint lists and libraries are displayed. To do this, you construct a JSON object that describes the elements that are displayed when a row is loaded in a list view and any styles to be applied to those elements. View formatting does not change the data in list items; it only changes how they're displayed to users who browse the list. Anyone who can create and manage views in a list can use view formatting to configure how views are displayed.
13
13
14
14
> [!TIP]
15
-
> Samples demonstrated in this article and numerous other community samples are available from a GitHub repository dedicated for open-sourced column formatting definitions. You can find these samples from the [sp-dev-list-formatting](https://github.com/SharePoint/sp-dev-list-formatting) repository at[SharePoint](https://github.com/SharePoint) GitHub organization.
15
+
> Samples demonstrated in this article and numerous other community samples are available from a GitHub repository dedicated for open-sourced list formatting definitions. You can find these samples in the [sp-dev-list-formatting](https://github.com/SharePoint/sp-dev-list-formatting) repository within the[SharePoint](https://github.com/SharePoint) GitHub organization.
16
16
17
17
## Get started with view formatting
18
18
19
-
To open the view formatting pane, open the view dropdown, and choose **Format this view**.
19
+
To open the view formatting pane, open the view dropdown and choose **Format this view**.
20
20
21
-
The easiest way to use view formatting is to start from an example and edit it to apply to your specific view. The following sections contain examples that you can copy, paste, and edit for your scenarios. There are also several samples available in the [SharePoint/sp-dev-list-formatting repository](https://github.com/SharePoint/sp-dev-list-formatting).
21
+
The easiest way to use view formatting is to start from an example and edit it to apply to your specific view. The following sections contain examples that you can copy, paste, and customize for your specific needs. There are also several samples available in the [SharePoint/sp-dev-list-formatting repository](https://github.com/SharePoint/sp-dev-list-formatting).
22
22
23
-
## Apply conditional formatting
23
+
## Apply conditional classes
24
24
25
-
You can use view formatting to apply a class to a list view row, depending on the value of one or more fields in the row. These examples leave the content and structure of list view rows intact.
25
+
You can use view formatting to apply one or more classes to the entire list view row depending on the value of one or more fields in the row. These examples leave the content and structure of list view rows intact.
26
26
27
-
For a list of recommended classes to use inside view formats, please see the [Style Guidelines section](https://github.com/SharePoint/sp-dev-docs/blob/master/docs/declarative-customization/column-formatting.md#style-guidelines) in the [Column Formatting reference document.](https://github.com/SharePoint/sp-dev-docs/blob/master/docs/declarative-customization/column-formatting.md)
27
+
For a list of recommended classes to use inside view formats, please see the [Style Guidelines section](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting#style-guidelines) in the [Column Formatting reference document](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting).
28
28
29
-
### Conditional formatting based on a date range
29
+
> [!TIP]
30
+
> Using the `additionalRowClass` property to apply classes to list view rows will leave the formatting of individual columns in place. This allows you to combine view formats with column formatting for some really powerful visualizations.
31
+
32
+
### Conditional classes based on a date field
30
33
31
-
The following image shows a list view with conditional formatting applied based on a date range:
34
+
The following image shows a list view with a class applied based on the value of a date column:
32
35
33
36
34
-
This example applies the class `sp-field-severity--severeWarning` to a list view row when the item's DueDate is before the current date/time.
37
+
This example applies the class `sp-field-severity--severeWarning` to a list view row when the item's DueDate is before the current date/time:
### Conditional formatting based on the value in a text or choice field
46
+
### Conditional classes based on the value in a text or choice field
44
47
45
-
This example was adopted from a column formatting example, [Conditional formatting based on the value in a text of choice field](https://github.com/ldemaris/sp-dev-docs/blob/patch-7/docs/declarative-customization/column-formatting.md#conditional-formatting-based-on-the-value-in-a-text-or-choice-field-advanced), with some important differences to apply the concept to list view rows. The column formatting example applies both an icon and a class to a column based on the value of `@currentField`. The `additionalRowClass` attribute in view formatting, however, only allows you to specify a class and not an icon. Additionally, since `@currentField` always resolves to the value of the Title field when referenced inside a view format, this sample refers to the `$Status` field directly to determine which class to apply to the row.
48
+
This example was adopted from a column formatting example, [Conditional formatting based on the value in a text or choice field](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/column-samples/text-conditional-format), with some important differences to apply the concept to list view rows. The column formatting example applies both an icon and a class to a column based on the value of `@currentField`. The `additionalRowClass` attribute in view formatting, however, only allows you to specify a class and not an icon. Additionally, since `@currentField` always resolves to the value of the `Title` field when referenced inside a view format, this sample refers to the `Status` field directly (by using the to determine which class to apply to the row.
You can find this sample with additional details here: [Conditional formatting based on choice field](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/view-samples/text-conditional-format)
58
+
54
59
## Build custom row layouts
55
60
56
-
You can use view formatting to define a totally custom layout of field values inside a row.
61
+
You can use view formatting to define a totally custom layout of field values inside a row using the same syntax used in Column Formatting.
57
62
58
63
### Multi-line view style
59
64
60
65
The following image shows a list with a custom multi-line view style applied:
61
66
62
67
63
-
This example uses the `rowFormatter` element, which totally overrides the rendering of a list view row. The `rowFormatter` in this example creates a bounding `<div />` box for every list view row. Inside this bounding box, the `$Title` and `$Feedback` fields are displayed on separate lines. Under those fields, a `button` element is displayed that, when clicked, does the same thing as clicking the list row in an uncustomized view, which is opening the property form for the item. This `button` is displayed conditionally, when the value of the `$Assigned_x0020_To` field (assumed to be a person/group field) matches the current signed-in user.
68
+
This example uses the `rowFormatter` element, which totally overrides the rendering of a list view row. The `rowFormatter` in this example creates a bounding `<div />` box for every list view row. Inside this bounding box, the `$Title` and `$Feedback` fields are displayed on separate lines. Under those fields, a `button` element is displayed that, when clicked, does the same thing as clicking the list row in an uncustomized view, which is opening the property form for the item. This `button` is displayed conditionally, when the value of the `$Assigned_x0020_To` field (assumed to be a person/group field) matches the current signed-in user:
64
69
65
70
```JSON
66
71
{
@@ -126,6 +131,8 @@ This example uses the `rowFormatter` element, which totally overrides the render
126
131
}
127
132
```
128
133
134
+
You can find this sample with additional details here: [Multi-line view rendering](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/view-samples/multi-line-view)
135
+
129
136
## Creating custom JSON
130
137
131
138
Creating custom view formatting JSON from scratch is simple if you understand the schema. To create your own custom column formatting:
@@ -142,7 +149,7 @@ Creating custom view formatting JSON from scratch is simple if you understand th
142
149
}
143
150
```
144
151
145
-
You now have validation and autocomplete to create your JSON. You can start adding your JSON after the first line that defines the schema ___location.
152
+
You now have validation and autocomplete to create your JSON. You can start adding your JSON after the first line that defines the schema ___location.
146
153
147
154
> [!TIP]
148
155
> At any point, select **Ctrl**+**Space** to have Visual Studio Code offer suggestions for properties and values. For more information, see [Editing JSON with Visual Studio Code](https://code.visualstudio.com/Docs/languages/json).
@@ -151,26 +158,29 @@ Creating custom view formatting JSON from scratch is simple if you understand th
151
158
152
159
### rowFormatter
153
160
154
-
Optional element. Specifies a JSON object that describes a list view row format. The schema of this JSON object is identical to the schema of a column format. For details on this schema and its capabilities, see the [Column Format detailex syntax reference.](https://github.com/SharePoint/sp-dev-docs/blob/master/docs/declarative-customization/column-formatting.md#detailed-syntax-reference)
161
+
Optional element. Specifies a JSON object that describes a list view row format. The schema of this JSON object is identical to the schema of a column format. For details on this schema and its capabilities, see the [Column Format detailed syntax reference](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting#detailed-syntax-reference).
162
+
163
+
>[!NOTE]
164
+
> Using the `rowFormatter` property will override anything specified in the `additionalRowClass` property. They are mutually exclusive.
155
165
156
166
#### Differences in behavior between the rowFormatter element and column formatting
157
167
158
168
Despite sharing the same schema, there are some differences in behavior between elements inside a `rowFormatter` element and those same elements in a column formatting object.
159
169
160
-
*`@currentField` always resolves to the value of the Title field inside a `rowFormatter`.
170
+
*`@currentField` always resolves to the value of the `Title` field inside a `rowFormatter`.
161
171
162
172
### additionalRowClass
163
173
164
-
Optional element. Specifies a CSS class that is applied to the row.
174
+
Optional element. Specifies a CSS class(es) that is applied to the entire row. Supports expressions.
165
175
166
176
`additionalRowClass` only takes effect when there is no `rowFormatter` element specified. If a `rowFormatter` is specified, then `additionalRowClass` is ignored.
167
177
168
178
### hideSelection
169
179
170
-
Optional element. Specifies whether the ability to select rows in the view is diabled or not. *false* is the default behavior inside a list view. *true* means that users will not be able to select list items.
180
+
Optional element. Specifies whether the ability to select rows in the view is diabled or not. *false* is the default behavior inside a list view (meaning selection is visiable and enabled).*true* means that users will not be able to select list items.
171
181
172
182
`hideSelection` only takes effect when there's a `rowFormatter` element specified. If no `rowFormatter` is specified, then `hideSelection` is ignored.
173
183
174
-
### hideColumnHeader
184
+
### hideListHeader
175
185
176
-
Optional element. Specifies whether the column headers in the view are hidden or not. *false* is the default behavior inside a list view. *true* means that the view will not display column headers.
186
+
Optional element. Specifies whether the column headers in the view are hidden or not. *false* is the default behavior inside a list view (meaning column headers will be visible).*true* means that the view will not display column headers.
0 commit comments