Skip to content

Commit 8ebde47

Browse files
rk-menonrk-menon
committed
new file
1 parent 044fc7a commit 8ebde47

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎docs/declarative-customization/niket.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: Use view formatting to customize SharePoint
3+
description: Customize how views in SharePoint lists and libraries are displayed by constructing a JSON object that describes the elements that are displayed in a list view, and the styles to be applied to those elements.
4+
ms.date: 08/21/2019
5+
localization_priority: Priority
6+
---
7+
8+
# NIKETS VIEW
9+
10+
# Use view formatting to customize SharePoint
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 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+
14+
> [!TIP]
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+
17+
>[!NOTE]
18+
> View formatting is currently supported only in SharePoint Online.
19+
20+
21+
## Get started with view formatting
22+
23+
To open the view formatting pane, open the view dropdown and choose **Format this view**.
24+
25+
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).
26+
27+
## Apply conditional classes
28+
29+
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.
30+
31+
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).
32+
33+
> [!TIP]
34+
> 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 powerful visualizations.
35+
36+
### Conditional classes based on a date field
37+
38+
The following image shows a list view with a class applied based on the value of a date column:
39+
![SharePoint list with view formatted with conditional formatting](../images/listformatting-additionalrowclass.png)
40+
41+
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:
42+
43+
```JSON
44+
{
45+
"schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
46+
"additionalRowClass": "=if([$DueDate] <= @now, 'sp-field-severity--severeWarning', '')"
47+
}
48+
```
49+
50+
### Conditional classes based on the value in a text or choice field
51+
52+
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 [$Field] syntax inside the additionalRowClass property to determine which class to apply to the row).
53+
54+
```JSON
55+
{
56+
"schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
57+
"additionalRowClass": "=if([$Status] == 'Done', 'sp-field-severity--good', if([$Status] == 'In progress', 'sp-field-severity--low' ,if([$Status] == 'In review','sp-field-severity--warning', if([$Status] == 'Has issues','sp-field-severity--blocked', ''))))"
58+
}
59+
```
60+
61+
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)
62+
63+
## Build custom row layouts
64+
65+
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.
66+
67+
### Multi-line view style
68+
69+
The following image shows a list with a custom multi-line view style applied:
70+
![SharePoint list with multi-line view customization](../images/listformatting-rowformatter.png)
71+
72+
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:
73+
74+
```JSON
75+
{
76+
"schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
77+
"hideSelection": true,
78+
"hideColumnHeader": true,
79+
"rowFormatter": {
80+
"elmType": "div",
81+
"attributes": {
82+
"class": "sp-row-card"
83+
},
84+
"children": [
85+
{
86+
"elmType": "div",
87+
"style": {
88+
"text-align": "left"
89+
},
90+
"children": [
91+
{
92+
"elmType": "div",
93+
"attributes": {
94+
"class": "sp-row-title"
95+
},
96+
"txtContent": "[$Title]"
97+
},
98+
{
99+
"elmType": "div",
100+
"attributes": {
101+
"class": "sp-row-listPadding"
102+
},
103+
"txtContent": "[$Feedback]"
104+
},
105+
{
106+
"elmType": "button",
107+
"customRowAction": {
108+
"action": "defaultClick"
109+
},
110+
"txtContent": "Give feedback",
111+
"attributes": {
112+
"class": "sp-row-button"
113+
},
114+
"style": {
115+
"display": {
116+
"operator": "?",
117+
"operands": [
118+
{
119+
"operator": "==",
120+
"operands": [
121+
"@me",
122+
"[$Assigned_x0020_To.email]"
123+
]
124+
},
125+
"",
126+
"none"
127+
]
128+
}
129+
}
130+
}
131+
]
132+
}
133+
]
134+
}
135+
}
136+
```
137+
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)
138+
139+
### Alternate Row Formatting based on Modulus
140+
141+
This example applies `% (Mod)` to a list view row with alternate coloring the rows:
142+
143+
```JSON
144+
{
145+
"schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
146+
"additionalRowClass": "=if(@rowIndex%2==0,'ms-bgColor-themeLight','')"
147+
}
148+
```
149+
150+
## Creating custom JSON
151+
152+
Creating custom view formatting JSON from scratch is simple if you understand the schema. To create your own custom column formatting:
153+
154+
1. [Download Visual Studio Code](https://code.visualstudio.com/Download). It's free and fast to download.
155+
156+
2. In Visual Studio Code, create a new file, and save the empty file with a .json file extension.
157+
158+
3. Paste the following lines of code into your empty file.
159+
160+
```JSON
161+
{
162+
"$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json"
163+
}
164+
```
165+
166+
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.
167+
168+
> [!TIP]
169+
> 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).
170+
171+
## Detailed syntax reference
172+
173+
### rowFormatter
174+
175+
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).
176+
177+
>[!NOTE]
178+
> Using the `rowFormatter` property will override anything specified in the `additionalRowClass` property. They are mutually exclusive.
179+
180+
#### Differences in behavior between the rowFormatter element and column formatting
181+
182+
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.
183+
184+
* `@currentField` always resolves to the value of the `Title` field inside a `rowFormatter`.
185+
186+
### additionalRowClass
187+
188+
Optional element. Specifies a CSS class(es) that is applied to the entire row. Supports expressions.
189+
190+
`additionalRowClass` only takes effect when there is no `rowFormatter` element specified. If a `rowFormatter` is specified, then `additionalRowClass` is ignored.
191+
192+
### hideSelection
193+
194+
Optional element. Specifies whether the ability to select rows in the view is disabled or not. *false* is the default behavior inside a list view (meaning selection is visible and enabled). *true* means that users will not be able to select list items.
195+
196+
`hideSelection` only takes effect when there's a `rowFormatter` element specified. If no `rowFormatter` is specified, then `hideSelection` is ignored.
197+
198+
### hideColumnHeader
199+
200+
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

Comments
 (0)