WebRobot
App Builder · pages

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:

OptionMeaning
keyThe view's key. It is also its address: /v/<key>.
typeOne of the types below.
titleThe title on the page and in the menu. Translatable. In the menu, a view without a title shows its key.
rolesWho can open it. See Who can open a view.
navfalse keeps the view out of the menu. Default true.

Addresses

AddressWhat 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.
/loginThe sign-in page. See Sign-in and roles.
/admin/dataThe admins' data page. See Data.
/admin/pushThe 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 isThey can open a view when
signed inthe view has no roles, or they hold one of its roles
not signed inthe 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.

The header shows a menu to signed-in users. A view is in the menu when:

  • nav is not false;
  • its type is not report or run;
  • 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

TypeWhat it isRendered
pageLanding and content pages built from sectionsyes
new_runThe run form: start the main agentyes
reportWhere a finished run is shownthrough /r/<id>
runSame as reportthrough /r/<id>
historyThe user's runsyes
chatA conversation with an agentyes
table, cards, list, chartRows from a sourceyes
mapRows as markers on a mapyes
formCreate or edit a record of a collectionyes
bookingBook a time slotyes
dashboardOther views side by sideyes
tabsOther views as tabsyes
accountCredits, purchases, connected servicesyes
adminUsers, credits and runs, for adminsyes
approvalsRequests waiting for a person's decisionyes
instancesThe user's own agents made from a templateyes
reviewHuman review of resultsnot 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:

SectionRequiredWhat it shows
herotitleA 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.
stepsitemsNumbered items, each with title, text, badge. Optional title and intro.
cardsitemsThe same items as cards, without numbers. A badge that is a single emoji shows as an icon.
textcontentMarkdown, with an optional title.
notecontentMarkdown in a highlighted box.
htmlhtmlYour 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.
viewviewAnother view of the app, live, inside the page.
datasource, displayRows 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 /login is hidden from users who are already signed in.
  • A view section shows one level only: a page inside a page is left out.
  • A view section is left out when the reader cannot open that view. For visitors, history, account, report and run views are left out too.
  • A view section of type report or run shows 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? }
OptionMeaning
sourceagent:<key>: the agent that answers. Without it, the main agent.
examplesUp to 8 example questions, shown as chips.
placeholderThe 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 }
OptionMeaning
sourcecollection:<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.
datafields, filters, sort, limit, kpis, chart, groupBy, empty, path, actions, and display to override the type. See Data blocks.
columnsA short form of data.fields: a list of field keys.
exporttable, 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 optionDefaultMeaning
lat, lonlat, lonThe fields with the coordinates. Rows without valid numbers are left out.
titlenameThe field shown in bold in the popup.
popup—Up to 6 more fields in the popup.
tilesOpenStreetMapA tile URL template starting with https:// and containing {z}.
attribution© OpenStreetMap contributorsThe 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." }
OptionMeaning
collectionThe collection the form writes. Required.
fieldsThe collection's fields to show, in this order. Default: all.
edittrue: /v/<key>?id=<record id> opens that record to change it. The button then reads Save.
submit.labelThe button. Default Send (Save when editing).
submit.messageShown after saving. Default "Saved — thank you.".
submit.redirectA 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
OptionMeaning
collectionThe bookings. Must be ownedBy: user.
resourcesOptional: 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.
fieldsExtra fields of the collection asked when booking, e.g. notes. Texts are kept up to 2000 characters.
slotsThe opening rule, below.
slots optionDefaultMeaning
daysMonday to FridayDays of the week: 1 = Monday … 7 = Sunday.
from, to09:00, 18:00Opening hours, HH:MM. from must be before to.
minutes30Length of a slot, 5 to 480.
tzEurope/RomeThe time zone of the hours.
aheadDays14How many days ahead can be booked, 1 to 120.
minNoticeHours2The earliest slot is this many hours from now.
capacity1Bookings 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:

  1. 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.
  2. The user picks a time, fills the extra fields and confirms. Booking needs a signed-in user.
  3. The record gets start, end, date, resource (if any), status: booked, the user and bookedBy (their email). Two people clicking the same slot cannot both get it: the second gets that slot is no longer free.
  4. 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 children views below, one level (an admin child 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.

OptionMeaning
approvalsThe 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.

OptionMeaning
templateThe 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):

typeUsesWhat it does
callfield: a phone numberDials the number. Shown only when the number has at least 5 digits.
directionsfield: an address or a "lat,lng" positionOpens a route to it: Apple Maps on iPhone and iPad, Google Maps elsewhere.
sharefield: the text to shareOpens 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.
calendartitle, 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.