Working example of nested pages.

[danielkoller]

Hi everyone,

firstly I would like to congratulate the Payload Team to their amazing product. Beside some minor flaws, I really like working with it.

I have a wish for a video/better documentation/website template, namely the integration of a working example of nested pages.

It is one of the most common use cases when building extensive websites and I really had a hard time integrating it.

What helped me was the payload website itself, where it is nicely integrated.

So please implement a working example of nested pages into the website template or extend the docs on how to properly integrate it.

Thanks and keep up the great work!

[HarleySalas]

Hey @danielkoller

I do agree, perhaps the website template should be using @payloadcms/plugin-nested-docs for the pages collection to render pages.
Maybe @paulpopus will support this idea and I can submit a PR for it? To git a bit further context... I have explained how I do nested pages probably half a dozen times this week. It's something that people commonly wonder about.

The difference in my template and the existing "website" template for nested pages is as follows:

Instead of the following files to cover the pages collection;
/app/(frontend)/page.tsx
and
/app/(frontend)/[slug]/page.tsx

I utilize one single page.tsx file, which covers the index/homepage and all of the pages collection, which contains nested pages at any depth;

/app/(frontend)/[[...segments]]/page.tsx
I've also opted for the term "segments" as I use the term "slug" everywhere else, which does not contain nested docs, as I believe it is a more accurate depiction.

When rendering the page (inside of that page.tsx file) I query for the page by it's entire pathname, which should be unique and indexed, like so:

interface Props {
  params: Promise<{
    segments: string[]
  }>
}

const Pages = async ({ params }: Props) => {
  const { segments } = await params
  const pathname = resolvePathname(segments)
  const page = await getPageByPathname(pathname)

  if (!page) {
    notFound()
  }

  return (
    <>
      <Hero {...page.hero} />
      <RenderBlocks blocks={page.blocks} />
    </>
  )
}

You can resolve the pathname with this resolvePathname utility function:

export const resolvePathname = (param: string | string[] | undefined): string => {
  if (typeof param === 'string') {
    return param
  }

  if (Array.isArray(param)) {
    return `/${param.join('/')}`
  }

  return '/'
}

It should be noted that I do not use the slug "index" or "home" to determine my root page, but I allow an instance of a simple forward slash, / as the slug to indicate an index/homepage. So if you do it differently, you'll have to account for that.

For my slug field on the pages collection, It should be noted that I also modify the slug field from the website example, to allow for duplicating documents and I use a library called standard-slugify to transliterate any alphabet to latin and create url safe slugs from any language.

import type { TextField, FieldHook } from 'payload'
import format from 'standard-slugify'
import { deepMerge } from '@/utils/deepMerge'
import { generateShortId } from '@/utils/generateShortId'

type Slug = (fieldToUse?: string, overrides?: Partial<TextField>) => TextField

const formatSlug =
  (field: string): FieldHook =>
  ({ operation, value, previousValue, data, context }) => {
    if (!operation || (operation !== 'create' && operation !== 'update') || context.duplicate) {
      return
    }

    if (value === '/') return value

    if (typeof value === 'string' && value.length > 0 && value !== previousValue) {
      return format(value)
    }

    if (!value && data?.[field]) {
      return format(data[field])
    }
  }
export const slug: Slug = (fieldToUse = 'title', overrides = {}) =>
  deepMerge<Field, Partial<Field>>(
    {
      name: 'slug',
      label: "Slug",
      type: 'text',
      index: true,
      unique: true,
      admin: {
        position: 'sidebar',
      },
      hooks: {
        beforeValidate: [formatSlug(fieldToUse)],
        beforeDuplicate: [
          ({ value, context }) => {
            context.duplicate = true
            if (value === '/') {
              return generateShortId()
            }
            return `${value}-${generateShortId()}`
          },
        ],
      },
    },
    overrides,
  )

generateShortId is just a short, dependency-less id that is generated to ensure that duplicating any document ultimately always gets a unique pathname.

import crypto from 'crypto'

export const generateShortId = () => {
  return crypto.randomBytes(6).toString('base64url').slice(0, 8)
}

Provided that you add @payloadcms/plugin-nested-docs to your collection, there is one last piece to the puzzle; putting the pathname on your pages collection documents. We actually add our slug component with an override, specifying that the slug itself does not need to be unique for nested-docs, as pathname will be the unique and indexed value.

  slug(undefined, {unique: false, index: false}), //targets the "title" field automatically to generate slugs
{
      name: 'pathname',
      type: 'text',
      unique: true,
      index: true,
      admin: {
        readOnly: true,
        position: 'sidebar',
      },
      hooks: {
        beforeChange: [syncPathname],
      },
    },

and for syncPathname, we just take the last url that is available from the breadcrumbs that come with @payloadcms/plugin-nested-docs:

import { FieldHook } from 'payload'

export const syncPathname: FieldHook = async ({ data, value, operation }) => {
  if (
    (operation === 'create' || operation === 'update') &&
    data?.breadcrumbs?.at(-1)?.url !== value &&
    data?.breadcrumbs?.at(-1)?.url !== '/undefined'
  ) {
    return data?.breadcrumbs?.at(-1)?.url || ''
  }
}

Hopefully that's enough to get you started. Feel free to ask any more questions if you have them.

[paulpopus]

Maybe @paulpopus will support this idea and I can submit a PR for it?

I think this should be its own example in examples/. I would take a PR for that but otherwise I would prefer to minimise complexity in the website template, some people have already reported that it's too complex for their needs.

[danielkoller]

But the nested docs plugin is already part of the website template - why not just use it for pages instead of categories? :) I really think that a better documentation is needed here. Beside that, I really had a blast working with the website template. Great job!