payload-plugin-nested-pages v0.0.4
Notice: This plugin has moved! It is now supported by PayloadCMS — see the official plugin for full details.
Payload Nested Pages Plugin
A plugin for Payload CMS to easily allow for documents to be nested inside one another.
Core features:
- Allows for parent/child relationships between documents
- Automatically populates breadcrumbs data
Installation
yarn add payload-plugin-nested-pages
# OR
npm i payload-plugin-nested-pages
Basic Usage
In the plugins
array of your Payload config, call the plugin with options:
import { buildConfig } from 'payload/config';
import nestedPages from 'payload-plugin-nestedPages';
const config = buildConfig({
collections: [
{
slug: 'pages',
fields: [
{
name: 'title',
type: 'text'
},
{
name: 'slug',
type: 'text'
}
]
}
],
plugins: [
nestedPages({
collections: ['pages'],
generateLabel: (_, doc) => doc.title,
generateURL: (docs) => docs.reduce((url, doc) => `${url}/${doc.slug}`, ''),
})
]
});
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 theID
of the document. You can also dynamically define thelabel
by passing a function to the options property ofgenerateLabel
.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
collections
An array of collections slugs to enable nested pages.
generateLabel
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.
You can also pass a function to dynamically set the label
of your breadcrumb.
{
plugins: [
...
nestedPages({
...
generateLabel: (_, doc) => doc.title // NOTE: 'title' is a hypothetical field
})
]
The function takes two arguments and returns a string:
breadcrumbs
- an array of the breadcrumbs up to that pointcurrentDoc
- 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
.
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:
breadcrumbs
- an array of the breadcrumbs up to that pointcurrentDoc
- 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
orbreadcrumbs
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 agroup
,array
, orblocks
.
More
You can also extend the built-in parent
and breadcrumbs
fields on a page-by-page basis by importing helper methods as follows:
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:
import {
NestedPagesConfig,
GenerateURL,
GenerateLabel
} from 'payload-plugin-nested-pages/dist/types';