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

feat: initial working draft

Browse Source
This commit is contained in:
Jacob Fletcher
2022-03-07 16:19:40 -05:00
parent e08e681eda
commit 6e340f008f
17 changed files with 203 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
packages/plugin-nested-docs/README.md
View File

@@ -1,17 +1,19 @@
# Payload Breadcrumbs Plugin
# Payload Nested Pages Plugin
[![NPM](https://img.shields.io/npm/v/payload-plugin-breadcrumbs)](https://www.npmjs.com/package/payload-plugin-breadcrumbs)
[![NPM](https://img.shields.io/npm/v/payload-plugin-nested-pages)](https://www.npmjs.com/package/payload-plugin-nested-pages)
A breadcrumbs for [Payload CMS](https://github.com/payloadcms/payload) to easily allow for nested documents.
A plugin for [Payload CMS](https://github.com/payloadcms/payload) to easily allow for documents to be nested inside one another.
Core features:
- Allows for [parent/child](#parent) relationships between documents
- Automatically populates [breadcrumbs](#breadcrumbs) data
## Installation
```bash
yarn add payload-plugin-breadcrumbs
yarn add payload-plugin-nested-pages
# OR
npm i payload-plugin-breadcrumbs
npm i payload-plugin-nested-pages
```
## Basic Usage
@@ -20,16 +22,29 @@ In the `plugins` array of your [Payload config](https://payloadcms.com/docs/conf
```js
import { buildConfig } from 'payload/config';
import breadcrumbs from 'payload-plugin-breadcrumbs';
import nestedPages from 'payload-plugin-nestedPages';
const config = buildConfig({
collections: [
{
slug: 'pages',
fields: [
{
name: 'title',
type: 'text'
},
{
name: 'slug',
type: 'text'
}
]
}
],
plugins: [
breadcrumbs({
collections: [''],
parentFieldSlug: '',
breadcrumbsFieldSlug: '',
generateLabel: '',
generateURL: ''
nestedPages({
collections: ['pages'],
generateLabel: (_, doc) => doc.title,
generateURL: (docs) => docs.reduce((url, doc) => `${url}/${doc.slug}`, ''),
})
]
});
@@ -37,21 +52,134 @@ const config = buildConfig({
export default config;
```
### Fields
#### Parent
The `parent` relationship field is automatically added to every document which allows editors to choose another document from the same collection to act as the direct parent.
#### Breadcrumbs
The `breadcrumbs` field is an array which dynamically populates all parent relationships of a document up to the top level. It does not store any data in the database, and instead, acts as a `virtual` field which is dynamically populated each time the document is loaded.
The `breadcrumbs` array stores the following fields:
- `label`
The label of the breadcrumb. This field is automatically set to either the `collection.admin.useAsTitle` (if defined) or is set to the `ID` of the document. You can also dynamically define the `label` by passing a function to the options property of [`generateLabel`](#generateLabel).
- `url`
The URL of the breadcrumb. By default, this field is undefined. You can manually define this field by passing a property called function to the plugin options property of [`generateURL`](#generateURL).
### Options
- `collections`
#### `collections`
An array of collections slugs to enable breadcrumbs.
An array of collections slugs to enable nested pages.
## TypeScript
#### `generateLabel`
All types can be directly imported:
```js
import {
BreadcrumbsConfig,
} from 'payload-plugin-breadcrumbs/dist/types';
```
Each `breadcrumb` has a required `label` field. By default, its value will be set to the collection's `admin.useAsTitle` or fallback the the `ID` of the document.
## Screenshots
You can also pass a function to dynamically set the `label` of your breadcrumb.
<!-- ![screenshot 1](https://github.com/trouble/payload-plugin-breadcrumbs/blob/main/images/screenshot-1.jpg?raw=true) -->
```js
{
plugins: [
...
nestedPages({
...
generateLabel: (_, doc) => doc.title // NOTE: 'title' is a hypothetical field
})
]
```
The function takes two arguments and returns a string:
1. `breadcrumbs` - an array of the breadcrumbs up to that point
2. `currentDoc` - the current document being edited
#### `generateURL`
A function that allows you to dynamically generate each breadcrumb `url`. Each `breadcrumb` has an optional `url` field which is undefined by default. For example, you might want to format a full URL to contain all of the breadcrumbs up to that point, like `/about-us/company/our-team`.
```js
plugins: [
...
nestedPages({
...
generateURL: (docs) => docs.reduce((url, doc) => `${url}/${doc.slug}`, ''), // NOTE: 'slug' is a hypothetical field
})
]
```
This function takes two arguments and returns a string:
1. `breadcrumbs` - an array of the breadcrumbs up to that point
1. `currentDoc` - the current document being edited
#### `parentFieldSlug`
When defined, the `parent` field will not be provided for you automatically, and instead, expects you to add your own `parent` field to each collection manually. This gives you complete control over where you put the field in your admin dashboard, etc. Set this property to the `name` of your custom field.
#### `breadcrumbsFieldSlug`
When defined, the `breadcrumbs` field will not be provided for you, and instead, expects your to add your own `breadcrumbs` field to each collection manually. Set this property to the `name` of your custom field.
> Note - if you opt out of automatically being provided a `parent` or `breadcrumbs` field, you need to make sure that both fields are placed at the top-level of your document. They cannot exist within any nested data structures like a `group`, `array`, or `blocks`.
## More
You can also extend the built-in `parent` and `breadcrumbs` fields on a page-by-page basis by importing helper methods as follows:
```js
import { CollectionConfig } from 'payload/types';
import createParentField from 'payload-plugin-nested-pages/fields/parent';
import createBreadcrumbsField from 'payload-plugin-nested-pages/fields/breadcrumbs';
const examplePageConfig: CollectionConfig = {
slug: 'pages',
fields: [
createParentField(
// First argument is equal to the slug of the collection
// that the field references
'pages',
// Second argument is equal to field overrides that you specify,
// which will be merged into the base parent field config
{
admin: {
position: 'sidebar',
},
},
),
createBreadcrumbsField(
// First argument is equal to the slug of the collection
// that the field references
'pages',
// Argument equal to field overrides that you specify,
// which will be merged into the base `breadcrumbs` field config
{
label: 'Page Breadcrumbs',
}
)
]
}
```
## TypeScript
All types can be directly imported:
```js
import {
NestedPagesConfig,
GenerateURL,
GenerateLabel
} from 'payload-plugin-nested-pages/dist/types';
```
## Screenshots
<!-- ![screenshot 1](https://github.com/trouble/payload-plugin-nested-pages/blob/main/images/screenshot-1.jpg?raw=true) -->

2
packages/plugin-nested-docs/demo/package.json
View File

@@ -15,7 +15,7 @@
"dependencies": {
"dotenv": "^8.2.0",
"express": "^4.17.1",
"payload": "^0.14.24-beta.0"
"payload": "^0.14.30-beta.0"
},
"devDependencies": {
"@types/express": "^4.17.9",

6
packages/plugin-nested-docs/demo/src/collections/Pages/index.ts → packages/plugin-nested-docs/demo/src/collections/Pages.ts
View File

@@ -16,6 +16,12 @@ export const Pages: CollectionConfig = {
label: 'Title',
type: 'text',
required: true,
},
{
name: 'slug',
label: 'Slug',
type: 'text',
required: true,
}
],
};

0
packages/plugin-nested-docs/demo/src/collections/Users/index.ts → packages/plugin-nested-docs/demo/src/collections/Users.ts
View File

8
packages/plugin-nested-docs/demo/src/payload.config.ts
View File

@@ -1,7 +1,7 @@
import { buildConfig } from 'payload/config';
import path from 'path';
import breadcrumbsPlugin from '../../dist';
// import breadcrumbsPlugin from '../../src';
// import nestedPages from '../../dist';
import nestedPages from '../../src';
import { Users } from './collections/Users';
import { Pages } from './collections/Pages';
@@ -31,10 +31,12 @@ export default buildConfig({
Pages
],
plugins: [
breadcrumbsPlugin({
nestedPages({
collections: [
'pages'
],
generateLabel: (_, doc) => doc.title as string,
generateURL: (docs) => docs.reduce((url, doc) => `${url}/${doc.slug}`, ''),
}),
],
typescript: {

8
packages/plugin-nested-docs/demo/yarn.lock
View File

@@ -7425,10 +7425,10 @@ pause@0.0.1:
resolved "https://registry.yarnpkg.com/pause/-/pause-0.0.1.tgz#1d408b3fdb76923b9543d96fb4c9dfd535d9cb5d"
integrity sha1-HUCLP9t2kjuVQ9lvtMnf1TXZy10=
payload@^0.14.24-beta.0:
version "0.14.24-beta.0"
resolved "https://registry.yarnpkg.com/payload/-/payload-0.14.24-beta.0.tgz#45bdbee0012bdfe97b4419637663cec3384ecdf8"
integrity sha512-wLKyTEUPWxZZBjYNll8cCnQApGPWQYp2R0e1ZEhsVnVE5jfxxdLPbzy9KPwHgpJC9Aol5jDFXOzdlmQg3p4NRg==
payload@^0.14.30-beta.0:
version "0.14.30-beta.0"
resolved "https://registry.yarnpkg.com/payload/-/payload-0.14.30-beta.0.tgz#7138008cd1fa46d8c2d769d9f03564b0f0f93175"
integrity sha512-HGk7tMf+nBEuuu2Xqvo5CpQIM1V3onISo+V1deHiYm/Bknrsuj8KT8wED9C4kc3O3Woz53fFa+eAZPM6N4Ds1w==
dependencies:
"@babel/cli" "^7.12.8"
"@babel/core" "^7.11.6"

12
packages/plugin-nested-docs/package.json
View File

@@ -1,7 +1,7 @@
{
"name": "payload-plugin-breadrumbs",
"name": "payload-plugin-nested-pages",
"version": "0.0.1",
"description": "Breadcrumbs plugin for Payload CMS",
"description": "Nested pages plugin for Payload CMS",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
@@ -15,17 +15,17 @@
"typescript",
"react",
"breadcrumbs",
"parent pages",
"nesting"
"nested pages",
"parent pages"
],
"author": "dev@trbl.design",
"license": "MIT",
"peerDependencies": {
"payload": "^0.14.24-beta.0",
"payload": "^0.14.30-beta.0",
"react": "^17.0.2"
},
"devDependencies": {
"payload": "^0.14.24-beta.0",
"payload": "^0.14.30-beta.0",
"react": "^17.0.2",
"typescript": "^4.5.5"
},

143
packages/plugin-nested-docs/src/README.md
View File

@@ -1,143 +0,0 @@
# Breadcrumbs
This plugin extends Payload collections with a parent -> child hierarchy as well as dynamically populates "breadcrumbs".
### Example Installation
```js
import { buildConfig } from 'payload/config';
import breadcrumbs from '@payloadcms/plugin-breadcrumbs';
import Pages from './collections/Pages';
export default buildConfig({
serverURL: 'https://localhost:3000',
collections: [
Pages,
],
plugins: [
breadcrumbs({
collections: ['pages'],
generateURL: (parentBreadcrumbs, currentDoc) => {
// This example shows how to combine breadcrumb URLs to create full
// URL paths like /about/company/our-team
// Reduce the parent breadcrumbs into a string
// Initialize the reducer's accumulator as the current doc's slug
return parentBreadcrumbs.reduce(
(url, breadcrumb) => {
// Join paths together
return `${breadcrumb.url}${url}`;
},
`/${currentDoc.slug}`
);
}
,
}),
}),
],
})
```
## How it works
This plugin adds two new fields to all collections that you specify:
### `parent`
The `parent` field is a `relationship` that allows for editors to choose a parent document from the same collection, which acts as the document's direct parent.
### `breadcrumbs`
The `breadcrumbs` field is an `array` which dynamically populates all parent relationships of a document up to the top level. It does not store any data in the database, and instead, acts as a `virtual` field which is dynamically populated each time the document is loaded.
The `breadcrumbs` array stores the following fields:
**`label`**
The label of the breadcrumb. This field is automatically set to either the `collection.admin.useAsTitle` (if defined) or is set to the `ID` of the document. You can also dynamically define the `label` by passing a function to the options property of `generateLabel`. More detail is below.
**`url`**
The URL of the breadcrumb. By default, this field is undefined. You can manually define this field by passing a property called function to the plugin options property of `generateURL`.
## Options
| Option | Description |
| -------------------------- | ----------- |
| **`collections`** * | An array of collection slugs of which you want to enable breadcrumbs on. |
| **`generateURL`** | A function that allows you to dynamically generate a URL for each breadcrumb. |
| **`generateLabel`** | A function that allows you to dynamically generate a label for each breadcrumb. |
| **`parentFieldSlug`** | If defined, the plugin will assume that you are providing your own parent field, equal to this slug, into each collection where breadcrumbs is enabled. |
| **`breadcrumbsFieldSlug`** | If defined, the plugin will assume that you are providing your own breadcrumbs field, equal to this slug, into each collection where breadcrumbs is enabled. |
*\* An asterisk denotes that a property is required.*
##### `generateLabel`
Each `breadcrumb` has a required `label` field. By default, its value will be set to the collection's `admin.useAsTitle` field data, and if that data is not defined, the field will be set to the `ID` of the document. However, you can pass a function to this option that allows you to dynamically set the `label` of your breadcrumb.
The function takes two arguments:
1. `breadcrumbs` - an array of the breadcrumbs up to that point
1. `currentDoc` - the current document being edited
The function should return a string.
##### `generateURL`
As with a label, each `breadcrumb` has an optional `url` field. By default, its value will be undefined, but you can pass a function to this option that allows you to dynamically set the `url` of your breadcrumb. For example, you might want to format a full URL containing all breadcrumbs up to that point, say, like `/about-us/company/our-team`. Logic to combine breadcrumbs into a full URL can go here.
The function also takes two arguments:
1. `breadcrumbs` - an array of the breadcrumbs up to that point
1. `currentDoc` - the current document being edited
The function should return a string.
##### `parentFieldSlug`
You can opt out of having the `parent` field provided for you, and instead, provide it yourself to each collection that enables breadcrumbs. This gives you complete control over where you put the field in your admin dashboard, among other customizations. If you pass this property the `name` of your manually provided `parent` field, the plugin will opt-out of automatically providing this field for you and refer to your field instead.
##### `breadcrumbsFieldSlug`
As with the above option, you can also opt out of having the `breadcrumbs` field provided for you by providing your own field, and then passing its `name` to this property.
> Note - if you opt out of automatically being provided a `parent` or `breadcrumbs` field, you need to make sure that both fields are placed at the top-level of your document. They cannot exist within any nested data structures like a `group`, `array`, or `blocks`.
**Tip: You can also leverage and extend the built-in `parent` and `breadcrumb` fields by importing helper methods as follows:**
```js
import { CollectionConfig } from 'payload/types';
import createParentField from '@payloadcms/plugin-breadcrumbs/fields/parent';
import createBreadcrumbsField from '@payloadcms/plugin-breadcrumbs/fields/breadcrumbs';
const examplePageConfig: CollectionConfig = {
slug: 'pages',
fields: [
createParentField(
// First argument is equal to the slug of the collection
// that the field references
'pages',
// Second argument is equal to field overrides that you specify,
// which will be merged into the base parent field config
{
admin: {
position: 'sidebar',
},
},
),
createBreadcrumbsField(
// First argument is equal to the slug of the collection
// that the field references
'pages',
// Argument equal to field overrides that you specify,
// which will be merged into the base `breadcrumbs` field config
{
label: 'Page Breadcrumbs',
}
)
]
}
```

9
packages/plugin-nested-docs/src/fields/breadcrumbs.ts
View File

@@ -1,7 +1,7 @@
import { ArrayField } from 'payload/dist/fields/config/types';
import { Field } from 'payload/types';
import deepMerge from '../../../utilities/deepMerge';
const createBreadcrumbsField = (relationTo: string, overrides: Partial<Field> = {}): Field => deepMerge({
const createBreadcrumbsField = (relationTo: string, overrides: Partial<ArrayField> = {}): Field => ({
name: 'breadcrumbs',
type: 'array',
fields: [
@@ -34,10 +34,13 @@ const createBreadcrumbsField = (relationTo: string, overrides: Partial<Field> =
},
],
},
...overrides?.fields || []
],
admin: {
readOnly: true,
...overrides?.admin || {}
},
}, overrides);
...overrides || {}
});
export default createBreadcrumbsField;

8
packages/plugin-nested-docs/src/fields/parent.ts
View File

@@ -1,14 +1,16 @@
import { RelationshipField } from 'payload/dist/fields/config/types';
import { Field } from 'payload/types';
import deepMerge from '../../../utilities/deepMerge';
const createParentField = (relationTo: string, overrides: Partial<Field> = {}): Field => deepMerge({
const createParentField = (relationTo: string, overrides: Partial<RelationshipField>): Field => ({
name: 'parent',
relationTo,
type: 'relationship',
maxDepth: 1,
admin: {
position: 'sidebar',
...overrides?.admin || {},
},
}, overrides);
...overrides || {}
});
export default createParentField;

2
packages/plugin-nested-docs/src/hooks/resaveChildren.ts
View File

@@ -1,5 +1,5 @@
import { CollectionConfig, CollectionAfterChangeHook } from 'payload/types';
import populateBreadcrumbs from '../populateBreadcrumbs';
import populateBreadcrumbs from '../utilities/populateBreadcrumbs';
import { Options } from '../types';
const resaveChildren = (options: Options, collection: CollectionConfig): CollectionAfterChangeHook => ({ req: { payload }, req, doc }) => {

11
packages/plugin-nested-docs/src/hooks/resaveSelfAfterCreate.ts
View File

@@ -1,6 +1,13 @@
import { CollectionConfig, CollectionAfterChangeHook } from 'payload/types';
import { Breadcrumb } from '../types';
type DocWithBreadcrumbs = {
breadcrumbs: Breadcrumb[]
}
const resaveSelfAfterCreate = (collection: CollectionConfig): CollectionAfterChangeHook => async ({ req: { payload }, req, doc, operation }) => {
const { breadcrumbs = [] } = doc as DocWithBreadcrumbs;
if (operation === 'create') {
const originalDocWithDepth0 = await payload.findByID({
collection: collection.slug,
@@ -14,9 +21,9 @@ const resaveSelfAfterCreate = (collection: CollectionConfig): CollectionAfterCha
depth: 0,
data: {
...originalDocWithDepth0,
breadcrumbs: doc.breadcrumbs.map((crumb, i) => ({
breadcrumbs: breadcrumbs.map((crumb, i) => ({
...crumb,
doc: doc?.breadcrumbs?.length === i + 1 ? doc.id : crumb.doc,
doc: breadcrumbs?.length === i + 1 ? doc.id : crumb.doc,
})),
},
});

3
packages/plugin-nested-docs/src/index.ts
View File

@@ -2,11 +2,10 @@ import { Config } from 'payload/config';
import { Options } from './types';
import createBreadcrumbsField from './fields/breadcrumbs';
import createParentField from './fields/parent';
import populateBreadcrumbs from './populateBreadcrumbs';
import populateBreadcrumbs from './utilities/populateBreadcrumbs';
import resaveChildren from './hooks/resaveChildren';
import resaveSelfAfterCreate from './hooks/resaveSelfAfterCreate';
const breadcrumbs = (options: Options) => (config: Config): Config => ({
...config,
collections: (config.collections || []).map((collection) => {

4
packages/plugin-nested-docs/src/formatBreadcrumb.ts → packages/plugin-nested-docs/src/utilities/formatBreadcrumb.ts
View File

@@ -1,12 +1,12 @@
import { CollectionConfig } from 'payload/types';
import { Options, Breadcrumb } from './types';
import { Options, Breadcrumb } from '../types';
const formatBreadcrumb = (
options: Options,
collection: CollectionConfig,
docs: Record<string, unknown>[],
): Breadcrumb => {
let url: string;
let url: string | undefined = undefined;
let label: string;
const lastDoc = docs[docs.length - 1];

2
packages/plugin-nested-docs/src/getParents.ts → packages/plugin-nested-docs/src/utilities/getParents.ts
View File

@@ -1,5 +1,5 @@
import { CollectionConfig } from 'payload/types';
import { Options } from './types';
import { Options } from '../types';
const getParents = async (
req: any,

2
packages/plugin-nested-docs/src/populateBreadcrumbs.ts → packages/plugin-nested-docs/src/utilities/populateBreadcrumbs.ts
View File

@@ -1,5 +1,5 @@
import { CollectionConfig } from 'payload/types';
import { Options } from './types';
import { Options } from '../types';
import getParents from './getParents';
import formatBreadcrumb from './formatBreadcrumb';

8
packages/plugin-nested-docs/yarn.lock
View File

@@ -7145,10 +7145,10 @@ pause@0.0.1:
resolved "https://registry.yarnpkg.com/pause/-/pause-0.0.1.tgz#1d408b3fdb76923b9543d96fb4c9dfd535d9cb5d"
integrity sha1-HUCLP9t2kjuVQ9lvtMnf1TXZy10=
payload@^0.14.24-beta.0:
version "0.14.24-beta.0"
resolved "https://registry.yarnpkg.com/payload/-/payload-0.14.24-beta.0.tgz#45bdbee0012bdfe97b4419637663cec3384ecdf8"
integrity sha512-wLKyTEUPWxZZBjYNll8cCnQApGPWQYp2R0e1ZEhsVnVE5jfxxdLPbzy9KPwHgpJC9Aol5jDFXOzdlmQg3p4NRg==
payload@^0.14.30-beta.0:
version "0.14.30-beta.0"
resolved "https://registry.yarnpkg.com/payload/-/payload-0.14.30-beta.0.tgz#7138008cd1fa46d8c2d769d9f03564b0f0f93175"
integrity sha512-HGk7tMf+nBEuuu2Xqvo5CpQIM1V3onISo+V1deHiYm/Bknrsuj8KT8wED9C4kc3O3Woz53fFa+eAZPM6N4Ds1w==
dependencies:
"@babel/cli" "^7.12.8"
"@babel/core" "^7.11.6"