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
import { Page } from '@bloklabs/core/tools';Configuration
| Option | Type | Default | Description |
|---|---|---|---|
href | (pageId: string) => string | undefined | 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 |
pageIdFromHref | (href: string) => string | null | undefined | undefined | Turns a URL back into a page id, or returns |
open | (pageId: string, ctx: { event?: MouseEvent | KeyboardEvent }) => void | undefined | Opens the page. Blok calls it on a plain left click. Without it, a click follows Enter also opens the page when the block is selected from the keyboard (Escape, then the arrow keys). Then Blok also calls it once right after a user inserts a new page from the toolbox. Then |
resolve | (pageId: string) => PageInfo | null | undefined | Promise<…> | undefined | Returns authorized current page metadata. The host must check permissions before returning metadata. |
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 When your code inserts a page through the API without a
With |
databasePages | boolean | false | 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 |
createFromMention | boolean | false | Offers a New page section in the Turn it on only when |
search | (query: string) => Promise<readonly PageSearchResult[]> | undefined | Offers accessible pages for inline The The Link to page section lists the results. Each row shows the icon, the title and With |
subscribe | (pageId: string, onChange: () => void) => (() => void) | void | undefined | Calls |
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
interface PageData {
pageId: string;
kind?: 'database'; // Set by "Database - Full page"
}{
"id": "pg001",
"type": "page",
"data": { "pageId": "p1" }
}Usage Example
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,
});