Menus, site-wide content and lists

Pages are only part of a website. This page covers the rest: menus, site-wide content, lists of entries and references between them. It uses the cms client from Connect a website. Every call here reads published content, and takes preview: true to read drafts while previewing.

Menus

Editors build menus in Menus, each with a key such as main or footer.

const menu = await cms.findNavigation({ key: 'main' })

Both take region, locale, preview and signal. A menu can be shared by every region or belong to one; ask with the region you are showing and the right one answers.

A menu has key, name and items. Each item has:

Items that link to an unpublished page are left out, and hidden items never arrive.

A menu with one level of sub-menus:

1import Link from 'next/link'2import type { CmsNavItem } from '@bifrost-orbit-cms/sdk'34function Item({ item }: { item: CmsNavItem }) {5  const label = (6    <>7      {item.label}8      {item.badge ? <span className="badge">{item.badge}</span> : null}9    </>10  )11  return (12    <li>13      {item.href ? <Link href={item.href} target={item.target ?? undefined}>{label}</Link> : <span>{label}</span>}14      {item.children.length > 0 ? (15        <ul>16          {item.children.map((child) => (17            <Item key={`${child.label}-${child.href}`} item={child} />18          ))}19        </ul>20      ) : null}21    </li>22  )23}2425export function SiteMenu({ items }: { items: CmsNavItem[] }) {26  return (27    <nav aria-label="Main">28      <ul>29        {items.map((item) => (30          <Item key={`${item.label}-${item.href}`} item={item} />31        ))}32      </ul>33    </nav>34  )35}

To mark the current page, compare item.href with the address in a client component using usePathname() from next/navigation.

Mark the menu for the preview so editors can open it from there: <header data-cms-edit="navigation:main" data-cms-edit-label="Menu">. See Set up the live preview.

Changing a menu sends navigation.changed, which refreshes cms:nav:<key> and every page that shows it.

Site-wide content

Content used on every page, such as the footer text, contact details, social links or the cookie notice, lives in global entries. Each has a key, such as footer.

const footer = await cms.findGlobal({ key: 'footer' })

Both take region, locale, strict, preview, include and signal. A global entry follows the language fallback, but not the region fallback.

A global has key, name, contentType, locale (the language that answered), fields and components. Type the fields with the generated type for its content type:

1import type { FooterFields } from '@/cms/types'23const footer = await cms.findGlobal({ key: 'footer' })4const fields = footer?.fields as FooterFields | undefined

Draw its components with the same registry as pages:

<CmsBlocks blocks={footer?.components} registry={registry} />

Read several at once so the layout waits for the slowest, not the sum:

1const [header, footer, menu] = await Promise.all([2  cms.findGlobal({ key: 'header' }),3  cms.findGlobal({ key: 'footer' }),4  cms.findNavigation({ key: 'main' }),5])

find… answers null when the entry is missing, but still throws when the CMS cannot be reached. To keep the website up during an outage, catch per call: cms.findGlobal({ key: 'footer' }).catch(() => null), or use Promise.allSettled.

Publishing any entry without an address refreshes cms:global, so every global is fetched fresh on the next visit.

Lists and index pages

list reads entries of one content type, such as blog posts or products, for an index page:

const posts = await cms.list({ type: 'blogPost', sort: '-publishedAt', perPage: 12, page: 1 })

The answer:

1{2  items: [{ id, url, name, contentType, publishedAt, seo, fields? }],3  total: 42,     // matching entries across all pages4  page: 1,5  hasMore: true, // ask for page 26}

To keep every entry of a type under one address, set Address on the content type in Schema › Content types, such as /blog. Every entry then lives at /blog/<slug>, whatever folder it is in, including new ones editors create. It can be set only when every entry already lives there, so no address changes, and removed only when the type has no entries. Make the index page the hub page of a folder with the same address, so editors find it beside the entries.

Items are summaries: no body. Link to each item's url, and render the full entry on its own page. An entry without an address has url and seo set to null. Global entries never appear in lists.

A paginated index page

1import Link from 'next/link'2import { cms } from '@/lib/cms'34export const revalidate = 6056type Props = { searchParams: Promise<{ page?: string }> }78export default async function Blog({ searchParams }: Props) {9  const page = Math.max(1, Number((await searchParams).page) || 1)10  const posts = await cms.list({ type: 'blogPost', sort: '-publishedAt', perPage: 12, page })1112  return (13    <main>14      <h1>Blog</h1>15      <ul>16        {posts.items.map((post) => (17          <li key={post.id}>{post.url ? <Link href={post.url}>{post.name}</Link> : post.name}</li>18        ))}19      </ul>20      <nav>21        {page > 1 ? <Link href={`/blog?page=${page - 1}`}>Newer</Link> : null}22        {posts.hasMore ? <Link href={`/blog?page=${page + 1}`}>Older</Link> : null}23      </nav>24    </main>25  )26}

A folder such as app/blog takes priority over the catch-all page route, so /blog is this index while /blog/my-post still comes from the CMS. Reading searchParams renders the page on each request, but the CMS answer is still cached under cms:list. To keep the index fully cached, put the page number in the address instead, such as app/blog/page/[n]/page.tsx.

If editors also build the index page itself in the CMS, with an intro and components, render it from the catch-all route and add the list as a component that fetches it; see "Components that need more data" in Render components.

Every entry, across pages

1async function allEntries(type: string) {2  const items = []3  for (let page = 1; ; page += 1) {4    const result = await cms.list({ type, page, perPage: 100 })5    items.push(...result.items)6    if (!result.hasMore) return items7  }8}

Entries without an address

Some entries are never pages, such as FAQ entries, team members or testimonials. Read them with their fields:

1import type { FaqEntryFields } from '@/cms/types'23const faqs = await cms.list<FaqEntryFields>({ type: 'faqEntry', category: 'pricing', include: ['fields'] })4faqs.items.map((item) => item.fields?.question)

The type parameter types fields. Fields arrive as on a page: images as objects, links with current addresses, rich text as HTML.

Filters and search

1await cms.list({ type: 'product', filter: { activity: 'hiking', season: 'winter' } })2await cms.list({ type: 'blogPost', tag: 'hiking' })3await cms.list({ type: 'faqEntry', category: 'pricing', include: ['fields'] })4await cms.list({ type: 'product', q: 'boots' })

• Filter values are text: pass '60', not 60. A field key must start with a letter and contain only letters, digits and underscores.
• q matches entry names only. For full-text search across bodies, send the entries to a search service, such as Algolia or Meilisearch, from your webhook route when content is published.
• For a filter driven by visitors, read the choices from a taxonomy: cms.getTaxonomy({ key: 'activity' }) answers its terms, each with value, label and sortOrder.

References

Reference and References fields point at other entries, such as the author of a post or the questions in an FAQ block. By default they arrive as entry ids. Ask for the entries instead with include:

const result = await cms.resolve({ path, preview, include: ['references'] })

resolve, getPage, getGlobal and list take it. Every Reference field on the entry and in any of its components then holds the entry, with id, url, name, contentType, publishedAt and fields:

1export function FaqList({ block }: BlockProps<'faqList'>) {2  return (3    <section data-cms-id={block.id}>4      {block.questions?.map((entry) => (5        <details key={entry.id}>6          <summary>{entry.fields.question}</summary>7          <RichText value={entry.fields.answer} />8        </details>9      ))}10    </section>11  )12}

• Type it: generate types with --include references, so block.questions is typed as CmsEntry<FaqEntryFields>[] rather than string[]. Read every page with include: ['references'] so the types are always true.
• One level only: references inside a referenced entry stay ids.
• Unpublished entries are left out of a References list, and a Reference becomes null. Previews show drafts of referenced entries too.
• Language: each entry is read in the visitor's language, with the same fallback as the page.
• Refreshing: answers with references are tagged cms:references, and every content change refreshes that tag, so a page showing an FAQ entry updates when the entry is published.
• Live preview: CmsLivePage asks the editor for references too when the page was read with them.

Without include, fetch referenced entries yourself with list and filter, or keep the ids for linking.

Regions, products and other content

• Regions and their languages: cms.getRegions() and cms.getLocales(region); see Regions and languages.
• Banners, popups and countdowns: see Render banners, popups and countdowns.
• Products: cms.getProducts({ page, perPage, filter }) answers products with prices and stock from the shop catalogue, in the same shape as lists.
• Anything else, in one request: GraphQL through cms.graphql(query, { variables }). GraphQL answers are never cached by the SDK; wrap them in your own cache if you use them on public pages.