gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(widget-relation): improve docs (#3990)

Browse Source
This commit is contained in:
Erez Rokah 2020-07-06 15:43:28 +03:00 committed by GitHub
parent f4b2999898
commit 2da824bf71
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
website/content/docs/widgets/relation.md
View File

@ -10,14 +10,14 @@ The relation widget allows you to reference items from another collection. It pr
- **Data type:** data type of the value pulled from the related collection item
- **Options:**
- `collection`: (**required**) name of the collection being referenced (string)
- `valueField`: (**required**) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use index notation to target a list item (e.g `categories.0`) or a wildcard `*` to target all list items (e.g. `categories.*`).
- `valueField`: (**required**) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use a wildcard `*` to target all list items (e.g. `categories.*`).
- `searchFields`: (**required**) list of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of *valueField*.
- `file`: allows referencing a specific file when the collection being referenced is a files collection (string)
- `displayFields`: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to `valueField`. Syntax to reference nested fields is similar to that of *valueField*.
- `default`: accepts any widget data type; defaults to an empty string
- `multiple` : accepts a boolean, defaults to `false`
- `optionsLength`: accepts integer to override number of options presented to user. Defaults to `20`.
- **Example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
- **Referencing a folder collection example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
```yaml
- label: "Post Author"
@ -31,7 +31,7 @@ The relation widget allows you to reference items from another collection. It pr
The generated UI input will search the authors collection by name and twitterHandle, and display each author's handle and follower count. On selection, the author name will be saved for the field.
- **Note:** `valueField` and `displayFields` support string templates. For example:
- **String templates example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
```yaml
- label: "Post Author"
@ -44,3 +44,18 @@ The generated UI input will search the authors collection by name and twitterHan
```
The generated UI input will search the authors collection by name, and display each author's handle and follower count. On selection, the author entry slug will be saved for the field.
- **Referencing a file collection list field example** (assuming a separate "relation_files" collection with a file named "cities" with a list field "cities" with subfields "name" and "id"):
```yaml
- label: "City"
name: "city"
widget: "relation"
collection: "relation_files"
file: "cities"
searchFields: ["cities.*.name"]
displayFields: ["cities.*.name"]
valueField: "cities.*.id"
```
The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id will be saved for the field.