tabshift/payload
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: spelling, REST auth ops, Upload progress

Browse Source
This commit is contained in:
James
2021-01-03 12:00:35 -05:00
parent a0bf503f88
commit 85658c7017
11 changed files with 130 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Admin/overview.mdx
View File

@@ -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.
<br/>
![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*

2
docs/Admin/webpack.mdx
View File

@@ -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

2
docs/Authentication/operations.mdx
View File

@@ -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.

5
docs/Authentication/overview.mdx
View File

@@ -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

4
docs/Authentication/using-middleware.mdx
View File

@@ -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

4
docs/Configuration/collections.mdx
View File

@@ -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

2
docs/Configuration/overview.mdx
View File

@@ -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.
<strong>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.</strong>
<strong>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.</strong>
<Banner type="warning">
<strong>Important:</strong><br />This file is included in the Payload admin bundle, so make sure you do not embed any sensitive information.

12
docs/Hooks/fields.mdx
View File

@@ -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

2
docs/Hooks/overview.mdx
View File

@@ -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)

15
docs/REST-API/overview.mdx
View File

@@ -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

102
docs/Upload/config.mdx
View File

@@ -1,16 +1,108 @@
---
title: Upload Config
title: Uploads
label: Config
order: 10
---
Talk about how to configure uploads here.
<Banner>
Payload provides for everything you need to enable file upload, storage, and management directly on your server—including extremely powerful file access control.
</Banner>
![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.
<Banner type="success">
<strong>Tip:</strong><br/>
A common pattern is to create a <strong>Media</strong> collection and enable <strong>upload</strong> on that collection.
</Banner>
#### 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