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
New design for the widgets section in the docs (#866)
* Initial commit for the new widgets section
* Placing all the widgets and refining the CSS and Hugo logic
* Initial commit for the new widgets section
* Placing all the widgets and refining the CSS and Hugo logic
* Rebased and updated the info according to @verythorough contribution
* Fixing the yaml codes for the relation and select widget sections
* Merging with widgets.md and app.j
* Fixing some silly mistakes (sorry!)
* Following @verythorough contributions :)
* Adding the markdown widget and fixing the widgets container background
* Adding the URL functionality and myself as a contributor :)
* Adding myself as a contributor :)
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
62
+
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
Copy file name to clipboardExpand all lines: website/site/content/docs/widgets.md
+2-308
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ To see working examples of all of the built-in widgets, try making a 'Kitchen Si
17
17
The following options are available on all fields:
18
18
19
19
-`required`: specify as `false` to make a field optional; defaults to `true`
20
-
-`pattern`: add field validation by specifying a list with a regex pattern and an error message; more extensive validation can be achieved with [custom widgets](https://www.netlifycms.org/docs/custom-widgets/#advanced-field-validation)
20
+
-`pattern`: add field validation by specifying a list with a [regex pattern](https://regexr.com/) and an error message; more extensive validation can be achieved with [custom widgets](https://www.netlifycms.org/docs/custom-widgets/#advanced-field-validation)
21
21
-**Example:**
22
22
23
23
```yaml
@@ -27,310 +27,4 @@ The following options are available on all fields:
27
27
pattern: ['.{10,}', "Must have at least 20 characters"]
28
28
```
29
29
30
-
31
-
## Boolean
32
-
33
-
The boolean widget translates a toggle switch input to a true/false value.
34
-
35
-
- **Name:** `boolean`
36
-
- **UI:** toggle switch
37
-
- **Data type:** boolean
38
-
- **Options:**
39
-
- `default`: accepts `true` or `false`; defaults to `false`
- `default`: accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetime
77
-
- `format`: accepts Moment.js [tokens](https://momentjs.com/docs/#/parsing/string-format/); defaults to ISO8601 format `YYYY-MM-DDTHH:mm:ssZ`
78
-
- **Example:**
79
-
80
-
```yaml
81
-
- label: "Start time"
82
-
name: "start"
83
-
widget: "datetime"
84
-
default: ""
85
-
format: "LLL"
86
-
```
87
-
88
-
89
-
## File
90
-
91
-
The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string.
92
-
93
-
- **Name:** `file`
94
-
- **UI:** file picker button opens media gallery
95
-
- **Data type:** file path string, based on `media_folder`/`public_folder` configuration
96
-
- **Options:**
97
-
- `default`: accepts a file path string; defaults to null
98
-
- **Example:**
99
-
100
-
```yaml
101
-
- label: "Manual PDF"
102
-
name: "manual_pdf"
103
-
widget: "file"
104
-
default: "/uploads/general-manual.pdf"
105
-
```
106
-
107
-
108
-
## Hidden
109
-
110
-
Hidden widgets do not display in the UI. In folder collections that allow users to create new items, you will often want to set a default for hidden fields, so they will be set without requiring an input.
111
-
112
-
- **Name:** `hidden`
113
-
- **UI:** none
114
-
- **Data type:** any valid data type
115
-
- **Options:**
116
-
- `default`: accepts any valid data type; recommended for collections that allow adding new items
The image widget allows editors to upload an image or select an existing one from the media library. The path to the image file will be saved to the field as a string.
- **Data type:** file path string, based on `media_folder`/`public_folder` configuration
131
-
- **Options:**
132
-
- `default`: accepts a file path string; defaults to null
133
-
- **Example:**
134
-
135
-
```yaml
136
-
- label: "Featured Image"
137
-
name: "thumbnail"
138
-
widget: "image"
139
-
default: "/uploads/chocolate-dogecoin.jpg"
140
-
```
141
-
142
-
143
-
## List
144
-
145
-
The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. map a user-provided string with a comma delimiter into a list. You can choose any widget as a child of a list widget—even other lists.
146
-
147
-
- **Name:** `list`
148
-
- **UI:** if `fields` is specified, field containing a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets; if unspecified, a text input for entering comma-separated values
149
-
- **Data type:** list of widget values
150
-
- **Options:**
151
-
- `default`: if `fields` is specified, declare defaults on the child widgets; if not, you may specify a list of strings to populate the text field
152
-
- `field`: a single widget field to be repeated
153
-
- `fields`: a nested list of multiple widget fields to be included in each repeatable iteration
The number widget uses an HTML number input, saving the value as a string, integer, or floating point number.
193
-
194
-
- **Name:** `number`
195
-
- **UI:** HTML [number input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number)
196
-
- **Data type:** string by default; configured by `valueType` option
197
-
- **Options:**
198
-
- `default`: accepts string or number value; defaults to empty string
199
-
- `valueType`: accepts `int` or `float`; any other value results in saving as a string
200
-
- `min`: accepts a number for minimum value accepted; unset by default
201
-
- `max`: accepts a number for maximum value accepted; unset by default
202
-
- **Example:**
203
-
204
-
```yaml
205
-
- label: "Puppy Count"
206
-
name: "puppies"
207
-
widget: "number"
208
-
default: 2
209
-
valueType: "int"
210
-
min: 1
211
-
max: 101
212
-
```
213
-
214
-
215
-
## Object
216
-
217
-
The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget—even other objects.
218
-
219
-
- **Name:** `object`
220
-
- **UI:** a field containing one or more child widgets
221
-
- **Data type:** list of child widget values
222
-
- **Options:**
223
-
- `default`: you can set defaults within each sub-field's configuration
224
-
- `fields`: (**required**) a nested list of widget fields to include in your widget
The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you're referencing, and the list automatically updates with matched entries based on what you've typed.
252
-
253
-
- **Name:** `relation`
254
-
- **UI:** text input with search result dropdown
255
-
- **Data type:** data type of the value pulled from the related collection item
256
-
- **Options:**
257
-
- `default`: accepts any widget data type; defaults to an empty string
258
-
- `collection`: (**required**) name of the collection being referenced (string)
259
-
- `searchFields`: (**required**) list of one or more names of fields in the referenced collection to search for the typed value
260
-
- `valueField`: (**required**) name of the field from the referenced collection whose value will be stored for the relation
261
-
- **Example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields):
262
-
263
-
```yaml
264
-
- label: Post Author
265
-
name: author
266
-
widget: relation
267
-
collection: authors
268
-
searchFields: [name, twitterHandle]
269
-
valueField: name
270
-
```
271
-
The generated UI input will search the authors collection by name and twitterHandle as the user types. On selection, the author name will be saved for the field.
272
-
273
-
274
-
## Select
275
-
276
-
The select widget allows you to pick a single string value from a dropdown menu.
277
-
278
-
- **Name:** `select`
279
-
- **UI:** HTML select input
280
-
- **Data type:** string
281
-
- **Options:**
282
-
- `default`: accepts a string; defaults to an empty string
283
-
- `options`: (**required**) a list of options for the dropdown menu; can be listed in two ways:
284
-
- string values: the label displayed in the dropdown is the value saved in the file
285
-
- object with `label` and `value` fields: the label displays in the dropdown; the value is saved in the file
286
-
- **Example** (options as strings):
287
-
288
-
```yaml
289
-
- label: "Align Content"
290
-
name: "align"
291
-
widget: "select"
292
-
options: ["left", "center", "right"]
293
-
```
294
-
- **Example** (options as objects):
295
-
296
-
```yaml
297
-
- label: "City"
298
-
name: "airport-code"
299
-
widget: "select"
300
-
options:
301
-
- { label: "Chicago", value: "ORD" }
302
-
- { label: "Paris", value: "CDG" }
303
-
- { label: "Tokyo", value: "HND" }
304
-
```
305
-
306
-
307
-
## String
308
-
309
-
The string widget translates a basic text input to a string value. For larger textarea inputs, use the [text](#text) widget.
310
-
311
-
- **Name:** `string`
312
-
- **UI:** text input
313
-
- **Data type:** string
314
-
- **Options:**
315
-
- `default`: accepts a string; defaults to an empty string
0 commit comments