Pages & Sites
Page Builder V3
Build visual pages with the three-pane V3 editor, component library, filter bars, Iris refinement, and React blocks.
Page Builder V3 is the visual Sites editor: a three-pane studio (library / canvas / settings) that stores a recursive JSON component tree (PBPageData, version: "3.0") on sites.Page.content.
Choose V3 when you want drag-and-drop layout, ready-made data widgets, and a page-level filter bar — with optional React blocks for custom behaviour. Prefer V4 when Iris should own a single React source file.
Editor anatomy
| Pane | Role |
|---|---|
| Component library | Layout, basic, media, interactive, charts, self-contained widgets, templates |
| Canvas | Recursive render of nested nodes; 16-column width grid |
| Settings | Presets, basic/advanced options, Tailwind classes, custom styles, data bindings |
| Iris refinement | Generate or refine the tree while preserving structure (when page has id/slug) |
Component catalogue
| Category | Types |
|---|---|
| Layout | container, card (only these may have children) |
| Basic | heading, paragraph, divider, spacer, html, reactBlock, code |
| Media | image, video, audio, youtube |
| Interactive | button, link, countdown |
| Charts | barChart, pieChart, tileChart, funnelChart, radarChart, treeChart, timeSeriesChart, scatterChart, bubbleChart, pictogramChart, proportionalAreaChart, splitBarChart, heatmapChart, alluvialChart, table |
| Data widgets | welcomeGreeting, taskSnippet, profileHeader, globalSearch, recentDocuments, registriesList, documentCabinet |
| Templates | heroSection, features |
| Filters | Page-level filter bar items that broadcast values to charts/tables/React blocks |
Layout rules
- Full width =
16, half =8, quarter =4 - Children of a row should sum to ≤ 16 unless wrapping is intended
- Config is flat; use dot-notation keys for nested chart/data options
- Accessibility and alt text belong in node settings, not only in design notes
Filter bars
Add a filter bar when several components should share the same user controls (date range, status, owner, category). At runtime, React blocks read filters via usePageBuilderFilter() and convert values with buildFilterQ() / normaliseFilterValue() into JQL q / filter objects. See Data hooks.
React blocks
reactBlock nodes compile JSX through the shared Page Builder runtime:
- Default-exported function component
- No imports — React hooks,
useJql, Formik/Yup, inputs, charts, and Iris widgets are injected - Can participate in page filters and record context (
useRecordContext) when the page is bound to an object tab
Use React blocks for forms, custom tables, and interactions the stock library cannot express. Use stock widgets when they already fit.
Configuration checklist
- Create a Sites page; set version 3, audience, slug, roles.
- Drop a top-level
containerorheroSection. - Add content, charts, tables, data widgets, and optional React blocks.
- Set widths, Tailwind classes, and data namespaces on each node.
- Add a filter bar if the page is a dashboard.
- Refine with Iris, then manually verify edge cases.
- Save, preview as each audience, pin to menu/home if needed.
Audiences
| Audience | URL pattern |
|---|---|
public | /<slug> |
authenticated | /sites/<slug> |
admin | /admin/<slug> |