diff --git a/docs/Admin/overview.mdx b/docs/Admin/overview.mdx index 9b6c9b56a7..0c37312838 100644 --- a/docs/Admin/overview.mdx +++ b/docs/Admin/overview.mdx @@ -9,7 +9,7 @@ Payload dynamically generates a beautiful, fully functional React admin panel to The Payload Admin panel is built with Webpack, code-split, highly performant (even with 100+ fields), and written fully in TypeScript. It's meant to be simple enough to give you a starting point but not bring too much complexity, so that you can easily customize it to suit the needs of your application and your editors.
-![Array field in Payload admin panel](/images/admin.jpg) +![Payload's Admin panel built in React](/images/admin.jpg) *Screenshot of the Admin panel while editing a document from an example `AllFields` collection* diff --git a/docs/Admin/webpack.mdx b/docs/Admin/webpack.mdx index 14e5ebeb43..d4e83adc40 100644 --- a/docs/Admin/webpack.mdx +++ b/docs/Admin/webpack.mdx @@ -152,7 +152,7 @@ The above code will alias the file at path `createStripeSubscriptionPath` to a m export default {}; ``` -Now, when Webpack sees that you're attempting to import your `createStripeSubscriptionPath` file, it'll disregard that actual file and load your mock file instead. Not only will your Admin panel now bundle succcessfully, you will have optimized its filesize by removing unnecessary code! And you might have learned something about Webpack, too. +Now, when Webpack sees that you're attempting to import your `createStripeSubscriptionPath` file, it'll disregard that actual file and load your mock file instead. Not only will your Admin panel now bundle successfully, you will have optimized its filesize by removing unnecessary code! And you might have learned something about Webpack, too. ## Admin environment vars diff --git a/docs/Authentication/operations.mdx b/docs/Authentication/operations.mdx index 017506b6d5..fbecd9308e 100644 --- a/docs/Authentication/operations.mdx +++ b/docs/Authentication/operations.mdx @@ -266,7 +266,7 @@ const result = await payload.verifyEmail({ ### Unlock -If a user locls themselves out and you wish to deliberately unlock them, you can utilize the Unlock operation. The Admin panel features an Unlock control automatically for all collections that feature max login attempts, but you can programmatically unlock users as well by using the Unlock operation. +If a user locks themselves out and you wish to deliberately unlock them, you can utilize the Unlock operation. The Admin panel features an Unlock control automatically for all collections that feature max login attempts, but you can programmatically unlock users as well by using the Unlock operation. To restrict who is allowed to unlock users, you can utilize the [`unlock`](/docs/access-control/overview#unlock) access control function. diff --git a/docs/Authentication/overview.mdx b/docs/Authentication/overview.mdx index 604ddd9763..7f0c1d6fe2 100644 --- a/docs/Authentication/overview.mdx +++ b/docs/Authentication/overview.mdx @@ -10,7 +10,10 @@ order: 10 Authentication is used within the Payload Admin panel itself as well as throughout your app(s) themselves however you determine necessary. -Here are some common use cases of Authentication outside of Payload's dashboard itself: +![Authentication admin panel functionality](/images/auth-admin.jpg) +*Admin panel screenshot depicting an Admins Collection with Auth enabled* + +**Here are some common use cases of Authentication outside of Payload's dashboard itself:** - Customer accounts for an ecommerce app - Customer accounts for a SaaS product diff --git a/docs/Authentication/using-middleware.mdx b/docs/Authentication/using-middleware.mdx index 6af2bf5d3e..d8d402f9df 100644 --- a/docs/Authentication/using-middleware.mdx +++ b/docs/Authentication/using-middleware.mdx @@ -4,11 +4,11 @@ label: Using the Middleware order: 40 --- -Because Payload uses your existing Express server, you are free to add whatever logic you need to your app through endpoints of your own. However, Payload does not add its middleware to your Express app itself—instead, ist scopes all of its middelware to Payload-specific routers. +Because Payload uses your existing Express server, you are free to add whatever logic you need to your app through endpoints of your own. However, Payload does not add its middleware to your Express app itself—instead, ist scopes all of its middleware to Payload-specific routers. This approach has a ton of benefits - it's great for isolation of concerns and limiting scope, but it also means that your additional routes won't have access to Payload's user authentication. -If you would like to make use of Payload's built-in authentication within your custom routes, you can to add Payload's authentication middeware. +If you would like to make use of Payload's built-in authentication within your custom routes, you can to add Payload's authentication middleware. Example in `server.js`: ```js diff --git a/docs/Configuration/collections.mdx b/docs/Configuration/collections.mdx index 744eceb8a8..5ac7eaa6f7 100644 --- a/docs/Configuration/collections.mdx +++ b/docs/Configuration/collections.mdx @@ -70,7 +70,7 @@ You can customize the way that the Admin panel behaves on a collection-by-collec 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 corrresponding collection's Edit view. Clicking the Preview button will link to the URL that is generated by the function. +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 the document being edited as an argument. @@ -104,7 +104,7 @@ You can specify extremely granular access control (what users can do with docume ### Hooks -Hooks are a powerful way to extend collection functionality and execute your own logic, and can be defined on a collectiion by collection basis. To learn more, go to the [Hooks](/docs/hooks/overview) documentation. +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 diff --git a/docs/Configuration/overview.mdx b/docs/Configuration/overview.mdx index b82675d4e5..04c860b6e6 100644 --- a/docs/Configuration/overview.mdx +++ b/docs/Configuration/overview.mdx @@ -6,7 +6,7 @@ order: 10 Payload is a *config-based*, code-first CMS and application framework. The Payload config is central to everything that Payload does. It scaffolds the data that Payload stores as well as maintains custom React components, hook logic, custom validations, and much more. The config itself and all of its dependencies are run through Babel, so you can take full advantage of newer JavaScript features and even directly import React components containing JSX. -Also, because the Payload source code is fully written in TypeScript, its configs are strongly typed—meaning that even if you aren't using TypeScript to build your project, your IDE (such as VSCode) may still provide helpful information like typeahead suggestions while you write your config. +Also, because the Payload source code is fully written in TypeScript, its configs are strongly typed—meaning that even if you aren't using TypeScript to build your project, your IDE (such as VSCode) may still provide helpful information like type-ahead suggestions while you write your config. Important:
This file is included in the Payload admin bundle, so make sure you do not embed any sensitive information. diff --git a/docs/Hooks/fields.mdx b/docs/Hooks/fields.mdx index 22879753e3..16cc844b8c 100644 --- a/docs/Hooks/fields.mdx +++ b/docs/Hooks/fields.mdx @@ -6,7 +6,7 @@ order: 30 Field-level hooks offer incredible potential for encapsulating your logic. They help to isolate concerns and package up functionalities to be easily reusable across your projects. -Example use cases include: +**Example use cases include:** - Automatically add an `owner` relationship to a Document based on the `req.user.id` - Encrypt / decrypt a sensitive field using `beforeValidate` and `afterRead` hooks @@ -14,12 +14,12 @@ Example use cases include: - Format incoming data such as kebab-casing a document `slug` with `beforeValidate` - Restrict updating a document to only once every X hours using the `beforeChange` hook -All field types provide the following hooks: +**All field types provide the following hooks:** -- [beforeValidate](#beforeValidate) -- [beforeChange](#beforeChange) -- [afterChange](#afterChange) -- [afterRead](#afterRead) +- `beforeValidate` +- `beforeChange` +- `afterChange` +- `afterRead` ## Config diff --git a/docs/Hooks/overview.mdx b/docs/Hooks/overview.mdx index 894b86a06e..2013cacaf6 100644 --- a/docs/Hooks/overview.mdx +++ b/docs/Hooks/overview.mdx @@ -40,4 +40,4 @@ You can specify hooks in the following contexts: - [Collection Hooks](/docs/hooks/collections) - [Field Hooks](/docs/hooks/fields) -- [Global Hooks](/docs/hoooks/globals) +- [Global Hooks](/docs/hooks/globals) diff --git a/docs/REST-API/overview.mdx b/docs/REST-API/overview.mdx index 03857c9b8f..190a17a8cf 100644 --- a/docs/REST-API/overview.mdx +++ b/docs/REST-API/overview.mdx @@ -37,7 +37,20 @@ The `find` endpoint supports the following additional query parameters: - [sort](/docs/queries/overview#sort) - sort by field - [where](/docs/queries/overview) - pass a `where` query to constrain returned documents - [limit](/docs/queries/pagination#pagination-controls) - limit the returned documents to a certain number -- [page](/docs/queries/pagination#pagination-controls) - get a specfic page of documents +- [page](/docs/queries/pagination#pagination-controls) - get a specific page of documents + +## 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). | ## Globals diff --git a/docs/Upload/config.mdx b/docs/Upload/config.mdx index b9c02f22e3..55b1b00e22 100644 --- a/docs/Upload/config.mdx +++ b/docs/Upload/config.mdx @@ -1,16 +1,108 @@ --- -title: Upload Config +title: Uploads label: Config order: 10 --- -Talk about how to configure uploads here. + + Payload provides for everything you need to enable file upload, storage, and management directly on your server—including extremely powerful file access control. + + +![Upload admin panel functionality](/images/upload-admin.jpg) +*Admin panel screenshot depicting a Media Collection with Upload enabled* + +**Here are some common use cases of Uploads:** + +- Creating a "Media Library" that contains images for use throughout your site or app +- Building a Gated Content library where users need to sign up to gain access to downloadable assets like ebook PDFs, whitepapers, etc. +- Storing publicly available, downloadable assets like software, ZIP files, MP4s, etc. + +**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` array](#image-sizes) 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 `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 + +### Enabling Uploads + +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. + + +#### 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. | + +*An asterisk denotes that a property above is required.* + +**Example Upload collection:** +```js +const Media = { + slug: 'media', + upload: { + staticURL: '/media', + staticDir: 'media', + imageSizes: [ + { + name: 'thumbnail', + width: 400, + height: 300, + crop: 'centre', + }, + { + name: 'card', + width: 768, + height: 1024, + crop: 'centre', + } + ] + } +} +``` + +### Payload-wide Upload Options + +Payload relies on the [`express-fileupload`](https://www.npmjs.com/package/express-fileupload) package to manage file uploads in Express. In addition to the Upload options specifiable on a Collection by Collection basis, you can also control the `express-fileupload` options by passing your base Payload config an `upload` property containing an object supportive of all `express-fileupload` properties which use `Busboy` under the hood. [Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control. + +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'; + +export default buildConfig({ + serverURL: 'http://localhost:3000', + collections: [ + { + slug: 'media', + fields: [ + { + name: 'alt', + type: 'text', + }, + ], + upload: true, + }, + ], + upload: { + limits: { + fileSize: 5000000, // 5MB, written in bytes + } + } +}); +``` + Need to cover: -1. Global upload config #global -1. Can have multiple collections -1. Static directory 1. How to upload (multipart/form-data) 1. Uploading is REST-only 1. Access control