Payload Concepts
Payload is based around a small and intuitive set of concepts. Before starting to work with Payload, it's a good idea to familiarize yourself with the following:
Config
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.
Collections
Collections define the shape of your data as well as all functionalities attached to that data. They will contain one or many "documents", all corresponding with the same fields and functionalities that you define.
They can represent anything you can store in a database - for example - pages, posts, users, people, orders, categories, events, customers, transactions, and anything else your app needs.
Globals
Globals are in many ways similar to Collections, but there is only ever one instance of a Global, whereas Collections can contain many documents.
Fields
Payload comes with many different field types 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.
Hooks
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.
There are many more potential reasons to use Hooks. For more, visit the Hooks documentation.
Access Control
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.
For more, visit the Access Control documentation.
Depth
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.
It is also possible to limit the depth for specific relation
and upload
fields using the maxDepth
property in your configuration.
For example, let's look at the following Collections: departments
, users
, posts
If you were to query the Posts endpoint at, say, http://localhost:3000/api/posts?depth=1
, you will retrieve Posts with populations one level deep. This depth parameter can be thought of as N, where N is the number of levels you want to populate. To populate one level further, you would simply specify N+1 as the depth. A returned result may look like the following:
Notice how the user.author
is fully populated, but user.author.department
is left as a document ID? That's because the User collection counted as the first level of depth
and got populated—but then prevented any further populations from taking place.
To populate user.author.department
in it's entirety you could specify ?depth=2
or higher.