102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# Configuring your site
|
||
|
||
## Widgets
|
||
|
||
Widgets define the data type and interface for entry fields. Netlify CMS comes with several built-in widgets, including:
|
||
|
||
| Name | UI | Data Type |
|
||
| -------- | ---------------------------------- | ---------------------------------------------------|
|
||
| `string` | text input | string |
|
||
| `boolean` | toggle switch | boolean |
|
||
| `text` | textarea input | string (multiline) |
|
||
| `number` | number input | number |
|
||
| `markdown` | rich text editor | string (markdown) |
|
||
| `datetime` | date picker | string (ISO date) |
|
||
| `select` | select input (dropdown) | string |
|
||
| `image` | file picker w/ drag-and-drop | image file |
|
||
| `file` | file picker w/ drag-and-drop | file |
|
||
| `hidden` | none | string |
|
||
| `object` | group of other widgets | Immutable Map containing field values |
|
||
| `list` | repeatable group of other widgets | Immutable List of objects containing field values |
|
||
| `relation` | text input w/ suggestions dropdown | value of `valueField` in related entry (see below) |
|
||
|
||
We’re always adding new widgets, and you can also [create your own](/docs/extending)!
|
||
|
||
### List Widget
|
||
|
||
The list widget allows you to map a user-provided string with a comma delimiter into a list. Consider the following example that also demonstrates how to set default values:
|
||
|
||
```yaml
|
||
collections:
|
||
- name: posts
|
||
label: Post
|
||
folder: "_posts"
|
||
slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
|
||
create: true
|
||
fields:
|
||
- {label: Title, name: title, widget: string, tagname: h1}
|
||
- {label: Body, name: body, widget: markdown}
|
||
- {label: Categories, name: categories, widget: list}
|
||
- {label: Tags, name: tags, widget: list, default: ['term_1', 'term_2']}
|
||
```
|
||
|
||
Lists of objects are supported as well and require a nested field list.
|
||
|
||
```yaml
|
||
collections:
|
||
- name: posts
|
||
label: Post
|
||
folder: "_posts"
|
||
slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
|
||
create: true
|
||
fields:
|
||
- {label: Title, name: title, widget: string, tagname: h1}
|
||
- {label: Body, name: body, widget: markdown}
|
||
- name: authors
|
||
label: Authors
|
||
widget: list
|
||
fields:
|
||
- {label: Name, name: name, widget: string}
|
||
- {label: Description, name: description, widget: markdown}
|
||
```
|
||
|
||
### Relation Widget
|
||
|
||
The relation widget allows you to reference an existing entry from within the entry you're editing. 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.
|
||
|
||
The following field configuration properties are specific to fields using the relation widget:
|
||
|
||
Property | Accepted Values | Description
|
||
--- | --- | ---
|
||
`collection` | string | name of the collection being referenced
|
||
`searchFields` | list | one or more names of fields in the referenced colleciton to search for the typed value
|
||
`valueField` | string | name a field from the referenced collection whose value will be stored for the relation
|
||
`name` | text input | string
|
||
|
||
Let's say we have a "posts" collection and an "authors" collection, and we want to select an author for each post - our config might look something like this:
|
||
|
||
```yaml
|
||
collections:
|
||
- name: authors
|
||
label: Authors
|
||
folder: "authors"
|
||
create: true
|
||
fields:
|
||
- {name: name, label: Name}
|
||
- {name: twitterHandle, label: "Twitter Handle"}
|
||
- {name: bio, label: Bio, widget: text}
|
||
- name: posts
|
||
label: Posts
|
||
folder: "posts"
|
||
create: true
|
||
fields:
|
||
- {name: title, label: Title}
|
||
- {name: body, label: Body, widget: markdown}
|
||
- name: author
|
||
label: Author
|
||
widget: relation
|
||
collection: authors
|
||
searchFields: [name, twitterHandle]
|
||
valueField: name
|
||
```
|