113 lines
5.4 KiB
Plaintext
113 lines
5.4 KiB
Plaintext
---
|
|
title: Collection Configs
|
|
label: Collections
|
|
order: 20
|
|
desc: Structure your Collections for your needs by defining fields, adding slugs and labels, establishing access control, tying in hooks, setting timestamps and more.
|
|
keywords: collections, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
|
|
---
|
|
|
|
Payload Collections are defined through configs of their own, and you can define as many as your application needs. Each Collection will scaffold a MongoDB collection automatically based on fields that you define.
|
|
|
|
It's often best practice to write your Collections in separate files and then import them into the main Payload config.
|
|
|
|
## Options
|
|
|
|
| Option | Description |
|
|
| ---------------- | -------------|
|
|
| **`slug`** * | Unique, URL-friendly string that will act as an identifier for this Collection. |
|
|
| **`fields`** * | Array of field types that will determine the structure and functionality of the data stored within this Collection. [Click here](/docs/fields/overview) for a full list of field types as well as how to configure them. |
|
|
| **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. |
|
|
| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-options). |
|
|
| **`hooks`** | Entry points to "tie in" to Collection actions at specific points. [More](/docs/hooks/overview#collection-hooks) |
|
|
| **`access`** | Provide access control functions to define exactly who should be able to do what with Documents in this Collection. [More](/docs/access-control/overview/#collections) |
|
|
| **`auth`** | Specify options if you would like this Collection to feature authentication. For more, consult the [Authentication](/docs/authentication/config) documentation. |
|
|
| **`upload`** | Specify options if you would like this Collection to support file uploads. For more, consult the [Uploads](/docs/upload/overview) documentation. |
|
|
| **`timestamps`** | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps. |
|
|
|
|
*\* An asterisk denotes that a property is required.*
|
|
|
|
#### Simple collection example
|
|
|
|
```js
|
|
const Orders = {
|
|
slug: 'orders',
|
|
fields: [
|
|
{
|
|
name: 'total',
|
|
type: 'number',
|
|
required: true,
|
|
},
|
|
{
|
|
name: 'placedBy',
|
|
type: 'relationship',
|
|
relationTo: 'customers',
|
|
required: true,
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### More collection config examples
|
|
|
|
You can find an assortment of [example collection configs](https://github.com/payloadcms/payload/blob/master/demo/collections) in the Payload source code on GitHub.
|
|
|
|
### Admin options
|
|
|
|
You can customize the way that the Admin panel behaves on a collection-by-collection basis by defining the `admin` property on a collection's config.
|
|
|
|
| Option | Description |
|
|
| ---------------------------- | -------------|
|
|
| `useAsTitle` | Specify a top-level field to use for a document title throughout the Admin panel. If no field is defined, the ID of the document is used as the title. |
|
|
| `defaultColumns` | Array of field names that correspond to which columns to show by default in this collection's List view. |
|
|
| `disableDuplicate ` | Disables the "Duplicate" button while editing documents within this collection. |
|
|
| `enableRichTextRelationship` | The [Rich Text](/docs/fields/rich-text) field features a `Relationship` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default. |
|
|
| `preview` | Function to generate preview URLS within the Admin panel that can point to your app. [More](#preview). |
|
|
| `components` | Swap in your own React components to be used within this collection. [More](/docs/admin/components#collections) |
|
|
|
|
### Preview
|
|
|
|
Collection `admin` options can accept a `preview` function that will be used to generate a link pointing to the frontend of your app to preview data.
|
|
|
|
If the function is specified, a Preview button will automatically appear in the corresponding collection's Edit view. Clicking the Preview button will link to the URL that is generated by the function.
|
|
|
|
**The preview function accepts two arguments:**
|
|
|
|
1. The document being edited
|
|
1. An `options` object, containing `locale` and `token` properties. The `token` is the currently logged in user's JWT.
|
|
|
|
**Example collection with preview function:**
|
|
|
|
```js
|
|
{
|
|
slug: 'posts',
|
|
fields: [
|
|
{
|
|
name: 'slug',
|
|
type: 'text',
|
|
required: true,
|
|
}
|
|
]
|
|
admin: {
|
|
preview: (doc, { locale }) => {
|
|
if (doc?.slug) {
|
|
return `https://bigbird.com/preview/posts/${doc.slug}?locale=${locale}`,
|
|
}
|
|
|
|
return null;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Access control
|
|
|
|
You can specify extremely granular access control (what users can do with documents in a collection) on a collection by collection basis. To learn more, go to the [Access Control](/docs/access-control/overview) docs.
|
|
|
|
### Hooks
|
|
|
|
Hooks are a powerful way to extend collection functionality and execute your own logic, and can be defined on a collection by collection basis. To learn more, go to the [Hooks](/docs/hooks/overview) documentation.
|
|
|
|
### Field types
|
|
|
|
Collections support all field types that Payload has to offer—including simple fields like text and checkboxes all the way to more complicated layout-building field groups like Blocks. [Click here](/docs/fields/overview) to learn more about field types.
|