A block is a piece of a page: a paragraph of text, a table, cards, an image carousel or a button. A page is assembled from blocks like from parts. The agent places the needed blocks in order, and the portal renders them in a single style.
What a block is
Every block has an id (so it can be referenced), a type (what kind of block it is), a title (optional), a width, content settings and, when needed, button actions. Width is measured on a 12-part grid: 12 takes the full page width, 6 a half, 4 a third. That way two or three blocks can sit side by side.
Blocks are not edited on the page itself: a block can only be changed through the agent. But every block has a readable type name — if the agent placed something unfamiliar, the reader sees no error, but the note This block is managed by the agent.
All 28 block types
The types are grouped into six families. Below is what each of them does.
| Type | Family | What it is |
markdown | text and structure | the main text: paragraphs, lists, emphasis, links, mermaid diagrams, pictures and files right inside the text |
heading | text and structure | a subheading inside the page, with a level from 1 to 4 |
hero | text and structure | a large banner heading with a subtitle and buttons, optionally with an image |
callout | text and structure | a highlighted note block: a hint, a warning, an important remark |
quote | text and structure | a quotation with the author and their role |
list | text and structure | a list: bulleted, numbered or with check marks |
icon-grid | text and structure | a grid of identical cards: icon, title, short text |
divider | text and structure | a divider or an empty gap between parts of a page |
tabs | text and structure | several tabs with different content, one open |
accordion | text and structure | collapsed “accordion” sections: the one you need unfolds |
timeline | text and structure | a feed of dated events on a vertical line |
stepper | text and structure | a step-by-step instruction with numbered circles |
image | media | a single image with a caption, optionally a link |
gallery | media | a set of images in a grid, with a large view |
slider | media | a slide carousel, each slide with its own buttons |
video | media | video from your server or an external service |
files | media | a list of downloadable files with sizes and notes |
embed | media | an embedded third-party block: a map, a form, an external service |
cards | navigation | link cards pointing to other portal pages |
table | data | a table with columns and rows, with a sticky header; it fits the page width — cell text wraps, and sideways scrolling remains only where nothing else works; cells can carry icons, colours and action buttons, and a row its own colour |
people | data | staff cards: photo, name, role, contacts |
kpi | data | tiles with the key numbers: a measure, a unit, a change |
feed | data | a feed of entries: date, title, short text, picture |
viz | data | a visualisation from your database: 33 kinds — an indicator, a gauge, a table, a chart, a map and others |
actions | actions | buttons only, with no content of their own |
chart | dynamic | a chart whose data is computed by a script |
script | dynamic | ready text assembled by a script |
form | dynamic | a form with fields and a submit button |
Which blocks can compute data
Data reaches a page by one of two paths. The first is a calculating script: seven types can take their content not from text but from a program written in Python. This means the numbers on the page are always fresh — from your system, not typed in by hand. The data-computing types are: list, table, kpi (number tiles), feed, chart, script (ready text) and form.
The second path is a ready-made visualisation: it takes data from a database or another source by a query description, with no program at all, and shows it in one of 33 ways — from a single number to a map of regions (see the Data Sources & Visualisations section).
Diagrams, pictures and files in the text
A block of text can carry a diagram: the markup is written inside three backticks with the word mermaid, and the portal draws it as a diagram instead of a code listing. The drawing library is downloaded only when the first diagram appears; the diagram follows the portal’s light and dark theme and redraws when the reader switches. Markup with a mistake shows its own source text — the rest of the block renders as usual. Diagrams work on the public site as well.
A link to a file from the page’s own folder (assets/…) shows a picture in place, and downloads anything else as an attachment without taking the reader off the page. Everything else in the text stays exactly as written: links to other sites, anchors inside the page, links to other portal pages and examples inside code blocks. Safe headers ride on every response, and the public site has its own address for the same files.
Icons, colours and buttons in tables
A table cell can carry an icon by name, a text colour and a background colour; a whole row can carry its own colour and background. The background is drawn as a soft fill, so any colour stays readable in both themes, and the precedence runs cell → row → zebra stripes: a marked row is not striped. An icon the portal does not know or a colour written wrongly is simply not drawn — the cell renders as ordinary text.
A cell can carry the same buttons as a block: a link, a step inside the portal, a script, a request to the agent or a form. Buttons that ask the agent are hidden without a connected agent and on the public site; the rest work everywhere. More about buttons is in the Buttons & Actions section.
What all blocks share
- Title — optional. When present, the block’s name with its icon appears above the content.
- Width — from 1 to 12 parts of the page. By default a block takes the full width.
- Action buttons — up to three per block. Each can be a link, a step inside the portal, a script run, a request to the agent, a one-click button or a form button (see Buttons & Actions).
- The freshness footer — blocks with computed data and visualisations show at the bottom when the data was updated, plus a refresh button.
A block with no title and no buttons renders “bare” — without an extra frame around it. That way the text on a page reads like a normal article rather than a set of boxes.
Formatting inside lists, tables and cards
The main text of a page can carry bold and italic words, code spans and links. The same works in the smallest places: in a list item, in a table cell and in card text. That is handy when the main thing in a report row needs stressing or a link has to come straight out of a cell — with no extra paragraph.
A link inside a card fires by itself: clicking follows the link instead of opening the whole card. And the formatting stays on one line — no list or separate paragraph appears inside a cell or a card, otherwise the table would fall apart. Tables themselves fit the page width: the text in cells wraps, and reading a row needs no sideways scrolling.
When a block breaks
One unlucky block never takes the whole page down. An unknown type renders as a calm note naming the type: This block is managed by the agent. And when a block fails to render because of an error, its place shows Block could not be rendered with a Copy details button — that note can be handed to the agent to fix. All the other blocks on the page keep rendering as usual.
Where to see examples
All 28 types are collected in a demonstration portal: it has the carousel, the tabs, the charts and the forms — live examples show how a block behaves in practice. Ask the agent to open this demonstration set when you want to see a block type before putting it on your own page.
Next: how block buttons behave — in the Buttons & Actions section; where live numbers come from — in the Data Sources & Visualisations section; how data is computed for blocks — in Dynamic Python Blocks; how blocks are checked — in Page Validation.