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

Update collection types documentation

Browse Source
This commit is contained in:
Daniel Lautzenheiser 2022-11-02 16:34:05 -04:00
parent af50c29bf1
commit 7a1ec55a5c
1 changed files with 111 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
website/content/docs/collection-types.mdx
View File

@ -3,6 +3,7 @@ group: Collections
title: Collection Types title: Collection Types
weight: 10 weight: 10
--- ---
All editable content types are defined in the `collections` field of your `config.yml` file, and display in the left sidebar of the Content page of the editor UI. All editable content types are defined in the `collections` field of your `config.yml` file, and display in the left sidebar of the Content page of the editor UI.
Collections come in two main types: `folder` and `files`. Collections come in two main types: `folder` and `files`.
@ -15,34 +16,52 @@ Unlike file collections, folder collections have the option to allow editors to
**Note:** Folder collections must have at least one field with the name `title` for creating new entry slugs. That field should use the default `string` widget. The `label` for the field can be any string value. If you wish to use a different field as your identifier, set `identifier_field` to the field name. See the [Collections reference doc](/docs/configuration-options/#collections) for details on how collections and fields are configured. If you forget to add this field, you will get an error that your collection "must have a field that is a valid entry identifier". **Note:** Folder collections must have at least one field with the name `title` for creating new entry slugs. That field should use the default `string` widget. The `label` for the field can be any string value. If you wish to use a different field as your identifier, set `identifier_field` to the field name. See the [Collections reference doc](/docs/configuration-options/#collections) for details on how collections and fields are configured. If you forget to add this field, you will get an error that your collection "must have a field that is a valid entry identifier".
Example: ### Examples
#### Basic
```yaml ```yaml
collections: collections:
- label: "Blog" - name: blog
title: "blog" label: Blog
folder: "_posts/blog" folder: _posts/blog
create: true create: true
fields: fields:
- {label: "Title", title: "title", widget: "string"} - name: title
- {label: "Publish Date", title: "date", widget: "datetime"} label: Title
- {label: "Featured Image", title: "thumbnail", widget: "image"} widget: string
- {label: "Body", title: "body", widget: "markdown"} - name: date
label: Publish Date
widget: datetime
- name: thumbnail
label: Featured Image
widget: image
- name: body
label: Body
widget: 'markdown
``` ```
With `identifier_field`: #### With Identifier Field
```yaml ```yaml
- label: "Blog" - name: 'blog'
title: "blog" label: 'Blog'
folder: "_posts/blog" folder: '_posts/blog'
create: true create: true
identifier_field: name identifier_field: name
fields: fields:
- {label: "Name", title: "name", widget: "string"} - name: name
- {label: "Publish Date", title: "date", widget: "datetime"} label: Name
- {label: "Featured Image", title: "thumbnail", widget: "image"} widget: string
- {label: "Body", title: "body", widget: "markdown"} - name: date
label: Publish Date
widget: datetime
- name: thumbnail
label: Featured Image
widget: image
- name: body
label: Body
widget: markdown
``` ```
### Filtered folder collections ### Filtered folder collections
@ -51,38 +70,56 @@ The entries for any folder collection can be filtered based on the value of a si
The `filter` option requires two fields: The `filter` option requires two fields:
* `field`: The name of the collection field to filter on. - `field`: The name of the collection field to filter on.
* `value`: The desired field value. - `value`: The desired field value.
The example below creates two collections in the same folder, filtered by the `language` field. The first collection includes posts with `language: en`, and the second, with `language: es`. The example below creates two collections in the same folder, filtered by the `language` field. The first collection includes posts with `language: en`, and the second, with `language: es`.
```yaml ```yaml
collections: collections:
- label: "Blog in English" - name: 'english_posts'
title: "english_posts" label: 'Blog in English'
folder: "_posts" folder: '_posts'
create: true create: true
filter: {field: "language", value: "en"} filter:
field: language
value: en
fields: fields:
- {label: "Language", title: "language", widget: "select", options: ["en", "es"]} - name: language
- {label: "Title", title: "title", widget: "string"} label: Language
- {label: "Content", title: "body", widget: "markdown"} widget: select
- label: "Blog en Español" options: ['en', 'es']
title: "spanish_posts" - name: title
folder: "_posts" label: Title
widget: string
- name: body
label: Content
widget: markdown
- name: spanish_posts
label: Blog en Español
folder: _posts
create: true create: true
filter: {field: "language", value: "es"} filter:
field: language
value: es
fields: fields:
- {label: "Lenguaje", title: "language", widget: "select", options: ["en", "es"]} - name: language
- {label: "Titulo", title: "title", widget: "string"} label: Lenguaje
- {label: "Contenido", title: "body", widget: "markdown"} widget: select
options: ['en', 'es']
- name: title
label: Titulo
widget: string
- name: body
label: Contenido
widget: markdown
``` ```
### Nested collections (beta) ### Nested Collections (Beta)
[Nested collections](/docs/beta-features/#nested-collections) is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory. As it is in beta, please use with discretion. [Nested collections](/docs/beta-features/#nested-collections) is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory. As it is in beta, please use with discretion.
## File collections ## File Collections
A `files` collection contains one or more uniquely configured files. Unlike items in `folder` collections, which repeat the same configuration over all files in the folder, each item in a `files` collection has an explicitly set path, filename, and configuration. This can be useful for unique files with a custom set of fields, like a settings file or a custom landing page with a unique content structure. A `files` collection contains one or more uniquely configured files. Unlike items in `folder` collections, which repeat the same configuration over all files in the folder, each item in a `files` collection has an explicitly set path, filename, and configuration. This can be useful for unique files with a custom set of fields, like a settings file or a custom landing page with a unique content structure.
@ -90,36 +127,54 @@ When configuring a `files` collection, configure each file in the collection sep
**Note:** Files listed in a file collection must already exist in the hosted repository branch set in your Static CMS [backend configuration](/docs/backends-overview). Files must also have a valid value for the file type. For example, an empty file works as valid YAML, but a JSON file must have a non-empty value to be valid, such as an empty object. **Note:** Files listed in a file collection must already exist in the hosted repository branch set in your Static CMS [backend configuration](/docs/backends-overview). Files must also have a valid value for the file type. For example, an empty file works as valid YAML, but a JSON file must have a non-empty value to be valid, such as an empty object.
Example: ### Example
```yaml ```yaml
collections: collections:
- label: "Pages" - name: pages
title: "pages" label: Pages
files: files:
- label: "About Page" - name: about
title: "about" label: About Page
file: "site/content/about.yml" file: site/content/about.yml
fields: fields:
- {label: Title, title: title, widget: string} - name: title
- {label: Intro, title: intro, widget: markdown} label: Title
- label: Team widget: string
title: team - name: intro
label: Intro
widget: markdown
- name: team
label: Team
widget: list widget: list
fields: fields:
- {label: Name, title: name, widget: string} - name: name
- {label: Position, title: position, widget: string} label: Name
- {label: Photo, title: photo, widget: image} widget: string
- label: "Locations Page" - name: position
title: "locations" label: Position
file: "site/content/locations.yml" widget: string
- name: photo
label: Photo
widget: image
- name: locations
label: Locations Page
file: site/content/locations.yml
fields: fields:
- {label: Title, title: title, widget: string} - name: title
- {label: Intro, title: intro, widget: markdown} label: Title
- label: Locations widget: string
title: locations - name: intro
label: Intro
widget: markdown
- name: locations
label: Locations
widget: list widget: list
fields: fields:
- {label: Name, title: name, widget: string} - name: name
- {label: Address, title: address, widget: string} label: Name
widget: string
- name: address
label: Address
widget: string
``` ```