Skip to content

Commit 45d45f6

Browse files
AJIXuMuKAJIXuMuK
authored
Merge pull request #591 from siata13/dev
Add FieldCollectionData control.
2 parents e1d2ec5 + b842f36 commit 45d45f6

29 files changed

+4537
-2986
lines changed

‎docs/documentation/docs/assets/FieldCollectionData.gif

241 KB
Loading

‎docs/documentation/docs/controls/FieldCollectionData.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# FieldCollectionData control
2+
3+
This control gives you the ability to insert a list / collection data which can be used in your web part / application customizer. For example: you want to specify multiple locations for showing a weather information.
4+
5+
The control allows you to specify multiple data types like: string, number, boolean, or dropdown. It also provides the possibility to render custom field.
6+
7+
**FieldCollectionData**
8+
9+
![Code editor initial](../assets/FieldCollectionData.gif)
10+
11+
The type of data you get returned depends on the fields you defined. For the example above, the data looks like this:
12+
13+
```json
14+
[
15+
{
16+
"Field1": "String value", "Field2": "123", "Field3": "https://pnp.github.io/", "Field4": true
17+
}
18+
]
19+
```
20+
21+
## How to use this control in your solutions
22+
23+
1. Check that you installed the `@pnp/spfx-controls-react` dependency. Check out The [getting started](../../#getting-started) page for more information about installing the dependency.
24+
2. Import the following modules to your component:
25+
26+
```TypeScript
27+
import { FieldCollectionData, CustomCollectionFieldType } from '@pnp/spfx-controls-react/lib/FieldCollectionData';
28+
```
29+
30+
3. Add the control to the render method:
31+
32+
33+
```TypeScript
34+
<FieldCollectionData
35+
key={"FieldCollectionData"}
36+
label={"Fields Collection"}
37+
manageBtnLabel={"Manage"} onChanged={(value) => { console.log(value); }}
38+
panelHeader={"Manage values"}
39+
40+
fields={[
41+
{id: "Field1", title:"String field", type: CustomCollectionFieldType.string, required: true},
42+
{id: "Field2", title:"Number field", type: CustomCollectionFieldType.number},
43+
{id: "Field3", title:"URL field", type: CustomCollectionFieldType.url},
44+
{id: "Field4", title:"Boolean field", type: CustomCollectionFieldType.boolean}
45+
]}
46+
value={[
47+
{
48+
"Field1": "String value", "Field2": "123", "Field3": "https://pnp.github.io/", "Field4": true
49+
}
50+
]}
51+
/>
52+
```
53+
54+
### Sample of custom field rendering
55+
56+
Here is an example of how you can render your own controls in the `FieldCollectionData` control:
57+
58+
```TypeScript
59+
{
60+
id: "customFieldId",
61+
title: "Custom Field",
62+
type: CustomCollectionFieldType.custom,
63+
onCustomRender: (field, value, onUpdate, item, itemId, onError) => {
64+
return (
65+
React.createElement("div", null,
66+
React.createElement("input", { key: itemId, value: value, onChange: (event: React.FormEvent<HTMLInputElement>) => {
67+
if (event.currentTarget.value === "error") {
68+
onError(field.id, "Value shouldn't be equal to error");
69+
} else {
70+
onError(field.id, "");
71+
}
72+
onUpdate(field.id, event.currentTarget.value);
73+
}}), " 🎉"
74+
)
75+
);
76+
}
77+
}
78+
```
79+
80+
## Implementation
81+
82+
The `FieldCollectionData` control can be configured with the following properties:
83+
84+
| Property | Type | Required | Description | Default Value |
85+
| ---- | ---- | ---- | ---- | ---- |
86+
| key | string | yes | An unique key that indicates the identity of this control. | |
87+
| label | string | no | Property field label displayed on top. | |
88+
| panelHeader | string | yes | Label to be used as the header in the panel. | |
89+
| panelDescription | string | no | Property that allows you to specify a description in the collection panel. | |
90+
| manageBtnLabel | string | yes | Label of the button to open the panel. | |
91+
| saveBtnLabel | string | no | Label of the save button. | |
92+
| saveAndAddBtnLabel | string | yes | Label of the save and add button. | |
93+
| cancelBtnLabel | string | yes | Label of the cancel button. | |
94+
| fields | ICustomCollectionField[] | yes | The fields to be used for the list of collection data. | |
95+
| value | string | yes | The collection data value. | |
96+
| enableSorting | boolean | no | Specify if you want to be able to sort the items in the collection. | false |
97+
| disabled | boolean | no | Specify if the control is disabled. | false |
98+
| disableItemCreation | boolean | no | Allows you to specify if user can create new items. | false |
99+
| disableItemDeletion | boolean | no | Allows you to specify if users can delete already inserted items. | false |
100+
| panelClassName | string | no | Allows you to specify a custom CSS class name for the collection data panel. | |
101+
| tableClassName | string | no | Allows you to specify a custom CSS class name for the collection data table inside the panel. | |
102+
103+
Interface `ICustomCollectionField`
104+
105+
| Property | Type | Required | Description |
106+
| ---- | ---- | ---- | ---- |
107+
| id | string | yes | ID of the field. |
108+
| title | string | yes | Title of the field. This will be used for the label in the table. |
109+
| type | CustomCollectionFieldType | yes | Specifies the type of field to render. |
110+
| disableEdit | boolean | no | Allows you to specify if a field is disabled for editing. |
111+
| required | boolean | no | Specify if the field is required. |
112+
| options | [IDropdownOption[]](https://developer.microsoft.com/en-us/fabric#/components/dropdown) | no | Dropdown options. Only necessary when dropdown type is used. |
113+
| onRenderOption | IRenderFunction<ISelectableOption> | no | Dropdown custom options render method. Only for the **dropdown** field type. |
114+
| placeholder | string | no | Placehoder text which will be used for the input field. If not provided the input title will be used. |
115+
| defaultValue | any | no | Specify a default value for the input field. |
116+
| deferredValidationTime | number | no | Field will start to validate after users stop typing for `deferredValidationTime` milliseconds. Default: 200ms. |
117+
| onGetErrorMessage | (value: any, index: number, crntItem: any): string \| Promise<string> | no | The method is used to get the validation error message and determine whether the input value is valid or not. It provides you the current row index and the item you are currently editing. |
118+
| onCustomRender | (field: ICustomCollectionField, value: any, onUpdate: (fieldId: string, value: any) => void, item: any, itemUniqueId: string, onCustomFieldValidation: (fieldId: string, errorMessage: string) => void) => JSX.Element | no | This property is only required if you are using the `custom` field type and it can be used to specify the custom rendering of your control in the collection data. |
119+
120+
Enum `CustomCollectionFieldType`
121+
122+
| Type | Description |
123+
| ---- | ---- |
124+
| string | Text field |
125+
| number | Number field |
126+
| boolean | Checkbox |
127+
| dropdown | Dropdown field. You will have to specify the `options` property when using this field type |
128+
| fabricIcon | Name of the [Office UI Fabric icon](https://developer.microsoft.com/en-us/fabric#/styles/icons) |
129+
| url | URL field |
130+
| custom | This gives you control over the whole field rendering. Be sure to provide the `onCustomRender` method to render your control in the collection data. |
131+
132+
![](https://telemetry.sharepointpnp.com/sp-dev-fx-property-controls/wiki/FieldCollectionData)

0 commit comments

Comments
 (0)