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

chore: merge master

Browse Source
This commit is contained in:
James
2022-09-11 18:07:05 -07:00
parent 2ae33b603a 14a16dc05f
commit cd209379b2
245 changed files with 4708 additions and 2347 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/fields/array.mdx
View File

@@ -41,9 +41,11 @@ keywords: array, fields, config, configuration, documentation, Content Managemen
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -70,6 +72,5 @@ keywords: array, fields, config, configuration, documentation, Content Managemen
]
}
]
}
};
```

10
docs/fields/blocks.mdx
View File

@@ -72,8 +72,10 @@ The Admin panel provides each block with a `blockName` field which optionally al
### Example
`collections/ExampleCollection.js`
```js
const QuoteBlock = {
```ts
import { Block, CollectionConfig } from 'payload/types';
const QuoteBlock: Block = {
slug: 'Quote', // required
imageURL: 'https://google.com/path/to/image.jpg',
imageAltText: 'A nice thumbnail image to show what this block looks like',
@@ -90,7 +92,7 @@ const QuoteBlock = {
]
};
const ExampleCollection = {
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -111,7 +113,7 @@ const ExampleCollection = {
As you build your own Block configs, you might want to store them in separate files but retain typing accordingly. To do so, you can import and use Payload's `Block` type:
```js
```ts
import type { Block } from 'payload/types';
```

11
docs/fields/checkbox.mdx
View File

@@ -31,9 +31,11 @@ keywords: checkbox, fields, config, configuration, documentation, Content Manage
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -43,6 +45,5 @@ keywords: checkbox, fields, config, configuration, documentation, Content Manage
defaultValue: false,
}
]
}
};
```

25
docs/fields/code.mdx
View File

@@ -39,13 +39,27 @@ This field uses `prismjs` for syntax highlighting and `react-simple-code-editor`
In addition to the default [field admin config](/docs/fields/overview#admin-config), the Code field type also allows for the customization of a `language` property.
Currently, the `language` property only supports JavaScript syntax but more support will be added as requested.
The following `prismjs` plugins are imported, enabling the `language` property to accept the following values:
| Plugin | Language |
| ---------------------------- | ----------- |
| **`prism-css`** | `css` |
| **`prism-clike`** | `clike` |
| **`prism-markup`** | `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss` |
| **`prism-javascript`** | `javascript`, `js` |
| **`prism-json`** | `json` |
| **`prism-jsx`** | `jsx` |
| **`prism-typescript`** | `typescript`, `ts` |
| **`prism-tsx`** | `tsx` |
| **`prism-yaml`** | `yaml`, `yml` |
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -57,6 +71,5 @@ Currently, the `language` property only supports JavaScript syntax but more supp
}
}
]
}
};
```

11
docs/fields/collapsible.mdx
View File

@@ -22,9 +22,11 @@ keywords: row, fields, config, configuration, documentation, Content Management
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -39,6 +41,5 @@ keywords: row, fields, config, configuration, documentation, Content Management
],
}
]
}
};
```

15
docs/fields/date.mdx
View File

@@ -38,8 +38,8 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
| Option | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`pickerAppearance`** | Determines the appearance of the datepicker: `dayAndTime` `timeOnly` `dayOnly`. Defaults to `dayAndTime`. |
| **`displayFormat`** | Determines how the date is presented. dayAndTime default to `MMM d, yyy h:mm a` timeOnly defaults to `h:mm a` and dayOnly defaults to `MMM d, yyy`. |
| **`pickerAppearance`** | Determines the appearance of the datepicker: `dayAndTime` `timeOnly` `dayOnly` `monthOnly`. Defaults to `dayAndTime`. |
| **`displayFormat`** | Determines how the date is presented. dayAndTime default to `MMM d, yyy h:mm a` timeOnly defaults to `h:mm a` dayOnly defaults to `MMM d, yyy` and monthOnly defaults to `MM/yyyy`. |
| **`placeholder`** | Placeholder text for the field. |
| **`monthsToShow`** | Number of months to display max is 2. Defaults to 1. |
| **`minDate`** | Passed directly to [react-datepicker](https://github.com/Hacker0x01/react-datepicker/blob/master/docs/datepicker.md). |
@@ -55,10 +55,12 @@ Common use cases for customizing the `date` property are to restrict your field
### Example
`collections/ExampleCollection.js`
`collections/ExampleCollection.ts`
```js
{
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -74,6 +76,5 @@ Common use cases for customizing the `date` property are to restrict your field
}
}
]
}
};
```

11
docs/fields/email.mdx
View File

@@ -44,9 +44,11 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -56,6 +58,5 @@ Set this property to a string that will be used for browser autocomplete.
required: true,
}
]
}
};
```

11
docs/fields/group.mdx
View File

@@ -39,9 +39,11 @@ Set this property to `true` to hide this field's gutter within the admin panel.
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -65,6 +67,5 @@ Set this property to `true` to hide this field's gutter within the admin panel.
],
}
]
}
};
```

11
docs/fields/number.mdx
View File

@@ -50,9 +50,11 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -64,6 +66,5 @@ Set this property to a string that will be used for browser autocomplete.
}
}
]
}
};
```

76
docs/fields/overview.mdx
View File

@@ -16,8 +16,10 @@ Fields are defined as an array on Collections and Globals via the `fields` key.
The required `type` property on a field determines what values it can accept, how it is presented in the API, and how the field will be rendered in the admin interface.
**Simple collection with two fields:**
```js
const Pages = {
```ts
import { CollectionConfig } from 'payload/types';
const Page: CollectionConfig = {
slug: 'pages',
fields: [
{
@@ -29,7 +31,7 @@ const Pages = {
type: 'checkbox', // highlight-line
},
],
}
};
```
### Field types
@@ -80,8 +82,10 @@ There are two arguments available to custom validation functions.
| `payload` | If the `validate` function is being executed on the server, Payload will be exposed for easily running local operations. |
Example:
```js
{
```ts
import { CollectionConfig } from 'payload/types';
const Orders: CollectionConfig = {
slug: 'orders',
fields: [
{
@@ -101,27 +105,27 @@ Example:
},
},
],
}
};
```
When supplying a field `validate` function, Payload will use yours in place of the default. To make use of the default field validation in your custom logic you can import, call and return the result as needed.
For example:
```js
```ts
import { text } from 'payload/fields/validations';
const field =
{
name: 'notBad',
type: 'text',
validate: (val, args) => {
if (value === 'bad') {
return 'This cannot be "bad"';
}
// highlight-start
return text(val, args);
// highlight-end
},
}
const field: Field = {
name: 'notBad',
type: 'text',
validate: (val, args) => {
if (val === 'bad') {
return 'This cannot be "bad"';
}
// highlight-start
return text(val, args);
// highlight-end
},
};
```
### Customizable ID
@@ -131,7 +135,7 @@ Users are then required to provide a custom ID value when creating a record thro
Valid ID types are `number` and `text`.
Example:
```js
```ts
{
fields: [
{
@@ -174,7 +178,7 @@ The `condition` function should return a boolean that will control if the field
**Example:**
```js
```ts
{
fields: [
{
@@ -212,21 +216,19 @@ Functions are called with an optional argument object containing:
Here is an example of a defaultValue function that uses both:
```js
```ts
const translation: {
en: 'Written by',
es: 'Escrito por',
en: 'Written by',
es: 'Escrito por',
};
const field = {
name: 'attribution',
type: 'text',
admin: {
// highlight-start
defaultValue: ({ user, locale }) => (`${translation[locale]} ${user.name}`)
// highlight-end
}
};
name: 'attribution',
type: 'text',
// highlight-start
defaultValue: ({ user, locale }) => (`${translation[locale]} ${user.name}`)
// highlight-end
};
```
<Banner type="success">
@@ -244,7 +246,7 @@ As shown above, you can simply provide a string that will show by the field, but
**Function Example:**
```js
```ts
{
fields: [
{
@@ -262,7 +264,7 @@ As shown above, you can simply provide a string that will show by the field, but
This example will display the number of characters allowed as the user types.
**Component Example:**
```js
```ts
{
fields: [
{
@@ -289,10 +291,8 @@ This component will count the number of characters entered.
You can import the internal Payload `Field` type as well as other common field types as follows:
```js
```ts
import type {
Field,
Validate,
Condition,
} from 'payload/types';
```

10
docs/fields/point.mdx
View File

@@ -35,9 +35,11 @@ The data structure in the database matches the GeoJSON structure to represent po
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -46,7 +48,7 @@ The data structure in the database matches the GeoJSON structure to represent po
label: 'Location',
},
]
}
};
```
### Querying

8
docs/fields/radio.mdx
View File

@@ -45,9 +45,11 @@ The `layout` property allows for the radio group to be styled as a horizonally o
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

50
docs/fields/relationship.mdx
View File

@@ -45,6 +45,14 @@ keywords: relationship, fields, config, configuration, documentation, Content Ma
The <a href="/docs/getting-started/concepts#depth">Depth</a> parameter can be used to automatically populate related documents that are returned by the API.
</Banner>
### Admin config
In addition to the default [field admin config](/docs/fields/overview#admin-config), the Relationship field type also allows for the following admin-specific properties:
**`isSortable`**
Set to `true` if you'd like this field to be sortable within the Admin UI using drag and drop. (Only works when `hasMany` is set to `true`)
### Filtering relationship options
Options can be dynamically limited by supplying a [query constraint](/docs/queries/overview), which will be used both for validating input and filtering available relationships in the UI.
@@ -61,26 +69,26 @@ The `filterOptions` property can either be a `Where` query directly, or a functi
**Example:**
```js
const relationshipField = {
name: 'purchase',
type: 'relationship',
relationTo: ['products', 'services'],
filterOptions: ({ relationTo, siblingData }) => {
// returns a Where query dynamically by the type of relationship
if (relationTo === 'products') {
return {
'stock': { is_greater_than: siblingData.quantity }
}
```ts
const relationshipField = {
name: 'purchase',
type: 'relationship',
relationTo: ['products', 'services'],
filterOptions: ({ relationTo, siblingData }) => {
// returns a Where query dynamically by the type of relationship
if (relationTo === 'products') {
return {
'stock': { greater_than: siblingData.quantity }
}
}
if (relationTo === 'services') {
return {
'isAvailable': { equals: true }
}
if (relationTo === 'services') {
return {
'isAvailable': { equals: true }
}
},
};
}
},
};
```
You can learn more about writing queries [here](/docs/queries/overview).
@@ -98,7 +106,7 @@ Given the variety of options possible within the `relationship` field type, the
The most simple pattern of a relationship is to use `hasMany: false` with a `relationTo` that allows for only one type of collection.
```js
```ts
{
slug: 'example-collection',
fields: [
@@ -129,7 +137,7 @@ When querying documents in this collection via REST API, you could query as foll
Also known as **dynamic references**, in this configuration, the `relationTo` field is an array of Collection slugs that tells Payload which Collections are valid to reference.
```js
```ts
{
slug: 'example-collection',
fields: [
@@ -168,7 +176,7 @@ This query would return only documents that have an owner relationship to organi
The `hasMany` tells Payload that there may be more than one collection saved to the field.
```js
```ts
{
slug: 'example-collection',
fields: [
@@ -196,7 +204,7 @@ When querying documents, the format does not change for arrays:
#### Has Many - Polymorphic
```js
```ts
{
slug: 'example-collection',
fields: [

23
docs/fields/rich-text.mdx
View File

@@ -77,6 +77,13 @@ The default `leaves` available in Payload are:
Set this property to `true` to hide this field's gutter within the admin panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter.
**`link.fields`**
This allows [fields](/docs/fields/overview) to be saved as extra fields on a link inside the Rich Text Editor. When this is present, the fields will render inside a modal that can be opened by clicking the "edit" button on the link element.
![RichText link fields](https://payloadcms.com/images/fields/richText/rte-link-fields-modal.jpg)
*RichText link with custom fields*
**`upload.collections[collection-name].fields`**
This allows [fields](/docs/fields/overview) to be saved as meta data on an upload field inside the Rich Text Editor. When this is present, the fields will render inside a modal that can be opened by clicking the "edit" button on the upload element.
@@ -126,9 +133,11 @@ Custom `Leaf` objects follow a similar pattern but require you to define the `Le
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -178,7 +187,7 @@ Custom `Leaf` objects follow a similar pattern but require you to define the `Le
}
}
]
}
};
```
For more examples regarding how to define your own elements and leaves, check out the example [`RichText` field](https://github.com/payloadcms/public-demo/blob/master/src/fields/hero.ts) within the Public Demo source code.
@@ -187,7 +196,7 @@ 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
```ts
import React, { Fragment } from 'react';
import escapeHTML from 'escape-html';
import { Text } from 'slate';
@@ -308,7 +317,7 @@ If you want to utilize this functionality within your own custom elements, you c
`customLargeBodyElement.js`:
```js
```ts
import Button from './Button';
import Element from './Element';
import withLargeBody from './plugin';
@@ -338,7 +347,7 @@ The plugin itself extends Payload's built-in `shouldBreakOutOnEnter` Slate funct
If you are building your own custom Rich Text elements or leaves, you may benefit from importing the following types:
```js
```ts
import type {
RichTextCustomElement,
RichTextCustomLeaf,

8
docs/fields/row.mdx
View File

@@ -21,9 +21,11 @@ keywords: row, fields, config, configuration, documentation, Content Management
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

12
docs/fields/select.mdx
View File

@@ -51,12 +51,17 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
Set to `true` if you'd like this field to be clearable within the Admin UI.
**`isSortable`**
Set to `true` if you'd like this field to be sortable within the Admin UI using drag and drop. (Only works when `hasMany` is set to `true`)
### Example
`collections/ExampleCollection.js`
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
```js
{
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{
@@ -65,6 +70,7 @@ Set to `true` if you'd like this field to be clearable within the Admin UI.
hasMany: true,
admin: {
isClearable: true,
isSortable: true, // use mouse to drag and drop different values, and sort them according to your choice
},
options: [
{

8
docs/fields/tabs.mdx
View File

@@ -35,9 +35,11 @@ Each tab has its own required `label` and `fields` array. You can also optionall
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

8
docs/fields/text.mdx
View File

@@ -46,9 +46,11 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

8
docs/fields/textarea.mdx
View File

@@ -46,9 +46,11 @@ Set this property to a string that will be used for browser autocomplete.
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

8
docs/fields/ui.mdx
View File

@@ -34,9 +34,11 @@ With this field, you can also inject custom `Cell` components that appear as add
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{

8
docs/fields/upload.mdx
View File

@@ -46,9 +46,11 @@ keywords: upload, images media, fields, config, configuration, documentation, Co
### Example
`collections/ExampleCollection.js`
```js
{
`collections/ExampleCollection.ts`
```ts
import { CollectionConfig } from 'payload/types';
const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
{