Skip to content
FrameworkJavaScript

Page block: links to sub-pages

An owning page block saves only data.pageId; its body, title, icon, and access live in your host. A page-link block and an inline <a data-blok-page-id="p1">Page</a> are non-owning references. Neither stores a title, icon, URL, or access verdict.

Use resolve for authorized metadata and subscribe to refresh it after a host change. The host publishes same-tab notifications after local edits and remote changes. null means missing, undefined stays neutral, and { access: 'none' } means denied. A denied page hides its title, shows a lock, and explains No access on click or Enter.

Use search to offer only accessible pages for @ and [[ insertion. Your host owns global search and backlink screens. Ordinary URL mentions remain URL-backed. Register Page and PageLink with the same PageConfig; only Page can call create for a new owning page.

For static HTML, pass blocksToHtml(data, { pageInfo, pageHref }). pageInfo must supply authorized metadata synchronously. Missing, denied, or unresolved pages never receive a pageHref URL.

href builds a title-free URL from the opaque ID. open handles ordinary clicks and Enter; modified clicks follow the browser link. Blok does not load or save the page body.

Import

TypeScript
import { Page } from '@bloklabs/core/tools';

Configuration

OptionTypeDefaultDescription
href(pageId: string) => stringundefined

Builds the page's URL from its id. Blok puts it on the link, so Cmd/Ctrl-click or middle click opens the page in a new tab. Without it the link has no URL. Unsafe schemes such as javascript: are dropped.

pageIdFromHref(href: string) => string | null | undefinedundefined

Turns a URL back into a page id, or returns null when the URL is not a page link. Blok passes an absolute URL. With it, pasting a page link offers Mention, which inserts an inline reference to the page instead of a plain link.

open(pageId: string, ctx: { event?: MouseEvent | KeyboardEvent }) => voidundefined

Opens the page. Blok calls it on a plain left click. Without it, a click follows href.

Enter also opens the page when the block is selected from the keyboard (Escape, then the arrow keys). Then ctx.event is that key press.

Blok also calls it once right after a user inserts a new page from the toolbox. Then ctx.event is empty. It is not called for a page inserted through the API, or when create throws.

resolve(pageId: string) => PageInfo | null | undefined | Promise<…>undefined

Returns authorized current page metadata. null means the page does not exist; { access: 'none' } hides the title and icon and shows No access; undefined leaves a neutral label. A returned title or icon is displayed but never saved in the page block.

The host must check permissions before returning metadata. subscribe triggers another lookup when access or metadata changes.

create(init: { pageId: string; document?: OutputData; title?: string; parentId?: string }) => void | { pageId: string } | Promise<…>undefined

Makes the page in your app. Blok calls it once per new page, with an id it minted. It is never called on load, paste, undo, redo or a collaborator's change, or in read-only mode.

When a user picks Page in the toolbox, Blok waits for it. The item shows a spinner, and the block appears once it resolves. Return { pageId } to use your backend's id instead of Blok's. If it throws, no block is inserted; show the error yourself. Closing the menu while it runs does not cancel the insert.

When your code inserts a page through the API without a pageId, the block appears at once with Blok's id. A different returned id is ignored with a warning, so pass your own pageId to insert instead. If it throws, the block shows "Page not found". Blok still asks resolve, so a page your app made after all shows up.

init.document, when present, is the new page's starting content. Store it as the page's document. "Database - Full page" sends one database block with fullPage: true. The database finishes its setup when the page opens.

With createFromMention, the @ menu calls it too. Then init.title is the typed text, and init.parentId is the page the user chose. No parentId means the page this editor shows. Blok mentions the new page and does not open it.

databasePagesbooleanfalse

Offers "Database - Full page" in the toolbox's Database section. It makes a sub-page that holds a new database and opens it. The link shows a table glyph until the page gets an icon.

Turn it on only when create stores document as the new page's content and the database tool is registered.

createFromMentionbooleanfalse

Offers a New page section in the @ menu. It has two items: a sub-page of the current page, and a page under one the user picks. Each makes a page titled with the typed text and mentions it.

Turn it on only when create stores title and parentId.

search(query: string) => Promise<readonly PageSearchResult[]>undefined

Offers accessible pages for inline @ and [[ references. Filter results by the current user before returning them; Blok does not own global search.

The @ menu opens as soon as "@" is typed and asks with an empty query. Answer it with recent pages. While a search runs, the menu shows a spinner and placeholder rows.

The Link to page section lists the results. Each row shows the icon, the title and path, the titles of the pages above it. status: 'draft' shows a Draft mark. Six rows show first, then a "more results" row expands the list.

With resolve, Blok checks each result and uses its title, icon, path and status. Nothing found shows only when no section has items.

subscribe(pageId: string, onChange: () => void) => (() => void) | voidundefined

Calls onChange when page metadata or access changes. Blok re-runs resolve and uses the returned function to stop listening.

preview(pageId: string) => OutputBlockData[] | null | undefined | Promise<…>undefined

Supplies authorized opening blocks for the hover preview. Blok requests them only for an accessible page.

Save Data

TypeScript
interface PageData {
  pageId: string;
  kind?: 'database';  // Set by "Database - Full page"
}
JSON
{
  "id": "pg001",
  "type": "page",
  "data": { "pageId": "p1" }
}

Usage Example

TypeScript
import { Blok } from '@bloklabs/core';
import { Page, PageLink } from '@bloklabs/core/tools';
import { blocksToHtml } from '@bloklabs/core/view';

const pageUrl = (pageId) => `/pages/${pageId}`;
const pageConfig = {
  href: pageUrl,
  open: (pageId) => router.push(pageUrl(pageId)),
  resolve: (pageId) => myApi.getAuthorizedPageInfo(pageId),
  search: (query) => myApi.searchAccessiblePages(query),
  subscribe: (pageId, onChange) => myApi.subscribePage(pageId, onChange),
};

const editor = new Blok({
  holder: 'editor',
  tools: {
    page: {
      class: Page,
      config: {
        ...pageConfig,
        // Return { pageId } to use your backend's id instead of Blok's.
        create: async ({ pageId }) => ({ pageId: (await myApi.createPage(pageId)).id }),
      },
    },
    'page-link': { class: PageLink, config: pageConfig },
  },
});

const authorizedPageInfo = myApi.getAuthorizedPageInfoSnapshot();
const html = blocksToHtml(savedData, {
  pageInfo: (pageId) => authorizedPageInfo.get(pageId),
  pageHref: pageUrl,
});