Linked Pages

A linked page is a page on a site that shows content from somewhere else: an upstream page your platform supplies. A platform with hundreds of customer sites can keep one "Privacy policy", "Inventory" or "Contact us" page and let every site link it. When the upstream page changes, every linked page shows the change. A site that wants its own version duplicates the page and edits the copy.

Your platform owns the upstream pages. ChaiBuilder stores only the upstream page's id on the linked page and asks your code for its content whenever it is needed.

What editors see

With the feature on, Add New Page offers two tabs: Create from scratch and Link upstream page. The Link tab lists the pages your platform offers, grouped under the headings you supply. The editor picks one, a parent page and a slug, and the new page opens in the builder.

  • A linked page is view-only. The canvas shows the upstream content, nothing on it can be edited, and the page never saves. A notice offers Duplicate and edit.
  • Duplicate and edit copies the upstream content into the page, asks for confirmation, and turns it into an ordinary editable page. Later upstream changes no longer reach it.
  • Reset throws the copy away, including its own design tokens, and links the page to its upstream page again. It also asks first.
  • The pages manager labels each such page Linked or Cloned, and both open like any other page.
  • A linked page gets no language pages until it is duplicated.

A dynamic upstream page (a template that matches many URLs) must be linked under a parent page, takes its parent's path as its own, and has no slug of its own. It has no View live link, because it has no single URL.

The word "upstream page" is a default. Name it the way your platform does with labels.features.upstreamPage on the editor, as a string or a map of locales:

<ChaiWebsiteBuilder labels={{ features: { upstreamPage: { en: 'System Page', fr: 'Page système' } } }} />

Turn it on

Three pieces, all on the server:

  1. Set features: { upstreamPages: true }. The flag is off by default.
  2. Pass an upstreamPageSource to buildChaiBuilderConfig.
  3. Register a LIST_UPSTREAM_PAGES action that returns the pages a site may link.
// chaibuilder.config.ts
import { buildChaiBuilderConfig } from 'chaipro/nextjs/server'
import type { ChaiUpstreamPageSource } from 'chaipro/types'
import { ListUpstreamPagesAction } from './actions/list-upstream-pages'

const upstreamPageSource: ChaiUpstreamPageSource = {
  // May this site link this page on this user's behalf? Return the page, or null.
  async findLinkable({ id, appId, userId }) {
    const page = await platform.pages.findOfferedTo(appId, id, userId)
    return page ? { id: page.id, name: page.name, pageType: page.pageType, dynamic: page.isTemplate } : null
  },
  // The published content a linked page of this site renders and a duplicate copies.
  async getContent(id, { appId, live }) {
    const page = await platform.pages.contentFor(id, appId, { published: live })
    return page ? { blocks: page.blocks, seo: page.seo } : null
  },
}

export default buildChaiBuilderConfig({
  db,
  features: { upstreamPages: true },
  upstreamPageSource,
  actions: { LIST_UPSTREAM_PAGES: new ListUpstreamPagesAction() },
})

findLinkable

Called before a page is linked and before a duplicate is reset. Return the page when site appId may link it for userId, or null to refuse. This is your access check: ChaiBuilder trusts the answer.

getContent

Returns { blocks, seo } for the page, or null when it is gone. Two rules:

  • Make the content the site's own. Links, global blocks and any other ids in the blocks should point at the site's rows, not at the site the page came from.
  • Respect live. When live is true the call is for a live render, so match the site's published rows, since only those render. Otherwise (the editor, preview, a duplicate) match its drafts.

LIST_UPSTREAM_PAGES

The action returns { pages: ChaiUpstreamPageOption[] }, the options the Link tab lists:

Field Description
id The upstream page's id, stored on the linked page
name Shown in the list
pageType The page's type, or null
slug Optional. Prefills the slug; the name is slugified when it is absent
group Optional. The heading the page is listed under
dynamic Optional. true for a template that takes its parent's path

Write it like any custom action, and check the caller's permissions inside it.

Caching

Every cached render of a linked page carries the tag upstream-page-<id>, where <id> is the upstream page's id. When an upstream page's published content changes, revalidate that tag and every site linking the page picks up the change:

import { revalidateTag } from 'next/cache'

revalidateTag(`upstream-page-${upstreamPageId}`)

Linked page caches also follow the site's own publishes, so publishing, unpublishing or deleting a global block or a page a linked page links to refreshes it without any work on your side. See Caching and Revalidation.

Permissions

Linking, duplicating and resetting all need pages:update. Who may link which upstream page is decided by your findLinkable and LIST_UPSTREAM_PAGES. With the flag off, or with no upstreamPageSource, linking, rendering and duplicating are refused with FEATURE_DISABLED.

© ChaiBuilder. All rights reserved.

ChaiBuilderMade withChaiBuilder