gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
static-cms/packages/docs/content/docs/collection-overview.mdx
Daniel Lautzenheiser 799c7e6936
feat: v4.0.0 (#1016) 
Co-authored-by: Denys Konovalov <kontakt@denyskon.de>
Co-authored-by: Mathieu COSYNS <64072917+Mathieu-COSYNS@users.noreply.github.com>
2024-01-03 15:14:09 -05:00

452 lines
24 KiB
Plaintext
Raw Blame History

---
group: Collections
title: Collections Configuration
weight: 9
---
`collections` accepts a list of collection objects, each with the following options
| Name | Type | Default | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | | Unique identifier for the collection, used as the key when referenced in other contexts (like the [relation widget](/docs/widgets/#relation)) |
| identifier_field | string | `'title'` | _Optional_. See [identifier field](#identifier-field) below |
| label | string | `name` | _Optional_. Label for the collection in the editor UI |
| label_singular | string | `label` | _Optional_. Singular label for certain elements in the editor |
| icon | string | | _Optional_. Unique name of icon to use in main menu. See [custom icons](/docs/custom-icons) |
| description | string | | _Optional_. Text displayed below the label when viewing a collection |
| files or folder | [Collection Files](/docs/collection-types#file-collections)<br />\| [Collection Folder](/docs/collection-types#folder-collections) | | **Requires one of these**: Specifies the collection type and location; details in [collection types](/docs/collection-types) |
| filter | FilterRule<br />\| List of FilterRules | | _Optional_. Field and file filter for [Folder Collections](/docs/collection-types#folder-collections). See [filtered folder collections](/docs/collection-types#filtered-folder-collections) |
| create | boolean | `false` | _Optional_. **For [Folder Collections](/docs/collection-types#folder-collections) only**<br />`true` - Allows users to create new items in the collection |
| publish | boolean | `true` | _Optional_ For `publish_mode: editorial_workflow` only;<br />`false` hides UI publishing controls for a collection |
| hide | boolean | `false` | _Optional_. `true` hides a collection in the Static CMS UI. Useful when using the relation widget to hide referenced collections |
| delete | boolean | `true` | _Optional_. `false` prevents users from deleting items in a collection |
| extension | string | | _Optional_. See [extension and format](#extension-and-format) below |
| format | 'yaml'<br />\| 'yml'<br />\| 'json'<br />\| 'frontmatter'<br />\| 'json-frontmatter'<br />\| 'yaml-frontmatter' | | _Optional_. See [extension and format](#extension-and-format) below |
| frontmatter_delimiter | string<br />\| [string, string] | | _Optional_. See [frontmatter delimiter](#frontmatter-delimiter) below |
| slug | string | | _Optional_. See [slug](#slug) below |
| fields (required) | Field | | _Optional_. See [fields](#fields) below. Ignored if [Files Collection](/docs/collection-types#file-collections) |
| editor | EditorConfig | | _Optional_. See [editor](#editor) below |
| summary | string | | _Optional_. See [summary](#summary) below |
| summary_fields | list of strings | ['summary'] | _Optional_. A list of fields to show in the table view |
| sortable_fields | SortableFields | | _Optional_. See [sortable fields](#sortable-fields) below |
| view_filters | ViewFilter | | _Optional_. See [view filters](#view-filters) below |
| view_groups | ViewGroup | | _Optional_. See [view groups](#view-groups) below |
## Identifier Field
Static CMS expects every entry to provide a field named `"title"` that serves as an identifier for the entry. The identifier field serves as an entry's title when viewing a list of entries, and is used in [slug](#slug) creation. If you would like to use a field other than `"title"` as the identifier, you can set `identifier_field` to the name of the other field.
<CodeTabs>
```yaml
collections:
- name: posts
identifier_field: name
```
```js
collections: [
{
name: 'posts',
identifier_field: 'name',
},
],
```
</CodeTabs>
## Extension and Format
These settings determine how collection files are parsed and saved. Both are optional—Static CMS will attempt to infer your settings based on existing items in the collection. If your collection is empty, or you'd like more control, you can set these fields explicitly.
`extension` determines the file extension searched for when finding existing entries in a folder collection and it determines the file extension used to save new collection items. It accepts the following values: `yml`, `yaml`, `json`, `md`, `markdown`, `mdx`, `html`.
You may also specify a custom `extension` not included in the list above, as long as the collection files can be parsed and saved in one of the supported formats below.
`format` determines how collection files are parsed and saved. It will be inferred if the `extension` field or existing collection file extensions match one of the supported extensions above. It accepts the following values:
- `yml` or `yaml`: parses and saves files as YAML-formatted data files; saves with `yml` extension by default
- `json`: parses and saves files as JSON-formatted data files; saves with `json` extension by default
- `toml`: parses and saves files as TOML-formatted data files; saves with `toml` extension by default
- `frontmatter`: parses files and saves files with data frontmatter followed by an unparsed body text (edited using a `body` field); saves with `md` extension by default; default for collections that cannot be inferred. Collections with `frontmatter` format (either inferred or explicitly set) can parse files with frontmatter in YAML or JSON format. However, they will be saved with YAML frontmatter.
- `yaml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as YAML, followed by unparsed body text. The default delimiter for this option is `---`.
- `json-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved as JSON, followed by unparsed body text. The default delimiter for this option is `{` `}`.
- `toml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as TOML, followed by unparsed body text. The default delimiter for this option is `+++`.
## Frontmatter Delimiter
If you have an explicit frontmatter format declared, the `frontmatter_delimiter` option allows you to specify a custom delimiter like `~~~`. If you need different beginning and ending delimiters, you can use an array like `["(", ")"]`.
## Slug
For folder collections where users can create new items, the `slug` option specifies a template for generating new filenames based on a file's creation date and `title` field. (This means that all collections with `create: true` must have a `title` field (a different field can be used via [`identifier_field`](#identifier_field)).
The slug template can also reference a field value by name, eg. `{{title}}`. If a field name conflicts with a built in template tag name - for example, if you have a field named `slug`, and would like to reference that field via `{{slug}}`, you can do so by adding the explicit `fields.` prefix, eg. `{{fields.slug}}`.
**Available Template Tags**
- Any field can be referenced by wrapping the field name in double curly braces, eg. `{{author}}`
- `{{slug}}`: a url-safe version of the `title` field (or identifier field) for the file
- `{{year}}`: 4-digit year of the file creation date
- `{{month}}`: 2-digit month of the file creation date
- `{{day}}`: 2-digit day of the month of the file creation date
- `{{hour}}`: 2-digit hour of the file creation date
- `{{minute}}`: 2-digit minute of the file creation date
- `{{second}}`: 2-digit second of the file creation date
### Examples
#### Basic Example
<CodeTabs>
```yaml
slug: '{{year}}-{{month}}-{{day}}_{{slug}}'
```
```js
slug: '{{year}}-{{month}}-{{day}}_{{slug}}',
```
</CodeTabs>
#### Field Names
<CodeTabs>
```yaml
slug: '{{year}}-{{month}}-{{day}}_{{title}}_{{some_other_field}}'
```
```js
slug: '{{year}}-{{month}}-{{day}}_{{title}}_{{some_other_field}}',
```
</CodeTabs>
#### Field Name That Conflicts With Template Tag
<CodeTabs>
```yaml
slug: '{{year}}-{{month}}-{{day}}_{{fields.slug}}'
```
```js
slug: '{{year}}-{{month}}-{{day}}_{{fields.slug}}',
```
</CodeTabs>
## Fields
_Ignored if [Files Collection](/docs/collection-types#file-collections)_
The `fields` option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in your Static CMS `config` file determines their order in the editor UI and in the saved file.
`fields` accepts a list of widgets. See [widgets](/docs/widgets) for more details.
In files with frontmatter, one field should be named `body`. This special field represents the section of the document (usually markdown) that comes after the frontmatter.
<CodeTabs>
```yaml
fields:
- label: "Title"
name: "title"
widget: "string"
pattern: ['.{20,}', "Must have at least 20 characters"]
- {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
- {label: "Featured Image", name: "thumbnail", widget: "image", required: false}
- {label: "Body", name: "body", widget: "markdown", comment: 'This is a multiline\ncomment' }
```
```js
fields: [
{ label: 'Title', name: 'title', widget: 'string', pattern: ['.{20,}', 'Must have at least 20 characters'] },
{ label: 'Layout', name: 'layout', widget: 'hidden', default: 'blog' },
{ label: 'Featured Image', name: 'thumbnail', widget: 'image', required: false },
{ label: 'Body', name: 'body', widget: 'markdown', comment: 'This is a multiline\\ncomment' },
],
```
</CodeTabs>
## Editor
The `editor` setting changes options for the editor view of a collection or a file inside a files collection. It has the following options:
| Name | Type | Default | Description |
| ------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| preview | boolean | `true` | Set to `false` to disable the preview pane for this collection or file |
| frame | boolean | `true` | <ul><li>`true` - Previews render in a frame</li><li>`false` - Previews render directly in your app</li></ul> |
| size | 'compact'<br />\|'half' | `compact` | The size of the editor:<ul><li>`compact` - `450px`</li><li>`half` - `50%` of the screen width </li></ul> |
<CodeTabs>
```yaml
editor:
preview: false
frame: false
```
```js
editor: {
preview: false,
frame: false,
},
```
</CodeTabs>
**Note**: Setting this as a top level configuration will set the default for all collections
## Summary
The `summary` setting allows the customization of the collection table view. Similar to the `slug` field, a string with templates can be used to include values of different fields, e.g. `{{title}}`. This option over-rides the default of `title` field and `identifier_field`.
**Available Template Tags**
Template tags are the same as those for [slug](#slug), with the following additions:
- `{{dirname}}` The path to the file's parent directory, relative to the collection's `folder`.
- `{{filename}}` The file name without the extension part.
- `{{extension}}` The file extension.
- `{{commit_date}}` The file commit date on supported backends (git based backends).
- `{{commit_author}}` The file author date on supported backends (git based backends).
<CodeTabs>
```yaml
summary: 'Version: {{version}} - {{title}}'
```
```js
summary: 'Version: {{version}} - {{title}}',
```
</CodeTabs>
### Template Transformations
You can apply transformations on fields in a summary string template using filter notation syntax.
Example config:
<CodeTabs>
```yaml
collections:
- name: 'posts'
label: 'Posts'
folder: '_posts'
summary: "{{title | upper}} - {{date | date('yyyy-MM-dd')}} - {{body | truncate(20, '***')}}"
fields:
- { label: 'Title', name: 'title', widget: 'string' }
- { label: 'Publish Date', name: 'date', widget: 'datetime' }
- { label: 'Body', name: 'body', widget: 'markdown' }
```
```js
collections: [
{
name: 'posts',
label: 'Posts',
folder: '_posts',
summary: "{{title | upper}} - {{date | date('yyyy-MM-dd')}} - {{body | truncate(20, '***')}}",
fields: [
{ label: 'Title', name: 'title', widget: 'string' },
{ label: 'Publish Date', name: 'date', widget: 'datetime' },
{ label: 'Body', name: 'body', widget: 'markdown' },
],
},
],
```
</CodeTabs>
The above config will transform the title field to uppercase and format the date field using `yyyy-MM-dd` format.
Available transformations are:
| Name | Format | Description |
| -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| upper | `upper` | Transforms the value to uppercase |
| lower | `lower` | Transforms the value to lowercase |
| date | `date('<format>')` | Formats a date string in the provided format. Accepts [date-fns tokens](https://date-fns.org/docs/format) |
| default | `default('defaultValue')` | Provides default value if no field value |
| ternary | `ternary('valueForTrue','valueForFalse')` | <ul><li>If field has value, show `valueForTrue`</li><li>If field does not have a value, show `valueForFalse`</li></ul> |
| truncate | `truncate(<number>)`<br />`truncate(<number>, '<string>')` | Truncates text to a specified length. An optional replacement string for the omitted text can be provided as a second parameter |
## Sortable Fields
The `sortable_fields` setting is an optional object with the following options:
| Name | Type | Default | Description |
| ------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| fields | list of string | | A list of sort fields to show in the UI |
| default | SortableFieldsDefault | | _Optional_. The default field and direction to sort the collection. See [Default Sort](#default-sort) for details |
Defaults to inferring `title`, `date`, `author` and `description` fields and will also show `Update On` sort field in git based backends.
When `author` field cannot be inferred commit author will be used.
<CodeTabs>
```yaml
# use dot notation for nested fields
sortable_fields:
fields: ['commit_date', 'title', 'commit_author', 'language.en']
```
```js
// use dot notation for nested fields
sortable_fields: {
fields: ['commit_date', 'title', 'commit_author', 'language.en'],
},
```
</CodeTabs>
### Default Sort
| Name | Type | Default | Description |
| --------- | ----------------------------------------------- | ----------- | --------------------------------- |
| field | string | | The field to sort |
| direction | 'Ascending'<br />\| 'Descending'<br />\| 'None' | `Ascending` | _Optional_. The direction to sort |
<CodeTabs>
```yaml
# use dot notation for nested fields
sortable_fields:
fields: ['commit_date', 'title', 'commit_author', 'language.en']
default:
field: commit_date
direction: Descending
```
```js
// use dot notation for nested fields
sortable_fields: {
fields: ['commit_date', 'title', 'commit_author', 'language.en'],
default: {
field: 'commit_date',
direction: 'Descending'
}
},
```
</CodeTabs>
## View Filters
The `view_filters` setting is an optional property which takes a list of predefined view filters to show in the UI and an optional default view filter.
<CodeTabs>
```yaml
view_filters:
default: drafts
filters:
- name: alice-and-bob
label: "Alice's and Bob's Posts"
field: author
pattern: 'Alice|Bob'
- name: posts-2020
label: 'Posts published in 2020'
field: date
pattern: '2020'
- name: drafts
label: Drafts
field: draft
pattern: true
```
```js
view_filters: {
default: 'drafts',
filters: [
{
name: 'alice-and-bob',
label: "Alice's and Bob's Posts",
field: 'author',
pattern: 'Alice|Bob',
},
{
name: 'posts-2020',
label: 'Posts published in 2020',
field: 'date',
pattern: '2020',
},
{
name: 'drafts',
label: 'Drafts',
field: 'draft',
pattern: true,
},
],
},
```
</CodeTabs>
## View Groups
The `view_groups` setting is an optional property which takes a list of predefined view groups to show in the UI and an optional default view group.
<CodeTabs>
```yaml
view_groups:
default: by-year
groups:
- name: by-year
label: Year
field: date
# groups items based on the value matched by the pattern
pattern: \d{4}
- name: drafts
label: Drafts
field: draft
```
```js
view_groups: {
default: by-year
groups: [
{
name: 'by-year',
label: 'Year',
field: 'date',
pattern: '\\d{4}',
},
{
name: 'drafts',
label: 'Drafts',
field: 'draft',
},
],
},
```
</CodeTabs>
## Media Library
The `media_library` settings allows customization of the media library at the collection level.
### Options
| Name | Type | Default | Description |
| --------------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| max_file_size | number | `512000` | _Optional_. The max size, in bytes, of files that can be uploaded to the media library |
| folder_support | boolean | `false` | _Optional_. Enables directory navigation and folder creation in your media library |
### Example
<CodeTabs>
```yaml
media_library:
max_file_size: 512000
folder_support: true
```
```js
{
media_library: {
max_file_size: 512000,
folder_support: true
}
}
```
</CodeTabs>
Reference in New Issue View Git Blame Copy Permalink