From c86731aaf71321459301999e4540f16b01eac11a Mon Sep 17 00:00:00 2001 From: James Date: Thu, 31 Dec 2020 09:30:50 -0500 Subject: [PATCH] docs: array and blocks --- demo/blocks/Quote.ts | 2 +- docs/Fields/array.mdx | 75 +++++++++++++++++++++++++- docs/Fields/blocks.mdx | 112 ++++++++++++++++++++++++++++++++++++++- docs/Fields/overview.mdx | 35 +++++++++--- 4 files changed, 213 insertions(+), 11 deletions(-) diff --git a/demo/blocks/Quote.ts b/demo/blocks/Quote.ts index d25752f5c2d..3cb4ca37c9c 100644 --- a/demo/blocks/Quote.ts +++ b/demo/blocks/Quote.ts @@ -1,7 +1,7 @@ import { Block } from '../../src/fields/config/types'; const Quote: Block = { - blockImage: '/static/assets/images/generic-block-image.svg', + imageURL: '/static/assets/images/generic-block-image.svg', slug: 'quote', labels: { singular: 'Quote', diff --git a/docs/Fields/array.mdx b/docs/Fields/array.mdx index 7a93fcdf6d1..4b30a0a4b31 100644 --- a/docs/Fields/array.mdx +++ b/docs/Fields/array.mdx @@ -4,4 +4,77 @@ label: Array order: 20 --- -get out + + The Array field type is used when you need to have a set of "repeating" fields, and stores an array of objects containing the fields that you define. Its uses can be simple or highly complex. + + +**Example uses:** + +- A "slider" with an image ([upload field](/docs/fields/upload)) and a caption ([text field](/docs/fields/text)) +- Navigational structures where editors can specify nav items containing pages ([relationship field](/docs/fields/relationship)), an "open in new tab" [checkbox field](/docs/fields/checkbox) +- Event agenda "timeslots" where you need to specify start time ([date field](/docs/fields/date)), end time, label ([text field](/docs/fields/text)), and Learn More page [relationship](/docs/fields/relationship) + +**Admin panel screenshot:** + +![Array field in Payload admin panel](/images/fields/array.jpg) + +### Config + +| Option | Description | +| ---------------- | ----------- | +| **`name`** * | To be used as the property name when stored and retrieved from the database. | +| **`label`** | Used as a heading in the Admin panel and to name the generated GraphQL type. | +| **`fields`** * | Array of field types to correspond to each row of the Array. | +| **`validate`** | Provide a custom validation function. [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 an array of row 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. If enabled, a separate, localized set of all data within this Array will be kept, so there is no need to specify each nested field as `localized`. | +| **`required`** | Require this field to have a value. | +| **`labels`** | Customize the row labels appearing in the Admin dashboard. | +| **`admin`** | Admin-specific configuration. See below for [more detail](/docs/fields/array#admin). | + +*\* An asterisk denotes that an option is required.* + +### Full example + +`collections/ExampleCollection.js` +```js +{ + slug: 'example-collection', + fields: [ + { + name: 'slider', // required + type: 'array', // required + label: 'Image Slider', + minRows: 2, + maxRows: 10, + labels: { + singular: 'Slide', + plural: 'Slides', + }, + fields: [ // required + { + name: 'image', + label: 'Image', + type: 'upload', + relationTo: 'media', + required: true, + }, + { + name: 'caption', + label: 'Caption', + type: 'text', + } + ] + } + ] +} + +``` + +### Admin + +This field features default admin options at this time. For more on default admin options, [click here](/docs/fields/overview#admin). diff --git a/docs/Fields/blocks.mdx b/docs/Fields/blocks.mdx index ddc55081de9..38d63d177ad 100644 --- a/docs/Fields/blocks.mdx +++ b/docs/Fields/blocks.mdx @@ -1,7 +1,115 @@ --- title: Blocks Field label: Blocks -order: 20 +order: 30 --- -get out + + The Blocks field type is incredibly powerful and can be used as a layout builder as well as to define any other flexible content model you can think of. It stores an array of objects, where each object must match the shape of one of your provided block configs. + + +**Example uses:** + +- A layout builder tool that grants editors to design highly customizable page or post layouts. Blocks could include configs such as `Quote`, `CallToAction`, `Slider`, `Content`, `Gallery`, or others. +- A form builder tool where available block configs might be `Text`, `Select`, or `Checkbox`. +- Virtual event agenda "timeslots" where a timeslot could either be a `Break`, a `Presentation`, or a `BreakoutSession`. + +**Admin panel screenshot:** + +![Blocks field in Payload admin panel](/images/fields/blocks.jpg) + +### Field config + +| Option | Description | +| ---------------- | ----------- | +| **`name`** * | To be used as the property name when stored and retrieved from the database. | +| **`label`** | Used as a heading in the Admin panel and to name the generated GraphQL type. | +| **`blocks`** * | Array of [block configs](/docs/fields/blocks#block-configs) to be made available to this field. | +| **`validate`** | Provide a custom validation function. [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-level hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) | +| **`access`** | Provide field-level 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 response or the Admin panel. | +| **`defaultValue`** | Provide an array of block 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. If enabled, a separate, localized set of all data within this field will be kept, so there is no need to specify each nested field as `localized`. || **`required`** | Require this field to have a value. | +| **`unique`** | Enforce that each entry in the Collection has a unique value for this field. | +| **`labels`** | Customize the block row labels appearing in the Admin dashboard. | +| **`admin`** | Admin-specific configuration. See below for [more detail](/docs/fields/array#admin). | + +*\* An asterisk denotes that an option is required.* + +### Block configs + +Blocks are defined as separate configs of their own. + + + Tip:
+ Best practice is to define each block config in its own file, and then import them into your Blocks field as necessary. This way each block config can be easily shared between fields. For instance, using the "layout builder" example, you might want to feature a few of the same blocks in a Post collection as well as a Page collection. Abstracting into their own files trivializes their reusability. + + +| Option | Description | +| ---------------- | ----------- | +| **`slug`** * | Identifier for this block type. Will be saved on each block as the `blockType` property. | +| **`fields`** * | Array of fields to be stored in this block. | +| **`labels`** | Customize the block labels that appear in the Admin dashboard. Also used to name corresponding GraphQL schema types. | +| **`imageURL`** | Provide a custom image thumbnail to help editors identify this block in the Admin UI. | +| **`imageAltText`** | Customize this block's image thumbnail alt text. | + +#### Required, auto-generated data per block + +In addition to the field data that you define on each block, Payload will store two additional required properties on each block: + +**`blockType`** + +The `blockType` is saved as the slug of the block that has been selected. + +**`blockName`** + +The Admin panel provides each block with a `blockName` field which optionally allows editors to label their blocks for better editability and readability. + +### Full example + +`collections/ExampleCollection.js` +```js +{ + slug: 'example-collection', + fields: [ + { + name: 'layout', // required + type: 'blocks', // required + label: 'layout', + minRows: 1, + maxRows: 20, + labels: { + singular: 'Layout', + plural: 'Layouts', + }, + blocks: [ // required + { + slug: 'Quote', // required + imageURL: 'https://google.com/path/to/image.jpg', + imageAltText: 'A nice thumbnail image to show what this block looks like', + fields: [ // required + { + name: 'text', + label: 'Quote Text', + type: 'text', + required: true, + }, + { + name: 'text', + label: 'Quotee', + type: 'text', + }, + ] + }, + ] + } + ] +} + +``` + +### Admin + +This field features default admin options at this time. For more on default admin options, [click here](/docs/fields/overview#admin-options). diff --git a/docs/Fields/overview.mdx b/docs/Fields/overview.mdx index 7fb9aa07a5a..91014ce36d6 100644 --- a/docs/Fields/overview.mdx +++ b/docs/Fields/overview.mdx @@ -39,13 +39,34 @@ const Pages = { - [Code](/docs/fields/code) - xode editor that saves a string to the database - [Date](/docs/fields/date) - date / time field that saves a timestamp - [Email](/docs/fields/email) - validates the entry is a properly formatted email -- [Group](/docs/fields/group) - +- [Group](/docs/fields/group) - nest fields within an object - [Number](/docs/fields/number) - field that enforces that its value be a number -- [Radio](/docs/fields/radio) - Radio button group, allowing only one value to be selected -- [Relationship](/docs/fields/relationship) - Assign relationships to other collections -- [Rich Text](/docs/fields/rich-text) - Fully extensible Rich Text editor -- [Row](/docs/fields/row) - Used for admin field layout, no effect on data shape -- [Select](/docs/fields/select) - Dropdown / picklist style based on `react-select` +- [Radio](/docs/fields/radio) - radio button group, allowing only one value to be selected +- [Relationship](/docs/fields/relationship) - assign relationships to other collections +- [Rich Text](/docs/fields/rich-text) - fully extensible Rich Text editor +- [Row](/docs/fields/row) - used for admin field layout, no effect on data shape +- [Select](/docs/fields/select) - dropdown / picklist style based on `react-select` - [Text](/docs/fields/text) - simple text input - [Textarea](/docs/fields/textarea) - allows a bit larger of a text editor -- [Upload](/docs/fields/upload) - Allows local file and image upload +- [Upload](/docs/fields/upload) - allows local file and image upload + +### Field-level hooks + +Briefly talk about field hooks and then link to the Field Hooks docs. + +### Field-level access control + +Briefly talk about field access control and then link to the Field access control docs. + +### Admin options + +Go through admin options here. + +- position +- width +- style +- readOnly +- disabled +- condition +- components +- hidden