Pages¶
Pages are the screens people use inside a Diagonal app.
A Page can be a dashboard, portal, detail view, form, report, checkout flow, admin tool, or any other interactive surface. Builders compose Pages from Blocks, connect them to Workflows, and give them inputs so each Page can render the right experience for the current user and route.
Core idea
A Page is a runtime world.
It has Blocks, Inputs, Runtime State, and optional reusable Components. Together, those pieces decide what appears on screen, what can change while the user interacts, and which Workflows run when the user takes action.
Anatomy of a Page¶
Every Page combines structure, data, and behavior.
| Piece | Purpose |
|---|---|
| Route | The URL where the Page is available. |
| Page workflow | The Workflow that serves the Page and controls access. |
| Render step | The workflow step that renders the Page. |
| Blocks | The tree of visual and interactive elements on the Page. |
| Inputs | Values passed into the Page runtime from the route, workflow, user context, or parent Component. |
| Runtime state | Live values that Blocks can read and update while the Page is open. |
| Components | Reusable Block trees that can be placed across multiple Pages. |
| Authorizer | Access rules for who can view or use the Page. |
When a user opens a Page, Diagonal runs the Page workflow, gathers the Page inputs, creates the runtime world, and renders the Block tree.
Runtime World¶
The runtime world is the live environment a Page gets when it renders.
Think of it as the Page's working memory. It knows which Blocks exist, what inputs were provided, what each Block's current values are, and how nested Components relate to the surrounding Page.
The runtime world includes:
| Runtime piece | What it holds |
|---|---|
| Blocks | The Page's Block definitions, arranged as a tree. |
| Input values | Values available when the Page starts, such as route-bound records or values passed into a Component. |
| Input schema | The expected shape of the inputs. |
| Block state | Current values for each Block's fields. |
| Parent context | The surrounding runtime world when a nested world needs to reference it. |
| Slot context | The runtime world that owns a reusable Component placement. |
This lets a Page behave like a small application instead of a static document. A form field can hold a current value. A modal can open and close. A data grid can track filters. A Component can receive inputs from the Page that uses it.
Blocks¶
Blocks are the building units of Pages.
Each Block has a type, a name, settings, optional children, and sometimes event handlers. Blocks are arranged in a tree under the Page root. Some Blocks render content, some collect input, some control layout, and some connect the Page to Resources or Workflows.
Common Block categories:
| Category | Examples | Use them for |
|---|---|---|
| Layout | Div, Span, Accordion, Tabs, Modal, Slideover, Popover, Tooltip, Collapsible | Structure the Page and control how content is grouped or revealed. |
| Content | Header, Text, Rich Text, Image, Video, Icon, Iframe, File Display, Content Display | Show text, media, embedded content, and formatted values. |
| Forms | Form, Text Input, Text Area, Select, Combobox, Checkbox, Radio, Date, Time, File Upload, Money, Phone, Address, Repeater | Collect information from users. |
| Data | Data Grid, Resource Grid, Resource Record Display, Resource Field Input, Calendar, Email Messages, Payment Methods | Display and edit business data from Resources and platform features. |
| Actions | Button, Link, Delete Resource Record, Create Resource Record Form, Update Resource Record Form | Let users submit forms, navigate, create records, update records, or trigger workflows. |
| Logic | If, If Else, Then, Else, Loop, Loop Item, Empty Loop State | Show different UI based on state or repeat UI for a list of values. |
| Visualization | KPI Card, Table, Bar Chart, Line Chart, Pie Chart | Present metrics, reports, and structured information. |
| Composition | Component, Slot Definition, Slot Instance | Reuse UI and let Components accept nested content. |
| Utility | Timer, Signal Debug | Support runtime behavior and debugging. |
Blocks can be simple or deeply interactive. A Header Block might only display a title. A Form Block might collect fields, validate input, and submit to a Page workflow. A Resource Grid might show records with filtering, selection, and actions.
Inputs¶
Inputs are values passed into the runtime world.
They are how a Page starts with context. For example, a customer detail Page might receive a customer record from the route. A dashboard might receive the signed-in user's account. A Component might receive a title, record ID, or display mode from the Page where it is used.
Inputs are useful for:
- Loading the right record for a route like
/customers/{customer}. - Passing user-specific context into a Page.
- Configuring reusable Components from the Page that uses them.
- Giving Page workflows and Blocks a shared starting point.
Inputs are separate from runtime state. Inputs describe what the Page receives. Runtime state describes what can change while the Page is open.
Runtime State¶
Runtime state is stored in signals.
A signal is a live value in the Page runtime. Blocks use signals for their current fields and stateful behavior. When a signal changes, the parts of the Page that depend on it can update.
Runtime state can represent:
- A form input's current value.
- Whether a modal, popover, slideover, or tooltip is open.
- A selected tab or expanded accordion item.
- A data grid filter, selected row, or page size.
- A Block field that another Block reads.
- A Component input value after it has been passed into the Component's runtime world.
This is what makes Pages reactive. The Page does not have to reload every time something changes. Blocks can update their own state, respond to other Blocks, and pass values into workflows when the user takes action.
Page Workflows¶
Every Page is backed by a Page workflow.
The Page workflow defines the route, HTTP method, authentication requirements, permissions, and render step. When the Page is opened, the workflow runs synchronously so the user can receive the rendered Page immediately.
Page workflows also connect Pages to behavior. Buttons, forms, and other interactive Blocks can call Page workflows to validate input, update Records, send messages, charge payments, redirect users, or return updated values to the Page.
Components¶
Components are reusable Block trees.
A Component is like its own small runtime world. It has its own Blocks, its own input fields, and its own internal state. A Page uses a Component through a Component Block, then passes values into that Component just like props.
Use Components when the same interface appears in more than one place:
- A customer summary card used on dashboards and detail Pages.
- A reusable billing panel.
- A branded page header.
- A record action menu.
- A multi-step form section.
Components keep Pages consistent and easier to maintain. Change the Component once, and every Page that uses it can receive the update.
Component Inputs¶
Components define inputs so each placement can customize them.
For example, a Customer Card Component might define inputs for customer_id, title, and show_actions. One Page can render it as a compact card, while another Page can render the same Component with actions enabled.
Inside the Component, those inputs become part of the Component's runtime world. The Component can use them to render content, control visibility, or run Page workflows from its own Blocks.
Dynamic Values¶
Pages can use dynamic values to connect Blocks, inputs, workflow output, records, and user context.
This is how a Block can display the current user's name, a route-bound record field, or a value from another Block. The detailed resolver model is covered separately, so this guide focuses on the Page concepts rather than resolver syntax.
How Pages Fit With The Rest Of Diagonal¶
Pages are where end users experience the app that builders create.
| Platform area | How it connects to Pages |
|---|---|
| Data Layer | Pages display, collect, and update Records from Resources. |
| Workflow System | Pages are served by Page workflows and trigger workflows from user actions. |
| Security | Page authorizers, Roles, Permissions, and Policies decide who can view and act. |
| Navigation | Menus link users between Pages. |
| Components | Shared UI patterns can be reused across Pages. |
Start with the Page your user needs to complete a job, then add the Blocks, inputs, runtime state, workflows, and permissions that make that job possible.