- The Rich Text field is a powerful way to allow editors to write dynamic
- content. The content is saved as JSON in the database and can be converted
- into any format, including HTML, that you need.
+
+ The Rich Text field is a powerful way to allow editors to write dynamic content. The content is saved as JSON in the database and can be converted into any format, including HTML, that you need.
The Admin component is built on the powerful [`slatejs`](https://docs.slatejs.org/) editor and is meant to be as extensible and customizable as possible.
-
- Consistent with Payload's goal of making you learn as litle of Payload as
- possible, customizing and using the Rich Text Editor does not involve
- learning how to develop for a Payload rich text editor.
- {" "}
- Instead, you can invest your time and effort into learning Slate, an
- open-source tool that will allow you to apply your learnings elsewhere as
- well.
+ Consistent with Payload's goal of making you learn as litle of Payload as possible, customizing and using the Rich Text Editor does not involve learning how to develop for a Payload rich text editor. Instead, you can invest your time and effort into learning Slate, an open-source tool that will allow you to apply your learnings elsewhere as well.
### Config
-| Option | Description |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`name`** \* | To be used as the property name when stored and retrieved from the database. |
-| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
-| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
-| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`** | Provide data to be used for this field's default value. |
-| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`** | Require this field to have a value. |
-| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). |
+| Option | Description |
+| ---------------- | ----------- |
+| **`name`** * | To be used as the property name when stored and retrieved from the database. |
+| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
+| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
+| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
+| **`defaultValue`** | Provide data to be used for this field's default value. |
+| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
+| **`required`** | Require this field to have a value. |
+| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
### Admin config
@@ -85,11 +76,8 @@ The default `leaves` available in Payload are:
The built-in `relationship` element is a powerful way to reference other Documents directly within your Rich Text editor.
- Tip:
-
- To enable collections to be selected within the Rich Text relationship, you
- need to enable the collection admin option of{" "}
- enableRichTextRelationship.
+ Tip:
+ To enable collections to be selected within the Rich Text relationship, you need to enable the collection admin option of enableRichTextRelationship.
### Specifying which elements and leaves to allow
@@ -104,11 +92,11 @@ Once you're up to speed with the general concepts involved, you can pass in your
**Both custom elements and leaves are defined via the following config:**
-| Property | Description |
-| --------------- | ---------------------------------------------------------- |
-| **`name`** \* | The name to be used as a `type` for this element. |
-| **`Button`** \* | A React component to be rendered in the Rich Text toolbar. |
-| **`plugins`** | An array of plugins to provide to the Rich Text editor. |
+| Property | Description |
+| ---------------- | ----------- |
+| **`name`** * | The name to be used as a `type` for this element. |
+| **`Button`** * | A React component to be rendered in the Rich Text toolbar. |
+| **`plugins`** | An array of plugins to provide to the Rich Text editor. |
Custom `Element`s also require the `Element` property set to a Reactt component to be rendered as the `Element` within the rich text editor itself.
@@ -117,7 +105,6 @@ Custom `Leaf` objects follow a similar pattern but require you to define the `Le
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
@@ -169,68 +156,110 @@ For more examples regarding how to define your own elements and leaves, check ou
As the Rich Text field saves its content in a JSON format, you'll need to render it as HTML yourself. Here is an example for how to generate JSX / HTML from Rich Text content:
```js
-import React, { Fragment } from "react";
-import escapeHTML from "escape-html";
-import { Text } from "slate";
+import React, { Fragment } from 'react';
+import escapeHTML from 'escape-html';
+import { Text } from 'slate';
-const serialize = (children) =>
- children.map((node, i) => {
- if (Text.isText(node)) {
- let text = (
-
+const serialize = (children) => children.map((node, i) => {
+ if (Text.isText(node)) {
+ let text = ;
+
+ if (node.bold) {
+ text = (
+
+ {text}
+
+ );
+ }
+
+ if (node.code) {
+ text = (
+
+ {text}
+
+ );
+ }
+
+ if (node.italic) {
+ text = (
+
+ {text}
+
+ );
+ }
+
+ // Handle other leaf types here...
+
+ return (
+
+ {text}
+
+ );
+ }
+
+ if (!node) {
+ return null;
+ }
+
+ switch (node.type) {
+ case 'h1':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ // Iterate through all headings here...
+ case 'h6':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ case 'quote':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ case 'ul':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ case 'ol':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ case 'li':
+ return (
+
+ {serialize(node.children)}
+
+ );
+ case 'link':
+ return (
+
+ {serialize(node.children)}
+
);
- if (node.bold) {
- text = {text};
- }
-
- if (node.code) {
- text = {text};
- }
-
- if (node.italic) {
- text = {text};
- }
-
- // Handle other leaf types here...
-
- return {text};
- }
-
- if (!node) {
- return null;
- }
-
- switch (node.type) {
- case "h1":
- return {serialize(node.children)}
;
- // Iterate through all headings here...
- case "h6":
- return {serialize(node.children)}
;
- case "quote":
- return {serialize(node.children)}
;
- case "ul":
- return {serialize(node.children)}
;
- case "ol":
- return {serialize(node.children)}
;
- case "li":
- return {serialize(node.children)};
- case "link":
- return (
-
- {serialize(node.children)}
-
- );
-
- default:
- return {serialize(node.children)}
;
- }
- });
+ default:
+ return (
+
+ {serialize(node.children)}
+
+ );
+ }
+});
```
- Note:
-
- The above example is for how to render to JSX, although for plain HTML the
- pattern is similar. Just remove the JSX and return HTML strings instead!
+ Note:
+ The above example is for how to render to JSX, although for plain HTML the pattern is similar. Just remove the JSX and return HTML strings instead!
diff --git a/docs/fields/row.mdx b/docs/fields/row.mdx
index c65619a49..32ad232bb 100644
--- a/docs/fields/row.mdx
+++ b/docs/fields/row.mdx
@@ -6,24 +6,22 @@ desc: With the Row field you can arrange fields next to each other in the Admin
keywords: row, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---
-
- The Row field is presentational-only and only affects the Admin panel. By
- using it, you can arrange fields next to each other horizontally.
+
+ The Row field is presentational-only and only affects the Admin panel. By using it, you can arrange fields next to each other horizontally.
### Config
-| Option | Description |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| **`fields`** \* | Array of field types to nest within this Row. |
-| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
+| Option | Description |
+| ---------------- | ----------- |
+| **`fields`** * | Array of field types to nest within this Row. |
+| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
diff --git a/docs/fields/select.mdx b/docs/fields/select.mdx
index 204fb857b..08577ac24 100644
--- a/docs/fields/select.mdx
+++ b/docs/fields/select.mdx
@@ -6,47 +6,40 @@ desc: The Select field provides a dropdown-style interface for choosing options
keywords: select, multi-select, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---
-
- The Select field provides a dropdown-style interface for choosing options from
- a predefined list as an enumeration.
+
+ The Select field provides a dropdown-style interface for choosing options from a predefined list as an enumeration.
### Config
-| Option | Description |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`name`** \* | To be used as the property name when stored and retrieved from the database. |
-| **`options`** \* | Array of options to allow the field to store. Can either be an array of strings, or an array of objects containing an `option` string and a `value` string. |
-| **`hasMany`** | Boolean when, if set to `true`, allows this field to have many selections instead of only one. |
-| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
-| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
-| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
-| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
-| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`** | Provide data to be used for this field's default value. |
-| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`** | Require this field to have a value. |
-| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
+| Option | Description |
+| ---------------- | ----------- |
+| **`name`** * | To be used as the property name when stored and retrieved from the database. |
+| **`options`** * | Array of options to allow the field to store. Can either be an array of strings, or an array of objects containing an `option` string and a `value` string. |
+| **`hasMany`** | Boolean when, if set to `true`, allows this field to have many selections instead of only one. |
+| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
+| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
+| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
+| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
+| **`defaultValue`** | Provide data to be used for this field's default value. |
+| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
+| **`required`** | Require this field to have a value. |
+| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
- Important:
-
- Option values should be strings that do not contain hyphens or special
- characters due to GraphQL enumeration naming constraints. Underscores are
- allowed. If you determine you need your option values to be non-strings or
- contain special characters, they will be formatted accordingly before being
- used as a GraphQL enum.
+ Important:
+ Option values should be strings that do not contain hyphens or special characters due to GraphQL enumeration naming constraints. Underscores are allowed. If you determine you need your option values to be non-strings or contain special characters, they will be formatted accordingly before being used as a GraphQL enum.
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
diff --git a/docs/fields/text.mdx b/docs/fields/text.mdx
index 6ee05dc5a..e7b14e7f5 100644
--- a/docs/fields/text.mdx
+++ b/docs/fields/text.mdx
@@ -6,32 +6,31 @@ desc: Text field types simply save a string to the database and provide the Admi
keywords: text, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---
-
- The Text field type is one of the most commonly used fields. It saves a string
- to the database and provides the Admin panel with a simple text input.
+
+ The Text field type is one of the most commonly used fields. It saves a string to the database and provides the Admin panel with a simple text input.
### Config
-| Option | Description |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`name`** \* | To be used as the property name when stored and retrieved from the database. |
-| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
-| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
-| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
-| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
-| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
-| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
-| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`** | Provide data to be used for this field's default value. |
-| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`** | Require this field to have a value. |
-| **`admin`** | Admin-specific configuration. See below for [more detail](#admin). |
+| Option | Description |
+| ---------------- | ----------- |
+| **`name`** * | To be used as the property name when stored and retrieved from the database. |
+| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
+| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
+| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
+| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
+| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
+| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
+| **`defaultValue`** | Provide data to be used for this field's default value. |
+| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
+| **`required`** | Require this field to have a value. |
+| **`admin`** | Admin-specific configuration. See below for [more detail](#admin). |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
### Admin config
@@ -48,7 +47,6 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
diff --git a/docs/fields/textarea.mdx b/docs/fields/textarea.mdx
index d1153d42a..891a0c295 100644
--- a/docs/fields/textarea.mdx
+++ b/docs/fields/textarea.mdx
@@ -6,32 +6,31 @@ desc: Textarea field types save a string to the database, similar to the Text fi
keywords: textarea, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---
-
- The Textarea field is almost identical to the Text field but it features a
- slightly larger input that is better suited to edit longer text.
+
+ The Textarea field is almost identical to the Text field but it features a slightly larger input that is better suited to edit longer text.
### Config
-| Option | Description |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`name`** \* | To be used as the property name when stored and retrieved from the database. |
-| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
-| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
-| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
-| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
-| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
-| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
-| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`** | Provide data to be used for this field's default value. |
-| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`** | Require this field to have a value. |
-| **`admin`** | Admin-specific configuration. See below for [more detail](#admin). |
+| Option | Description |
+| ---------------- | ----------- |
+| **`name`** * | To be used as the property name when stored and retrieved from the database. |
+| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`minLength`** | Used by the default validation function to ensure values are of a minimum character length. |
+| **`maxLength`** | Used by the default validation function to ensure values are of a maximum character length. |
+| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
+| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
+| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
+| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
+| **`defaultValue`** | Provide data to be used for this field's default value. |
+| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
+| **`required`** | Require this field to have a value. |
+| **`admin`** | Admin-specific configuration. See below for [more detail](#admin). |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
### Admin config
@@ -48,7 +47,6 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
diff --git a/docs/fields/upload.mdx b/docs/fields/upload.mdx
index e05d8f6a8..cc553fc30 100644
--- a/docs/fields/upload.mdx
+++ b/docs/fields/upload.mdx
@@ -6,18 +6,13 @@ desc: Upload fields will allow a file to be uploaded, only from a collection sup
keywords: upload, images media, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---
-
- The Upload field allows for the selection of a Document from a collection
- supporting Uploads, and formats the selection as a thumbnail in the Admin
- panel.
+
+ The Upload field allows for the selection of a Document from a collection supporting Uploads, and formats the selection as a thumbnail in the Admin panel.
- Important:
-
- To use this field, you need to have a Collection configured to allow Uploads.
- For more information, click here to read
- about how to enable Uploads on a collection by collection basis.
+ Important:
+ To use this field, you need to have a Collection configured to allow Uploads. For more information, click here to read about how to enable Uploads on a collection by collection basis.
**Example uses:**
@@ -28,30 +23,29 @@ keywords: upload, images media, fields, config, configuration, documentation, Co
### Config
-| Option | Description |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`name`** \* | To be used as the property name when stored and retrieved from the database. |
-| **`*relationTo`** \* | Provide a single collection `slug` to allow this field to accept a relation to. Note: the related collection must be configured to support Uploads. |
-| **`hasMany`** | Boolean when, if set to `true`, allows this field to have many relations instead of only one. |
-| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
-| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
-| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
+| Option | Description |
+| ---------------- | ----------- |
+| **`name`** * | To be used as the property name when stored and retrieved from the database. |
+| **`*relationTo`** * | Provide a single collection `slug` to allow this field to accept a relation to. Note: the related collection must be configured to support Uploads. |
+| **`hasMany`** | Boolean when, if set to `true`, allows this field to have many relations instead of only one. |
+| **`label`** | Used as a field label in the Admin panel and to name the generated GraphQL type. |
+| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. |
+| **`validate`** | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
| **`index`** | Build a [MongoDB index](https://docs.mongodb.com/manual/indexes/) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. |
-| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`** | Provide data to be used for this field's default value. |
-| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`** | Require this field to have a value. |
-| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
+| **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
+| **`hooks`** | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
+| **`access`** | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
+| **`defaultValue`** | Provide data to be used for this field's default value. |
+| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
+| **`required`** | Require this field to have a value. |
+| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
-_\* An asterisk denotes that a property is required._
+*\* An asterisk denotes that a property is required.*
### Example
`collections/ExampleCollection.js`
-
```js
{
slug: 'example-collection',
diff --git a/docs/getting-started/concepts.mdx b/docs/getting-started/concepts.mdx
index 5bce155c5..bf04d8881 100644
--- a/docs/getting-started/concepts.mdx
+++ b/docs/getting-started/concepts.mdx
@@ -11,7 +11,7 @@ Payload is based around a small and intuitive set of concepts. Before starting t
### Config
- The Payload config is where you configure everything that Payload does.
+ The Payload config is where you configure everything that Payload does.
By default, the Payload config lives in the root folder of your code and is named `payload.config.js` (`payload.config.ts` if you're using TypeScript), but you can customize its name and where you store it. You can write full functions and even full React components right into your config.
@@ -19,8 +19,7 @@ By default, the Payload config lives in the root folder of your code and is name
### Collections
- A Collection represents a type of content that Payload will store and can
- contain many documents.
+ A Collection represents a type of content that Payload will store and can contain many documents.
Collections define the shape of your data as well as all functionalities attached to that data. They will contain or many "documents", all corresponding with the same fields and functionalities that you define.
@@ -30,8 +29,7 @@ They can represent anything you can store in a database - for example - pages, p
### Globals
- A Global is a "one-off" piece of content that is perfect for storing
- navigational structures, themes, top-level meta data, and more.
+ A Global is a "one-off" piece of content that is perfect for storing navigational structures, themes, top-level meta data, and more.
Globals are in many ways similar to Collections, but there is only ever **one** instance of a Global, whereas Collections can contain many documents.
@@ -39,8 +37,7 @@ Globals are in many ways similar to Collections, but there is only ever **one**
### Fields
- Fields are the building blocks of Payload. Collections and Globals both use
- Fields to define the shape of the data that they store.
+ Fields are the building blocks of Payload. Collections and Globals both use Fields to define the shape of the data that they store.
Payload comes with [many different field types](../fields/overview) that give you a ton of flexibility while designing your API. Each Field type has its own potential properties that allow you to customize how they work.
@@ -48,8 +45,7 @@ Payload comes with [many different field types](../fields/overview) that give yo
### Hooks
- Hooks are where you can "tie in" to existing Payload actions to perform your
- own additional logic or modify how Payload operates altogether.
+ Hooks are where you can "tie in" to existing Payload actions to perform your own additional logic or modify how Payload operates altogether.
Hooks are an extremely powerful concept and are central to extending and customizing your app. Payload provides a wide variety of hooks which you can utilize. For example, imagine if you'd like to send an email every time a document is created in your Orders collection. To do so, you can add an `afterChange` hook function to your Orders collection that receives the Order data and allows you to send an email accordingly.
@@ -59,8 +55,7 @@ There are many more potential reasons to use Hooks. For more, visit the [Hooks d
### Access Control
- Access Control refers to Payload's system of defining who can do what to your
- API.
+ Access Control refers to Payload's system of defining who can do what to your API.
Access Control is extremely powerful but easy and intuitive to manage. You can easily define your own full-blown RBAC (role-based access control) or any other access control pattern that your scenario requires. No conventions or structure is forced on you whatsoever.
@@ -70,11 +65,10 @@ For more, visit the [Access Control documentation](/docs/access-control/overview
### Depth
- "Depth" gives you control over how many levels down related documents should
- be automatically populated when retrieved.
+ "Depth" gives you control over how many levels down related documents should be automatically populated when retrieved.
-You can specify population `depth` via query parameter in the REST API and by an option in the local API. _Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries._
+You can specify population `depth` via query parameter in the REST API and by an option in the local API. *Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries.*
**For example, let's look the following Collections:** `departments`, `users`, `posts`
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
index 097e7fe6b..450792ee7 100644
--- a/docs/getting-started/installation.mdx
+++ b/docs/getting-started/installation.mdx
@@ -2,7 +2,7 @@
title: Installation
label: Installation
order: 30
-desc: How do I install Payload CMS? To quickly get started with Payload, simply run npx create-payload-app. Read more for further instructions or to install from scratch.
+desc: To quickly get started with Payload, simply run npx create-payload-app or install from scratch.
keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
---
diff --git a/docs/getting-started/what-is-payload.mdx b/docs/getting-started/what-is-payload.mdx
index 843f2c157..bf7aa5978 100644
--- a/docs/getting-started/what-is-payload.mdx
+++ b/docs/getting-started/what-is-payload.mdx
@@ -2,7 +2,7 @@
title: What is Payload?
label: What is Payload?
order: 10
-desc: What is Payload? Payload is a next-gen headless CMS and application framework, equipped with dozens of features to provide a massive boost to your development process.
+desc: Payload is a next-gen headless Content Management System (CMS) and application framework.
keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
---
diff --git a/docs/graphql/extending.mdx b/docs/graphql/extending.mdx
index ce91308c8..d7cb2dcef 100644
--- a/docs/graphql/extending.mdx
+++ b/docs/graphql/extending.mdx
@@ -10,10 +10,10 @@ You can add your own GraphQL queries and mutations to Payload, making use of all
To do so, add your queries and mutations to the main Payload config as follows:
-| Config Path | Description |
-| ------------------- | --------------------------------------------------------------------------- |
-| `graphQL.queries` | Function that returns an object containing keys to custom GraphQL queries |
-| `graphQL.mutations` | Function that returns an object containing keys to custom GraphQL mutations |
+| Config Path | Description |
+| -------------------- | -------------|
+| `graphQL.queries` | Function that returns an object containing keys to custom GraphQL queries |
+| `graphQL.mutations` | Function that returns an object containing keys to custom GraphQL mutations |
The above properties each receive a function that is defined with the following arguments:
@@ -34,18 +34,18 @@ Both `graphQL.queries` and `graphQL.mutations` functions should return an object
`payload.config.js`:
```js
-import { buildConfig } from "payload/config";
-import myCustomQueryResolver from "./graphQL/resolvers/myCustomQueryResolver";
+import { buildConfig } from 'payload/config';
+import myCustomQueryResolver from './graphQL/resolvers/myCustomQueryResolver';
export default buildConfig({
- serverURL: "http://localhost:3000",
+ serverURL: 'http://localhost:3000',
graphQL: {
// highlight-start
queries: (GraphQL, payload) => {
return {
MyCustomQuery: {
type: new GraphQL.GraphQLObjectType({
- name: "MyCustomQuery",
+ name: 'MyCustomQuery',
fields: {
text: {
type: GraphQL.GraphQLString,
@@ -57,14 +57,14 @@ export default buildConfig({
args: {
argNameHere: {
type: new GraphQL.GraphQLNonNull(GraphQLString),
- },
+ }
},
resolve: myCustomQueryResolver,
- }),
- },
- };
- },
+ })
+ }
+ }
+ }
// highlight-end
- },
-});
+ }
+})
```
diff --git a/docs/hooks/collections.mdx b/docs/hooks/collections.mdx
index 1c96ba217..488fc7b84 100644
--- a/docs/hooks/collections.mdx
+++ b/docs/hooks/collections.mdx
@@ -27,7 +27,6 @@ Additionally, `auth`-enabled collections feature the following hooks:
All collection Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
`collections/example-hooks.js`
-
```js
// Collection config
module.exports = {
@@ -64,7 +63,7 @@ const beforeOperationHook = async ({
operation, // name of the operation
}) => {
return args; // Return operation arguments as necessary
-};
+}
```
### beforeValidate
@@ -79,7 +78,7 @@ const beforeValidateHook = async ({
originalDoc, // original document
}) => {
return data; // Return data to either create or update a document with
-};
+}
```
### beforeChange
@@ -94,7 +93,7 @@ const beforeChangeHook = async ({
originalDoc, // original document
}) => {
return data; // Return data to either create or update a document with
-};
+}
```
### afterChange
@@ -108,7 +107,7 @@ const afterChangeHook = async ({
operation, // name of the operation ie. 'create', 'update'
}) => {
return data;
-};
+}
```
### beforeRead
@@ -122,7 +121,7 @@ const beforeReadHook = async ({
query, // JSON formatted query
}) => {
return doc;
-};
+}
```
### afterRead
@@ -136,7 +135,7 @@ const afterReadHook = async ({
query, // JSON formatted query
}) => {
return doc;
-};
+}
```
### beforeDelete
@@ -173,7 +172,7 @@ const afterLoginHook = async ({
token, // user token
}) => {
return user;
-};
+}
```
### afterForgotPassword
@@ -187,5 +186,5 @@ const afterLoginHook = async ({
token, // user token
}) => {
return user;
-};
+}
```
diff --git a/docs/hooks/fields.mdx b/docs/hooks/fields.mdx
index e82d75dc5..777922733 100644
--- a/docs/hooks/fields.mdx
+++ b/docs/hooks/fields.mdx
@@ -26,7 +26,6 @@ Field-level hooks offer incredible potential for encapsulating your logic. They
## Config
Example field configuration:
-
```js
{
name: 'name',
@@ -48,33 +47,27 @@ Example field configuration:
All field-level hooks are formatted to accept the same arguments, although some arguments may be `undefined` based on which field hook you are utilizing.
- Tip:
-
- It's a good idea to conditionally scope your logic based on which operation is
- executing.
+ Tip:
+ It's a good idea to conditionally scope your logic based on which operation is executing.
#### Arguments
Field Hooks receive one `args` argument that contains the following properties:
-| Option | Description |
-| ----------------- | ------------------------------------------------------------------------------------------------ |
+| Option | Description |
+| ----------------- | -------------|
| **`value`** | The value of the field, before any updating. Will return `undefined` within `create` operations. |
-| **`data`** | The data passed to update the field with in `create` and `update` operations. |
-| **`originalDoc`** | The full original document in `update` or `read` operations. |
-| **`operation`** | A string relating to which operation the field type is currently executing within. |
-| **`req`** | The Express `request` object. It is mocked for Local API operations. |
+| **`data`** | The data passed to update the field with in `create` and `update` operations. |
+| **`originalDoc`** | The full original document in `update` or `read` operations. |
+| **`operation`** | A string relating to which operation the field type is currently executing within. |
+| **`req`** | The Express `request` object. It is mocked for Local API operations. |
#### Return value
Field hooks **must** return the intended value for the field to be used in the operation. You can modify the return value of the field before the operation continues, or simply send the `value` that you receive through the hook's argument. If you return `undefined` within a `beforeChange` or `beforeValidate` hook, the property will be unset from its document.
- Important
-
- Due to GraphQL's typed nature, you should never change the type of data that
- you return from a field, otherwise GraphQL will produce errors. If you need to
- change the shape or type of data, reconsider Field Hooks and instead evaluate
- if Collection / Global hooks might suit you better.
+ Important
+ Due to GraphQL's typed nature, you should never change the type of data that you return from a field, otherwise GraphQL will produce errors. If you need to change the shape or type of data, reconsider Field Hooks and instead evaluate if Collection / Global hooks might suit you better.
diff --git a/docs/hooks/globals.mdx b/docs/hooks/globals.mdx
index c5ce4e1bb..b89f33d1f 100644
--- a/docs/hooks/globals.mdx
+++ b/docs/hooks/globals.mdx
@@ -19,7 +19,6 @@ Globals feature the ability to define the following hooks:
All Global Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
`globals/example-hooks.js`
-
```js
// Global config
module.exports = {
@@ -49,7 +48,7 @@ const beforeValidateHook = async ({
originalDoc, // original document
}) => {
return data; // Return data to either create or update a document with
-};
+}
```
### beforeChange
@@ -64,7 +63,7 @@ const beforeChangeHook = async ({
originalDoc, // original document
}) => {
return data; // Return data to either create or update a document with
-};
+}
```
### afterChange
@@ -78,7 +77,7 @@ const afterChangeHook = async ({
operation, // name of the operation ie. 'create', 'update'
}) => {
return data;
-};
+}
```
### beforeRead
diff --git a/docs/hooks/overview.mdx b/docs/hooks/overview.mdx
index 4ec4716e8..1e040d121 100644
--- a/docs/hooks/overview.mdx
+++ b/docs/hooks/overview.mdx
@@ -7,9 +7,7 @@ keywords: hooks, overview, config, configuration, documentation, Content Managem
---
- Hooks are powerful ways to tie into existing Payload actions in order to add
- your own logic like integrating with third-party APIs, adding auto-generated
- data, or modifing Payload's base functionality.
+ Hooks are powerful ways to tie into existing Payload actions in order to add your own logic like integrating with third-party APIs, adding auto-generated data, or modifing Payload's base functionality.
**With Hooks, you can transform Payload from a traditional CMS into a fully-fledged application framework.**
diff --git a/docs/local-api/overview.mdx b/docs/local-api/overview.mdx
index 082ab681d..8c7ecd692 100644
--- a/docs/local-api/overview.mdx
+++ b/docs/local-api/overview.mdx
@@ -9,14 +9,8 @@ keywords: local api, config, configuration, documentation, Content Management Sy
The Payload Local API gives you the ability to execute the same operations that are available through REST and GraphQL within Node, directly on your server. Here, you don't need to deal with server latency or network speed whatsoever and can interact directly with your database.
- Tip:
-
- The Local API is incredibly powerful when used with server-side rendering app
- frameworks like NextJS. With other headless CMS, you need to request your data
- from third-party servers which can add significant loading time to your
- server-rendered pages. With Payload, you don't have to leave your server to
- gather the data you need. It can be incredibly fast and is definitely a game
- changer.
+ Tip:
+ The Local API is incredibly powerful when used with server-side rendering app frameworks like NextJS. With other headless CMS, you need to request your data from third-party servers which can add significant loading time to your server-rendered pages. With Payload, you don't have to leave your server to gather the data you need. It can be incredibly fast and is definitely a game changer.
Here are some common examples of how you can use the Local API:
@@ -34,15 +28,14 @@ You can gain access to the currently running `payload` object via two ways:
You can import or require `payload` into your own files after it's been initialized, but you need to make sure that your `import` / `require` statements come **after** you call `payload.init()`—otherwise Payload won't have been initialized yet. That might be obvious. To us, it's usually not.
Example:
-
```js
-import payload from "payload";
+import payload from 'payload';
const afterChangeHook = async () => {
const posts = await payload.find({
- collection: "posts",
+ collection: 'posts',
});
-};
+}
```
##### Accessing from the `req`
@@ -50,38 +43,34 @@ const afterChangeHook = async () => {
Payload is available anywhere you have access to the Express `req` - including within your access control and hook functions.
Example:
-
```js
-const afterChangeHook = async ({ req: { payload } }) => {
+const afterChangeHook = async ({ req: { payload }}) => {
const posts = await payload.find({
- collection: "posts",
+ collection: 'posts',
});
-};
+}
```
### Local options available
You can specify more options within the Local API vs. REST or GraphQL due to the server-only context that they are executed in.
-| Local Option | Description |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `collection` | Required for Collection operations. Specifies the Collection slug to operate against. |
-| `data` | The data to use within the operation. Required for `create`, `update`. |
-| `depth` | [Control auto-population](/docs/getting-started/concepts#depth) of nested relationship and upload fields. |
-| `locale` | Specify [locale](/docs/configuration/localization) for any returned documents. |
-| `fallbackLocale` | Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents. |
-| `overrideAccess` | Skip access control. By default, this property is set to false. |
-| `user` | If you re-enable access control, you can specify a user to use against the access control checks. |
-| `showHiddenFields` | Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config. |
+| Local Option | Description |
+| -------------------- | ------------ |
+| `collection` | Required for Collection operations. Specifies the Collection slug to operate against. |
+| `data` | The data to use within the operation. Required for `create`, `update`. |
+| `depth` | [Control auto-population](/docs/getting-started/concepts#depth) of nested relationship and upload fields. |
+| `locale` | Specify [locale](/docs/configuration/localization) for any returned documents. |
+| `fallbackLocale` | Specify a [fallback locale](/docs/configuration/localization) to use for any returned documents. |
+| `overrideAccess` | Skip access control. By default, this property is set to false. |
+| `user` | If you re-enable access control, you can specify a user to use against the access control checks. |
+| `showHiddenFields` | Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config. |
-_There are more options available on an operation by operation basis outlined below._
+*There are more options available on an operation by operation basis outlined below.*
- Note:
-
- By default, all access control checks are disabled in the Local API, but you
- can re-enable them if you'd like, as well as pass a specific user to run the
- operation with.
+ Note:
+ By default, all access control checks are disabled in the Local API, but you can re-enable them if you'd like, as well as pass a specific user to run the operation with.
## Collections
@@ -93,13 +82,12 @@ The following Collection operations are available through the Local API:
```js
// The created Post document is returned
const post = await payload.create({
- collection: "posts", // required
- data: {
- // required
- title: "sure",
- description: "maybe",
+ collection: 'posts', // required
+ data: { // required
+ title: 'sure',
+ description: 'maybe',
},
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUserDoc,
overrideAccess: true,
@@ -108,7 +96,7 @@ const post = await payload.create({
// If creating verification-enabled auth doc,
// you can optionally disable the email that is auto-sent
disableVerificationEmail: true,
-});
+})
```
#### Find
@@ -136,15 +124,15 @@ const result = await payload.find({
```js
// Result will be a Post document.
const result = await payload.findByID({
- collection: "posts", // required
- id: "507f1f77bcf86cd799439011", // required
+ collection: 'posts', // required
+ id: '507f1f77bcf86cd799439011', // required
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUser,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
#### Update
@@ -152,20 +140,19 @@ const result = await payload.findByID({
```js
// Result will be the updated Post document.
const result = await payload.update({
- collection: "posts", // required
- id: "507f1f77bcf86cd799439011", // required
- data: {
- // required
- title: "sure",
- description: "maybe",
+ collection: 'posts', // required
+ id: '507f1f77bcf86cd799439011', // required
+ data: { // required
+ title: 'sure',
+ description: 'maybe',
},
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUser,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
#### Delete
@@ -173,15 +160,15 @@ const result = await payload.update({
```js
// Result will be the now-deleted Post document.
const result = await payload.delete({
- collection: "posts", // required
- id: "507f1f77bcf86cd799439011", // required
+ collection: 'posts', // required
+ id: '507f1f77bcf86cd799439011', // required
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUser,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
## Auth Operations
@@ -199,20 +186,19 @@ If a collection has [`Authentication`](/docs/authentication/overview) enabled, a
// }
const result = await payload.login({
- collection: "users", // required
- data: {
- // required
- email: "dev@payloadcms.com",
- password: "rip",
+ collection: 'users', // required
+ data: { // required
+ email: 'dev@payloadcms.com',
+ password: 'rip',
},
req: req, // pass an Express `req` which will be provided to all hooks
res: res, // used to automatically set an HTTP-only auth cookie
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
#### Forgot Password
@@ -220,13 +206,12 @@ const result = await payload.login({
```js
// Returned token will allow for a password reset
const token = await payload.forgotPassword({
- collection: "users", // required
- data: {
- // required
- email: "dev@payloadcms.com",
+ collection: 'users', // required
+ data: { // required
+ email: 'dev@payloadcms.com',
},
req: req, // pass an Express `req` which will be provided to all hooks
-});
+})
```
#### Reset Password
@@ -238,14 +223,13 @@ const token = await payload.forgotPassword({
// user: { ... } // the user document that just logged in
// }
const result = await payload.forgotPassword({
- collection: "users", // required
- data: {
- // required
- token: "afh3o2jf2p3f...", // the token generated from the forgotPassword operation
+ collection: 'users', // required
+ data: { // required
+ token: 'afh3o2jf2p3f...', // the token generated from the forgotPassword operation
},
req: req, // pass an Express `req` which will be provided to all hooks
res: res, // used to automatically set an HTTP-only auth cookie
-});
+})
```
#### Unlock
@@ -253,14 +237,13 @@ const result = await payload.forgotPassword({
```js
// Returned result will be a boolean representing success or failure
const result = await payload.unlock({
- collection: "users", // required
- data: {
- // required
- email: "dev@payloadcms.com",
+ collection: 'users', // required
+ data: { // required
+ email: 'dev@payloadcms.com',
},
req: req, // pass an Express `req` which will be provided to all hooks
overrideAccess: true,
-});
+})
```
#### Verify
@@ -268,9 +251,9 @@ const result = await payload.unlock({
```js
// Returned result will be a boolean representing success or failure
const result = await payload.verify({
- collection: "users", // required
- token: "afh3o2jf2p3f...", // the token saved on the user as `_verificationToken`
-});
+ collection: 'users', // required
+ token: 'afh3o2jf2p3f...', // the token saved on the user as `_verificationToken`
+})
```
## Globals
@@ -282,14 +265,14 @@ The following Global operations are available through the Local API:
```js
// Result will be the Header Global.
const result = await payload.findGlobal({
- global: "header", // required
+ global: 'header', // required
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUser,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
#### Update
@@ -297,23 +280,22 @@ const result = await payload.findGlobal({
```js
// Result will be the updated Header Global.
const result = await payload.updateGlobal({
- global: "header", // required
- data: {
- // required
+ global: 'header', // required
+ data: { // required
nav: [
{
- url: "https://google.com",
+ url: 'https://google.com',
},
{
- url: "https://payloadcms.com",
+ url: 'https://payloadcms.com',
},
],
},
depth: 2,
- locale: "en",
+ locale: 'en',
fallbackLocale: false,
user: dummyUser,
overrideAccess: false,
showHiddenFields: true,
-});
+})
```
diff --git a/docs/production/deployment.mdx b/docs/production/deployment.mdx
index cdbed17b1..bd2b2cd9d 100644
--- a/docs/production/deployment.mdx
+++ b/docs/production/deployment.mdx
@@ -7,9 +7,7 @@ keywords: deployment, production, config, configuration, documentation, Content
---
- So you've developed a Payload app, it's fully tested, and running great
- locally. Now it's time to launch. Awesome! Great work! Now,
- what's next?
+ So you've developed a Payload app, it's fully tested, and running great locally. Now it's time to launch. Awesome! Great work! Now, what's next?
There are many ways to deploy Payload to a production environment. When evaluating how you will deploy Payload, you need to consider these main aspects:
@@ -31,13 +29,7 @@ When you initialize Payload, you provide it with a `secret` property. This prope
Because _**you**_ are in complete control of who can do what with your data, you should double and triple-check that you wield that power responsibly before deploying to Production.
-
- By default, all Access Control functions require that a user is successfully
- logged in to Payload to create, read, update, or delete data.
- {" "}
- But, if you allow public user registration, for example, you will want to make
- sure that your access control functions are more strict - permitting{" "}
- only appropriate users to perform appropriate actions.
+ By default, all Access Control functions require that a user is successfully logged in to Payload to create, read, update, or delete data. But, if you allow public user registration, for example, you will want to make sure that your access control functions are more strict - permitting only appropriate users to perform appropriate actions.
##### Building the Admin panel
@@ -45,7 +37,6 @@ Because _**you**_ are in complete control of who can do what with your data, you
Before running in Production, you need to have built a production-ready copy of the Payload Admin panel. To do this, Payload provides the `build` NPM script. You can use it by adding a `script` to your `package.json` file like this:
`package.json`:
-
```js
{
"name": "project-name-here",
@@ -104,18 +95,15 @@ Alternatively, persistent filesystems will never delete your files and can be tr
- Many other more traditional web hosts
- Warning:
-
- If you rely on Payload's Upload functionality, make sure you
- either use a host with a persistent filesystem or have an integration with a
- third-party file host like Amazon S3.
+ Warning:
+ If you rely on Payload's Upload functionality, make sure you either use a host with a persistent filesystem or have an integration with a third-party file host like Amazon S3.
##### Using ephemeral filesystem providers like Heroku
If you don't use Payload's `upload` functionality, you can go ahead and use Heroku or similar platform easily. Everything will work exactly as you want it to.
-But, if you do, and you still want to use an ephemeral filesystem provider, you can write a hook-based solution to _copy_ the files your users upload to a more permanent storage solution like Amazon S3 or DigitalOcean Spaces.
+But, if you do, and you still want to use an ephemeral filesystem provider, you can write a hook-based solution to *copy* the files your users upload to a more permanent storage solution like Amazon S3 or DigitalOcean Spaces.
**To automatically send uploaded files to S3 or similar, you could:**
diff --git a/docs/production/licensing.mdx b/docs/production/licensing.mdx
index a0af675d6..37b6ac529 100644
--- a/docs/production/licensing.mdx
+++ b/docs/production/licensing.mdx
@@ -16,9 +16,8 @@ Payload is free to use locally for development purposes for as long as you like.
1. Add your license to a `.env` variable, and then add the `license` property to your `payload.init()` call.
`server.js`:
-
```js
-const payload = require("payload");
+const payload = require('payload');
payload.init({
license: process.env.PAYLOAD_LICENSE_KEY,
@@ -33,17 +32,13 @@ payload.init({
Payload licensing is enforced only through its Admin panel. Each time the Admin panel is loaded, a request is made to our licensing server that evaluates the domain that the panel was loaded from. We then verify that you have a valid, active license key and that the domain being used matches the license accordingly.
- Note:
-
- Your Payload APIs will always be available, regardless of subscription status.
- This means you can have peace of mind that your critical operations relying on
- your API will not going to be hindered because of a lapse in billing issue or
- a network problem between systems. Only the Admin panel will be affected.
+ Note:
+ Your Payload APIs will always be available, regardless of subscription status. This means you can have peace of mind that your critical operations relying on your API will not going to be hindered because of a lapse in billing issue or a network problem between systems. Only the Admin panel will be affected.
### How to choose the domain for your license
-Payload licenses are specific to **one** domain, but you can use your Payload API from an unlimited amount of sources. However, you can _only access your Payload Admin panel from one domain_. This means that when you are selecting the domain you'd like to tie to your Payload license, you should choose the domain that you'd like to use to access your admin panel in production.
+Payload licenses are specific to **one** domain, but you can use your Payload API from an unlimited amount of sources. However, you can *only access your Payload Admin panel from one domain*. This means that when you are selecting the domain you'd like to tie to your Payload license, you should choose the domain that you'd like to use to access your admin panel in production.
**Examples:**
@@ -51,10 +46,8 @@ Payload licenses are specific to **one** domain, but you can use your Payload AP
- If you'd like to access via a root-level domain like `coolsitehere.com/admin`, you would use `coolsitehere.com` for your license.
- Note:
-
- Even though your Payload license is tied to one domain, you can use your Admin
- panel for dev purposes however and wherever you'd like.
+ Note:
+ Even though your Payload license is tied to one domain, you can use your Admin panel for dev purposes however and wherever you'd like.
#### How does Payload know if the license is being used for dev or production purposes?
@@ -72,5 +65,4 @@ Our licensing service checks for any of the following criteria to determine if y
1. **Can I transfer a license?** You can change the domain name of a license in your Payload account by clicking on the license domain name, finding the "Change domain" link and following the instructions. If you need to transfer ownership to another user or organization, you can [contact us](mailto:info@payloadcms.com) for help.
### Read the full license
-
You can read the entirety of the Payload license directly in the distributed NPM package or in the Payload source code at [github.com](https://github.com/payloadcms/payload/blob/master/license.md)
diff --git a/docs/production/preventing-abuse.mdx b/docs/production/preventing-abuse.mdx
index d8f3ff1fc..4104dee77 100644
--- a/docs/production/preventing-abuse.mdx
+++ b/docs/production/preventing-abuse.mdx
@@ -18,22 +18,16 @@ Set the max number of failed login attempts before a user account is locked out
To prevent DDoS, brute-force, and similar attacks, you can set IP-based rate limits so that once a certain threshold of requests has been hit by a single IP, further requests from the same IP will be ignored. The Payload config `rateLimit` property accepts an object with the following properties:
-| Option | Description |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`window`** | Time in milliseconds to track requests per IP |
-| **`max`** | Number of requests served from a single IP before limiting |
-| **`skip`** | Express middleware function that can return true (or promise resulting in true) that will bypass limit |
-| **`trustProxy`** | True or false, to enable to allow requests to pass through a proxy such as a load balancer or an `nginx` reverse proxy |
+| Option | Description |
+| ---------------------------- | -------------|
+| **`window`** | Time in milliseconds to track requests per IP |
+| **`max`** | Number of requests served from a single IP before limiting |
+| **`skip`** | Express middleware function that can return true (or promise resulting in true) that will bypass limit |
+| **`trustProxy`** | True or false, to enable to allow requests to pass through a proxy such as a load balancer or an `nginx` reverse proxy |
- Warning:
-
- Very commonly, NodeJS apps are served behind `nginx` reverse proxies and
- similar. If you use rate-limiting while you're behind a proxy,{" "}
- all IP addresses from everyone that uses your API will appear
- as if they are from a local origin (127.0.0.1), and your users will get
- rate-limited very quickly without cause. If you plan to host your app behind a
- proxy, make sure you set trustProxy to true.
+ Warning:
+ Very commonly, NodeJS apps are served behind `nginx` reverse proxies and similar. If you use rate-limiting while you're behind a proxy, all IP addresses from everyone that uses your API will appear as if they are from a local origin (127.0.0.1), and your users will get rate-limited very quickly without cause. If you plan to host your app behind a proxy, make sure you set trustProxy to true.
#### Max Depth
@@ -49,7 +43,6 @@ CSRF prevention will verify the authenticity of each request to your API to prev
To securely allow headless operation you will need to configure the allowed origins for requests to be able to use the Payload API. You can see how to set CORS as well as other payload configuration settings [here](http://localhost:3000/docs/configuration/overview)
### Limiting GraphQL Complexity
-
Because GraphQL gives the power of query writing outside a server's control, someone with bad intentions might write a maliciously complex query and bog down your server. To prevent resource-intensive GraphQL requests, Payload provides a way specify complexity limits which are based on a complexity score that is calculated for each request.
Any GraphQL request that is calculated to be too expensive is rejected. On the Payload config, in `graphQL` you can set the `maxComplexity` value as an integer. For reference, the default complexity value for each added field is 1, and all `relationship` and `upload` fields are assigned a value of 10.
diff --git a/docs/queries/overview.mdx b/docs/queries/overview.mdx
index 1b09d3582..a4fddbca7 100644
--- a/docs/queries/overview.mdx
+++ b/docs/queries/overview.mdx
@@ -9,15 +9,7 @@ keywords: query, documents, overview, documentation, Content Management System,
Payload provides an extremely granular querying language through all APIs. Each API takes the same syntax and fully supports all options.
-
- Here, "querying" relates to filtering or searching through documents within
- a Collection.
- {" "}
- You can build queries to pass to Find operations as well as to{" "}
-
- restrict which documents certain users can access
- {" "}
- via access control functions.
+ Here, "querying" relates to filtering or searching through documents within a Collection. You can build queries to pass to Find operations as well as to restrict which documents certain users can access via access control functions.
### Simple queries
@@ -26,54 +18,55 @@ For example, say you have a collection as follows:
```js
const Post = {
- slug: "posts",
+ slug: 'posts',
fields: [
{
- name: "color",
- type: "select",
- options: ["mint", "dark-gray", "white"],
+ name: 'color',
+ type: 'select',
+ options: [
+ 'mint',
+ 'dark-gray',
+ 'white',
+ ],
},
{
- name: "featured",
- type: "checkbox",
- },
- ],
-};
+ name: 'featured',
+ type: 'checkbox',
+ }
+ ]
+}
```
You may eventually have a lot of documents within this Collection. If you wanted to find only documents with `color` equal to `mint`, you could write a query as follows:
```js
const query = {
- color: {
- // property name to filter on
- equals: "mint", // operator to use and value to compare against
+ color: { // property name to filter on
+ equals: 'mint', // operator to use and value to compare against
},
-};
+}
```
The above example demonstrates a simple query but you can get much more complex.
### Operators
-| Operator | Description |
-| -------------------- | ----------------------------------------------------------------------------------------- |
-| `equals` | The value must be exactly equal. |
-| `not_equals` | The query will return all documents where the value is not equal. |
-| `greater_than` | For numeric or date-based fields. |
-| `greater_than_equal` | For numeric or date-based fields. |
-| `less_than` | For numeric or date-based fields. |
-| `less_than_equal` | For numeric or date-based fields. |
-| `like` | The value must partially match. |
-| `in` | The value must be found within the provided comma-delimited list of values. |
-| `not_in` | The value must NOT be within the provided comma-delimited list of values. |
+| Operator | Description |
+| -------------------- | ------------ |
+| `equals` | The value must be exactly equal. |
+| `not_equals` | The query will return all documents where the value is not equal. |
+| `greater_than` | For numeric or date-based fields. |
+| `greater_than_equal` | For numeric or date-based fields. |
+| `less_than` | For numeric or date-based fields. |
+| `less_than_equal` | For numeric or date-based fields. |
+| `like` | The value must partially match. |
+| `in` | The value must be found within the provided comma-delimited list of values. |
+| `not_in` | The value must NOT be within the provided comma-delimited list of values. |
| `exists` | Only return documents where the value either exists (`true`) or does not exist (`false`). |
- Tip:
- If you know your users will be querying on certain fields a lot, you can add
- index: true
- to a field's config which will speed up searches using that field immensely.
+ Tip:
+ If you know your users will be querying on certain fields a lot, you can add index: true to a field's config which will speed up searches using that field immensely.
### And / Or Logic
@@ -82,30 +75,28 @@ In addition to defining simple queries, you can join multiple queries together u
```js
const query = {
- or: [
- // array of OR conditions
+ or: [ // array of OR conditions
{
color: {
- equals: "mint",
+ equals: 'mint',
},
},
{
- and: [
- // nested array of AND conditions
+ and: [ // nested array of AND conditions
{
color: {
- equals: "white",
- },
+ equals: 'white',
+ }
},
{
featured: {
equals: false,
- },
- },
- ],
- },
- ],
-};
+ }
+ }
+ ]
+ }
+ ]
+}
```
Written in plain English, if the above query were passed to a `find` operation, it would translate to finding posts where either the `color` is `mint` OR the `color` is `white` AND `featured` is set to false.
@@ -140,29 +131,24 @@ This one isn't too bad, but more complex queries get unavoidably more difficult
**For example, using fetch:**
```js
-import qs from "qs";
+import qs from 'qs';
const query = {
color: {
- equals: "mint",
+ equals: 'mint',
},
// This query could be much more complex
// and QS would handle it beautifully
-};
+}
const getPosts = async () => {
- const stringifiedQuery = qs.stringify(
- {
- where: query, // ensure that `qs` adds the `where` property, too!
- },
- { addQueryPrefix: true }
- );
+ const stringifiedQuery = qs.stringify({
+ where: query // ensure that `qs` adds the `where` property, too!
+ }, { addQueryPrefix: true });
- const response = await fetch(
- `http://localhost:3000/api/posts${stringifiedQuery}`
- );
+ const response = await fetch(`http://localhost:3000/api/posts${stringifiedQuery}`);
// Continue to handle the response below...
-};
+}
```
### Local API Queries
@@ -172,18 +158,19 @@ The Local API's `find` operation accepts an object exactly how you write it. For
```js
const getPosts = async () => {
const posts = await payload.find({
- collection: "posts",
+ collection: 'posts',
where: {
color: {
- equals: "mint",
+ equals: 'mint',
},
},
});
return posts;
-};
+}
```
+
## Sort
Payload `find` queries support a `sort` parameter through all APIs. Pass the `name` of a top-level field to sort by that field in ascending order. Prefix the name of the field with a minus symbol ("-") to sort in descending order.
@@ -192,7 +179,6 @@ Payload `find` queries support a `sort` parameter through all APIs. Pass the `na
**`https://localhost:3000/api/posts?sort=-createdAt`**
**GraphQL example:**
-
```
query {
Posts(sort: "-createdAt") {
@@ -208,10 +194,10 @@ query {
```js
const getPosts = async () => {
const posts = await payload.find({
- collection: "posts",
- sort: "-createdAt",
+ collection: 'posts',
+ sort: '-createdAt',
});
return posts;
-};
+}
```
diff --git a/docs/queries/pagination.mdx b/docs/queries/pagination.mdx
index 0dc38b374..665cfe975 100644
--- a/docs/queries/pagination.mdx
+++ b/docs/queries/pagination.mdx
@@ -10,21 +10,20 @@ All collection `find` queries are paginated automatically. Responses are returne
**`Find` response properties:**
-| Property | Description |
-| ------------- | --------------------------------------------------------- |
-| docs | Array of documents in the collection |
-| totalDocs | Total available documents within the collection |
-| limit | Limit query parameter - defaults to `10` |
-| totalPages | Total pages available, based upon the `limit` queried for |
-| page | Current page number |
-| pagingCounter | `number` of the first doc on the current page |
-| hasPrevPage | `true/false` if previous page exists |
-| hasNextPage | `true/false` if next page exists |
-| prevPage | `number` of previous page, `null` if it doesn't exist |
-| nextPage | `number` of next page, `null` if it doesn't exist |
+| Property | Description |
+| ------------- | ---------------------------------------------------------- |
+| docs | Array of documents in the collection |
+| totalDocs | Total available documents within the collection |
+| limit | Limit query parameter - defaults to `10` |
+| totalPages | Total pages available, based upon the `limit` queried for |
+| page | Current page number |
+| pagingCounter | `number` of the first doc on the current page |
+| hasPrevPage | `true/false` if previous page exists |
+| hasNextPage | `true/false` if next page exists |
+| prevPage | `number` of previous page, `null` if it doesn't exist |
+| nextPage | `number` of next page, `null` if it doesn't exist |
**Example response:**
-
```js
{
// Document Array // highlight-line
@@ -55,7 +54,7 @@ All collection `find` queries are paginated automatically. Responses are returne
All Payload APIs support the pagination controls below. With them, you can create paginated lists of documents within your application:
-| Control | Description |
-| ------- | --------------------------------------- |
-| `limit` | Limits the number of documents returned |
-| `page` | Get a specific page number |
+| Control | Description |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `limit` | Limits the number of documents returned |
+| `page` | Get a specific page number |
diff --git a/docs/rest-api/overview.mdx b/docs/rest-api/overview.mdx
index 031bd1b54..9b16f54aa 100644
--- a/docs/rest-api/overview.mdx
+++ b/docs/rest-api/overview.mdx
@@ -7,8 +7,7 @@ keywords: rest, api, documentation, Content Management System, cms, headless, ja
---
- A fully functional REST API is automatically generated from your Collection
- and Global configs.
+ A fully functional REST API is automatically generated from your Collection and Global configs.
All Payload API routes are mounted prefixed to your config's `routes.api` URL segment (default: `/api`).
@@ -25,13 +24,13 @@ Each collection is mounted using its `slug` value. For example, if a collection'
**All CRUD operations are exposed as follows:**
-| Method | Path | Description |
-| -------- | --------------------------- | --------------------------------- |
-| `GET` | `/api/{collectionSlug}` | Find paginated documents |
-| `GET` | `/api/{collectionSlug}/:id` | Find a specific document by ID |
-| `POST` | `/api/{collectionSlug}` | Create a new document |
-| `PUT` | `/api/{collectionSlug}/:id` | Update a document by ID |
-| `DELETE` | `/api/{collectionSlug}/:id` | Delete an existing document by ID |
+| Method | Path | Description |
+| -------- | --------------------------- | -------------------------------------- |
+| `GET` | `/api/{collectionSlug}` | Find paginated documents |
+| `GET` | `/api/{collectionSlug}/:id` | Find a specific document by ID |
+| `POST` | `/api/{collectionSlug}` | Create a new document |
+| `PUT` | `/api/{collectionSlug}/:id` | Update a document by ID |
+| `DELETE` | `/api/{collectionSlug}/:id` | Delete an existing document by ID |
##### Additional `find` query parameters
@@ -44,22 +43,22 @@ The `find` endpoint supports the following additional query parameters:
## Auth Operations
-| Method | Path | Description |
-| ------ | --------------------------------------- | --------------------------------------------------------------------------------------- |
-| `POST` | `/api/{collectionSlug}/verify/:token` | [Email verification](/docs/authentication/operations#verify-by-email), if enabled. |
-| `POST` | `/api/{collectionSlug}/unlock` | [Unlock a user's account](/docs/authentication/operations#unlock), if enabled. |
-| `POST` | `/api/{collectionSlug}/login` | [Logs in](/docs/authentication/operations#login) a user with email / password. |
-| `POST` | `/api/{collectionSlug}/logout` | [Logs out](/docs/authentication/operations#logout) a user. |
-| `POST` | `/api/{collectionSlug}/refresh-token` | [Refreshes a token](/docs/authentication/operations#refresh) that has not yet expired. |
-| `GET` | `/api/{collectionSlug}/me` | [Returns the currently logged in user with token](/docs/authentication/operations#me). |
-| `POST` | `/api/{collectionSlug}/forgot-password` | [Password reset workflow](/docs/authentication/operations#forgot-password) entry point. |
-| `POST` | `/api/{collectionSlug}/reset-password` | [To reset the user's password](/docs/authentication/operations#reset-password). |
+| Method | Path | Description |
+| -------- | --------------------------- | ----------- |
+| `POST` | `/api/{collectionSlug}/verify/:token` | [Email verification](/docs/authentication/operations#verify-by-email), if enabled. |
+| `POST` | `/api/{collectionSlug}/unlock` | [Unlock a user's account](/docs/authentication/operations#unlock), if enabled. |
+| `POST` | `/api/{collectionSlug}/login` | [Logs in](/docs/authentication/operations#login) a user with email / password. |
+| `POST` | `/api/{collectionSlug}/logout` | [Logs out](/docs/authentication/operations#logout) a user. |
+| `POST` | `/api/{collectionSlug}/refresh-token` | [Refreshes a token](/docs/authentication/operations#refresh) that has not yet expired. |
+| `GET` | `/api/{collectionSlug}/me` | [Returns the currently logged in user with token](/docs/authentication/operations#me). |
+| `POST` | `/api/{collectionSlug}/forgot-password` | [Password reset workflow](/docs/authentication/operations#forgot-password) entry point. |
+| `POST` | `/api/{collectionSlug}/reset-password` | [To reset the user's password](/docs/authentication/operations#reset-password). |
## Globals
Globals cannot be created or deleted, so there are only two REST endpoints opened:
-| Method | Path | Description |
-| ------ | --------------------------- | ----------------------- |
-| `GET` | `/api/globals/{globalSlug}` | Get a global by slug |
-| `POST` | `/api/globals/{globalSlug}` | Update a global by slug |
+| Method | Path | Description |
+| -------- | --------------------------- | ----------------------- |
+| `GET` | `/api/globals/{globalSlug}` | Get a global by slug |
+| `POST` | `/api/globals/{globalSlug}` | Update a global by slug |
diff --git a/docs/upload/overview.mdx b/docs/upload/overview.mdx
index 9764d8c93..c1a4a711b 100644
--- a/docs/upload/overview.mdx
+++ b/docs/upload/overview.mdx
@@ -7,13 +7,11 @@ keywords: uploads, images, media, overview, documentation, Content Management Sy
---
- Payload provides for everything you need to enable file upload, storage, and
- management directly on your server—including extremely powerful file access
- control.
+ Payload provides for everything you need to enable file upload, storage, and management directly on your server—including extremely powerful file access control.
-_Admin panel screenshot depicting a Media Collection with Upload enabled_
+*Admin panel screenshot depicting a Media Collection with Upload enabled*
**Here are some common use cases of Uploads:**
@@ -24,7 +22,7 @@ _Admin panel screenshot depicting a Media Collection with Upload enabled_
**By simply enabling Upload functionality on a Collection, Payload will automatically transform your Collection into a robust file management / storage solution. The following modifications will be made:**
1. `filename`, `mimeType`, and `filesize` fields will be automatically added to your Collection. Optionally, if you pass `imageSizes` to your Collection's Upload config, a [`sizes`](#image-sizes) array will also be added containing auto-resized image sizes and filenames.
-1. The Admin panel will modify its built-in `List` component to show a thumbnail gallery of your Uploads instead of the default Table view
+1. The Admin panel will modify its built-in `List` component to show a thumbnail gallery of your Uploads instead of the default Table view
1. The Admin panel will modify its `Edit` view(s) to add a new set of corresponding Upload UI which will allow for file upload
1. The `create`, `update`, and `delete` Collection operations will be modified to support file upload, re-upload, and deletion
@@ -33,47 +31,45 @@ _Admin panel screenshot depicting a Media Collection with Upload enabled_
Every Payload Collection can opt-in to supporting Uploads by specifying the `upload` property on the Collection's config to either `true` or to an object containing `upload` options.
- Tip:
-
A common pattern is to create a Media collection and
- enable upload on that collection.
+ Tip:
+ A common pattern is to create a Media collection and enable upload on that collection.
#### Collection Upload Options
-| Option | Description |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| **`staticURL`** \* | The base URL path to use to access you uploads. Example: `/media` |
-| **`staticDir`** \* | The folder directory to use to store media in. Can be either an absolute path or relative to the directory that contains your config. |
-| **`imageSizes`** | If specified, image uploads will be automatically resized in accordance to these image sizes. [More](#image-sizes) |
-| **`adminThumbnail`** | Which of your provided image sizes to use for the admin panel's thumbnail. Typically a size around 500x500px or so works well. |
+| Option | Description |
+| ---------------------- | -------------|
+| **`staticURL`** * | The base URL path to use to access you uploads. Example: `/media` |
+| **`staticDir`** * | The folder directory to use to store media in. Can be either an absolute path or relative to the directory that contains your config. |
+| **`imageSizes`** | If specified, image uploads will be automatically resized in accordance to these image sizes. [More](#image-sizes) |
+| **`adminThumbnail`** | Which of your provided image sizes to use for the admin panel's thumbnail. Typically a size around 500x500px or so works well. |
-_An asterisk denotes that a property above is required._
+*An asterisk denotes that a property above is required.*
**Example Upload collection:**
-
```js
const Media = {
- slug: "media",
+ slug: 'media',
upload: {
- staticURL: "/media",
- staticDir: "media",
+ staticURL: '/media',
+ staticDir: 'media',
imageSizes: [
{
- name: "thumbnail",
+ name: 'thumbnail',
width: 400,
height: 300,
- crop: "centre",
+ crop: 'centre',
},
{
- name: "card",
+ name: 'card',
width: 768,
height: 1024,
- crop: "centre",
- },
+ crop: 'centre',
+ }
],
- adminThumbnail: "thumbnail",
- },
-};
+ adminThumbnail: 'thumbnail',
+ }
+}
```
### Payload-wide Upload Options
@@ -83,17 +79,17 @@ Payload relies on the [`express-fileupload`](https://www.npmjs.com/package/expre
A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed `fileSize` of uploads sent to Payload:
```js
-import { buildConfig } from "payload/config";
+import { buildConfig } from 'payload/config';
export default buildConfig({
- serverURL: "http://localhost:3000",
+ serverURL: 'http://localhost:3000',
collections: [
{
- slug: "media",
+ slug: 'media',
fields: [
{
- name: "alt",
- type: "text",
+ name: 'alt',
+ type: 'text',
},
],
upload: true,
@@ -102,8 +98,8 @@ export default buildConfig({
upload: {
limits: {
fileSize: 5000000, // 5MB, written in bytes
- },
- },
+ }
+ }
});
```
@@ -118,11 +114,8 @@ Behind the scenes, Payload relies on [`sharp`](https://sharp.pixelplumbing.com/a
### Uploading Files
- Important:
-
- Uploading files is currently only possible through the REST API due to how
- GraphQL works. It's difficult and fairly nonsensical to support uploading
- files through GraphQL.
+ Important:
+ Uploading files is currently only possible through the REST API due to how GraphQL works. It's difficult and fairly nonsensical to support uploading files through GraphQL.
To upload a file, use your collection's [`create`](/docs/rest-api/overview#collections) endpoint. Send it all the data that your Collection requires, as well as a `file` key containing the file that you'd like to upload.