Documentation · App Builder
Views
What a view is
A view is one page of the app. spec.views lists them. Each view has a key, a type and options that depend on
the type.
views:
- { key: home, type: page, nav: false, sections: [ … ] }
- key: requests
type: table
title: { en: Requests, it: Richieste }
source: collection:requests
roles: [consultant, admin]
Options every view has:
| Option | Meaning |
|---|---|
key | The view's key. It is also its address: /v/<key>. |
type | One of the types below. |
title | The title on the page and in the menu. Translatable. In the menu, a view without a title shows its key. |
roles | Who can open it. See Who can open a view. |
nav | false keeps the view out of the menu. Default true. |
Addresses
| Address | What it opens |
|---|---|
/ | The view with key home, if the visitor can open it. Otherwise the first view of the visitor's menu; otherwise the sign-in page. |
/v/<key> | The view <key>. |
/r/<run id> | One run: progress while the agent works, then its report. Only the run's user and the admins open it. |
/login | The sign-in page. See Sign-in and roles. |
/admin/data | The admins' data page. See Data. |
/admin/push | The admins' push notifications page (when the app sends push notifications). See Messaging. |
An unknown key gives "not found".
Who can open a view
| The visitor is | They can open a view when |
|---|---|
| signed in | the view has no roles, or they hold one of its roles |
| not signed in | the view is in auth.anonymous.views, or auth.public is true, or auth.method is none |
A signed-in user who cannot open a view gets "not found". A visitor who is not signed in is sent to sign in, then back to the view.
Admins follow the same rule: they do not skip roles. Add the admin role to the views they need. See
Sign-in and roles.
Some types also need a signed-in user, whatever the settings: history, account, and a form that is not open to
visitors send a visitor to sign in. Starting a run, chatting and booking ask for sign-in when the visitor acts.
Menu and navigation
The header shows a menu to signed-in users. A view is in the menu when:
navis notfalse;- its type is not
reportorrun; - the user can open it.
The menu keeps the order of spec.views. Admins also get Data (when the app has collections owned by shared,
app or org) and Notifications (when the app sends push notifications).
Visitors who are not signed in do not see the menu: they see header.links and the Sign in button (or
header.cta). See The manifest.
Set nav: false on the landing page (home), on pages you link to from other pages, and on pages shown only
inside another page.
View types
| Type | What it is | Rendered |
|---|---|---|
page | Landing and content pages built from sections | yes |
new_run | The run form: start the main agent | yes |
report | Where a finished run is shown | through /r/<id> |
run | Same as report | through /r/<id> |
history | The user's runs | yes |
chat | A conversation with an agent | yes |
table, cards, list, chart | Rows from a source | yes |
map | Rows as markers on a map | yes |
form | Create or edit a record of a collection | yes |
booking | Book a time slot | yes |
dashboard | Other views side by side | yes |
tabs | Other views as tabs | yes |
account | Credits, purchases, connected services | yes |
admin | Users, credits and runs, for admins | yes |
approvals | Requests waiting for a person's decision | yes |
instances | The user's own agents made from a template | yes |
review | Human review of results | not yet: the page says "This view is not rendered by the runtime yet (review)." |
page
A page shows Markdown content (optional), then its sections from top to bottom.
- key: home
type: page
nav: false
sections:
- type: hero
eyebrow: { en: For property agents, it: Per agenti immobiliari }
eyebrowStyle: pill
title: { en: "Valuations in **minutes**", it: "Valutazioni in **minuti**" }
text: { en: Pick the area and the property. An agent writes the sheet., it: Scegli zona e immobile. Un agente scrive la scheda. }
actions:
- { label: { en: Start free, it: Inizia gratis }, href: /login }
- { label: { en: How it works, it: Come funziona }, href: "#how", style: ghost }
- type: steps
id: how
title: { en: How it works, it: Come funziona }
items:
- { title: { en: Choose, it: Scegli }, text: { en: The area and the property., it: Zona e immobile. } }
- { title: { en: Wait, it: Attendi }, text: { en: The agent works for a minute., it: L'agente lavora un minuto. } }
- { type: view, view: new }
Section types:
| Section | Required | What it shows |
|---|---|---|
hero | title | A large title, optional eyebrow (small line above, eyebrowStyle: text, pill, pill-dot), text, actions (buttons, style: primary or ghost), note (small line under the buttons). layout: split puts the text, or aside, in a right column; aside is a card in HTML, cleaned like an html section. band: true makes a full-width tinted band. Bold words in the title are highlighted. |
steps | items | Numbered items, each with title, text, badge. Optional title and intro. |
cards | items | The same items as cards, without numbers. A badge that is a single emoji shows as an icon. |
text | content | Markdown, with an optional title. |
note | content | Markdown in a highlighted box. |
html | html | Your own HTML, cleaned against an allow-list: no script, form or iframe; links and images only https:// or same-app paths; inline style limited to layout and colour properties. |
view | view | Another view of the app, live, inside the page. |
data | source, display | Rows from a source. See Data blocks. |
Every section takes an optional id, the anchor for links like #how.
Rules of a page:
- A hero button that points to
/loginis hidden from users who are already signed in. - A
viewsection shows one level only: a page inside a page is left out. - A
viewsection is left out when the reader cannot open that view. For visitors,history,account,reportandrunviews are left out too. - A
viewsection of typereportorrunshows the user's latest finished report, with a link to open it, or "No report yet: start your first run.".
new_run
The form of spec.inputForm. Sending it starts the app's main agent and opens /r/<run id>. The title is the view's
title, else inputForm.title. Starting a run needs a signed-in user; a visitor who sends the form is taken to sign
in. See Data for the field types and Agents and automation for what happens next.
report and run
A report view (or run) names where a finished run is shown. Runs open at /r/<run id>, not at /v/<key>: opening
the view's own address goes to the home page. Keep nav: false.
At /r/<run id> the user sees:
- while the agent works: "Running…" and "The agent is working. You can leave this page: the report stays here.";
- when it fails: "Failed" and the reason;
- when it is done: the report, a Print / save PDF button (unless
printable: false), and the credits charged.
The page uses the title and printable of the first report view. See Billing for charges.
history
The signed-in user's runs, newest first: the title (or the form values), the status (Running…, Done, Failed) and the
date, each linking to /r/<run id>. When there are none: "Nothing yet.".
chat
A conversation with an agent.
- key: ask
type: chat
title: { en: Ask the guide, it: Chiedi alla guida }
source: agent:guide
placeholder: { en: Ask about a neighbourhood…, it: Chiedi di un quartiere… }
examples:
- { en: Where do families live?, it: Dove vivono le famiglie? }
| Option | Meaning |
|---|---|
source | agent:<key>: the agent that answers. Without it, the main agent. |
examples | Up to 8 example questions, shown as chips. |
placeholder | The text inside the empty input. Default "Ask anything…". |
How it works:
- Sending a message needs a signed-in user. A visitor who writes is taken to sign in.
- Each message starts the agent with the conversation so far (the last 8 exchanges) and the new message. The page checks for the reply every 3 seconds. A message holds at most 2000 characters.
- The conversation is kept per browser: coming back to the page shows it again.
- Each message costs the agent's price (
billing.costs["agent:<key>"]), except for admins. See Billing. - At most 30 messages per hour per user.
- Where the browser supports it, a microphone button dictates the message, and "Read the replies aloud" reads the answers.
- The agent must be published: an agent with an inline profile answers only after the app is published.
The schema also accepts placement: floating (a chat bubble on every page). The runtime does not render it yet.
table, cards, list, chart
Rows from a source, shown as a table, cards, a list or a chart. They work like a data block:
- key: listings
type: cards
title: { en: Listings, it: Annunci }
source: collection:listings
export: true
data:
fields:
- { key: title }
- { key: price, format: money }
- { key: phone }
filters: [ { field: status, op: "=", value: published } ]
sort: { field: price, dir: asc }
limit: 50
actions:
- { type: call, field: phone }
| Option | Meaning |
|---|---|
source | collection:<name>, job:<key>, run (the default) or catalog[:<category>]. collection:<name>.<list> is short for a path: e.g. collection:signals.assets shows each item of each record's assets. |
data | fields, filters, sort, limit, kpis, chart, groupBy, empty, path, actions, and display to override the type. See Data blocks. |
columns | A short form of data.fields: a list of field keys. |
export | table, list, cards: a Download CSV link. See Data. |
preview | {rows, unlessPlan}: a teaser for users without the plan. hideColumns is accepted but not applied yet. |
A chart view always draws a chart (data.chart: bar, line, pie, stacked; default bar). The first field
gives the labels, the others the series.
Which rows a user sees follows the data rules: their own records, shared ones, and those their role reaches. See
Data. When there are no rows: data.empty, or "No data yet.".
The view options param and query are accepted by the schema but not used by the runtime yet. A view source of
agent:<key> shows no rows: use it for chat only.
map
Rows as markers on a map. The rows follow the same rules as a table.
- key: shops
type: map
title: { en: Our shops, it: I nostri negozi }
source: collection:shops
map:
lat: latitude
lon: longitude
title: name
popup: [address, opening_hours]
map option | Default | Meaning |
|---|---|---|
lat, lon | lat, lon | The fields with the coordinates. Rows without valid numbers are left out. |
title | name | The field shown in bold in the popup. |
popup | — | Up to 6 more fields in the popup. |
tiles | OpenStreetMap | A tile URL template starting with https:// and containing {z}. |
attribution | © OpenStreetMap contributors | The credit line of the tiles, up to 200 characters. |
The default OpenStreetMap tiles are for light use. A busy app should use its own tile provider. The map shows at most 200 markers. With no markers, it shows Italy.
form
Creates a record in a collection, or changes one. No agent is involved; triggers on the collection fire on save.
- key: contact
type: form
title: { en: Contact us, it: Contattaci }
collection: contact_requests # ownedBy: org
fields: [name, email, message]
submit:
label: { en: Send, it: Invia }
message: { en: "Thanks, we will reply soon.", it: "Grazie, ti risponderemo presto." }
| Option | Meaning |
|---|---|
collection | The collection the form writes. Required. |
fields | The collection's fields to show, in this order. Default: all. |
edit | true: /v/<key>?id=<record id> opens that record to change it. The button then reads Save. |
submit.label | The button. Default Send (Save when editing). |
submit.message | Shown after saving. Default "Saved — thank you.". |
submit.redirect | A view key to open after saving. |
Who may send which form, and into which collections, is in Data.
Validation requires that a form open to visitors writes a collection ownedBy: org.
When editing a record the user may not change, the form says "Record not found.".
booking
The user picks a free time and books it. Each booking is the user's own record in collection.
- key: book
type: booking
title: { en: Book a visit, it: Prenota una visita }
collection: bookings # ownedBy: user
resources: collection:doctors # ownedBy: shared or app
fields: [notes, phone]
slots:
days: [1, 2, 3, 4, 5]
from: "09:00"
to: "18:00"
minutes: 30
tz: Europe/Rome
aheadDays: 14
minNoticeHours: 2
capacity: 1
| Option | Meaning |
|---|---|
collection | The bookings. Must be ownedBy: user. |
resources | Optional: collection:<name> of what is booked — people, rooms, tables. Must be ownedBy: app or shared. The user picks one first. Each is listed by its name, full_name, title or a similar field, else its first text field. Records with active: false are left out; at most 100 are listed. |
fields | Extra fields of the collection asked when booking, e.g. notes. Texts are kept up to 2000 characters. |
slots | The opening rule, below. |
slots option | Default | Meaning |
|---|---|---|
days | Monday to Friday | Days of the week: 1 = Monday … 7 = Sunday. |
from, to | 09:00, 18:00 | Opening hours, HH:MM. from must be before to. |
minutes | 30 | Length of a slot, 5 to 480. |
tz | Europe/Rome | The time zone of the hours. |
aheadDays | 14 | How many days ahead can be booked, 1 to 120. |
minNoticeHours | 2 | The earliest slot is this many hours from now. |
capacity | 1 | Bookings per slot (seats in a class), 1 to 100. |
A resource record may carry its own slots object to narrow its days and hours.
What happens:
- The page shows the next days with free slots, in the slots' time zone. A slot is free while it has fewer bookings
than
capacity; cancelled bookings do not count. - The user picks a time, fills the extra fields and confirms. Booking needs a signed-in user.
- The record gets
start,end,date,resource(if any),status: booked, the user andbookedBy(their email). Two people clicking the same slot cannot both get it: the second getsthat slot is no longer free. - The booking is an app event: triggers on the collection fire (notify the staff, remind the day before).
When nothing is free: "No free times in the coming days.". The runtime can cancel a booking (the user's own, or one a role may change), which frees the slot, but the booking view has no cancel button yet: show bookings in a table and let an agent or a form handle cancellations.
dashboard and tabs
Both show other views, listed in children.
dashboard: the child views side by side. One level: a dashboard inside a dashboard is not shown.tabs: one tab per child view; the address?tab=<key>opens a tab. The first tab opens by default.
Children the reader cannot open are left out.
- key: overview
type: dashboard
title: { en: Overview, it: Panoramica }
children: [kpis, latest, by_week]
account
The signed-in user's credits:
- the balance;
- the app's packs and plans, with Buy and Subscribe buttons when the app takes payments ("Payments are not enabled for this app yet." otherwise; payments are always off in the draft preview);
- Connected services: the API keys the user connects for the app's tools (
data.credentials). Keys scoped to the app (scope: org) are shown to admins only; - the movements of credits.
Validation requires an account view when the app declares API-key credentials. See Billing.
admin
For the app's admins: everyone else sees "For the app's admins only.". It shows:
- the users, newest first, with sign-up date, plans, balance, and a field to add credits;
- the latest 30 runs of all users;
- its
childrenviews below, one level (anadminchild is skipped).
Remember to give the view roles that include the admin role, or no role at all.
approvals
The requests agents made that the reader can decide. See Agents and automation for approvals.
| Option | Meaning |
|---|---|
approvals | The approval keys to list. Default: all the reader can decide. |
Each pending request shows its type, the summary, the details, the date and the due time, with a note field and Approve / Reject. Below, up to 20 recently decided requests. When nothing is pending: "No pending requests.". A visitor sees "Sign in to see the requests.".
Who decides: the approval's role, or the app's admins. A person never decides their own request, except for
approvals with decidedBy: requester, which only the requesting user decides.
instances
The user's own agents made from a template: create, run now, pause, resume, delete, and the latest result of each.
| Option | Meaning |
|---|---|
template | The template key. Required. |
The page shows the count against the template's maximum per user (default 5), the cost per run, and a form to create a new one while under the maximum. A visitor sees the template's description and a Sign in to create yours button. See Agents and automation.
Record actions
Rows in a table, cards, list or data block can carry up to 4 buttons, set in data.actions (or actions on a data
section):
type | Uses | What it does |
|---|---|---|
call | field: a phone number | Dials the number. Shown only when the number has at least 5 digits. |
directions | field: an address or a "lat,lng" position | Opens a route to it: Apple Maps on iPhone and iPad, Google Maps elsewhere. |
share | field: the text to share | Opens the system share sheet with the text and the page link. Where there is none, copies them and shows "Copied". Without field, the first text field of the row. |
calendar | title, start, and optional end, location (field names) | Adds an event to the calendar. Shown only when start is a valid date. A date without time makes an all-day event; without end, the event lasts one hour. |
label replaces the default button text (Call, Directions, Share, Add to calendar). Buttons are hidden in a plan
teaser.
actions:
- { type: call, field: phone }
- { type: directions, field: address }
- { type: calendar, title: service, start: start, end: end, location: address, label: { en: Save the date, it: Salva in agenda } }
Labels in several languages
Every text of a view — title, section texts, button labels, placeholder, examples, empty, submit texts,
action labels — takes a plain string or one string per language. See The manifest.
Field labels come from the collection: a column, card line or form field without its own label uses the field's
label, and a select value shows its option's label in the reader's language.
The runtime's own words (Sign in, Start, Running…, Download CSV, No data yet…) exist in English and Italian; in any other language they appear in English.