WebRobot
App Builder · pagine

Documentazione · App Builder

Viste e pagine

Che cos'è una vista

Una vista è una pagina dell'app. spec.views le elenca. Ogni vista ha una key, un type e opzioni che dipendono dal tipo.

views:
  - { key: home, type: page, nav: false, sections: [ … ] }
  - key: requests
    type: table
    title: { en: Requests, it: Richieste }
    source: collection:requests
    roles: [consultant, admin]

Opzioni comuni a tutte le viste:

OpzioneSignificato
keyLa chiave della vista. È anche il suo indirizzo: /v/<key>.
typeUno dei tipi elencati sotto.
titleIl titolo nella pagina e nel menu. Traducibile. Nel menu, una vista senza titolo mostra la sua chiave.
rolesChi può aprirla. Vedi Chi può aprire una vista.
navfalse tiene la vista fuori dal menu. Predefinito true.

Indirizzi

IndirizzoCosa apre
/La vista con chiave home, se il visitatore può aprirla. Altrimenti la prima vista del menu del visitatore; altrimenti la pagina di accesso.
/v/<key>La vista <key>.
/r/<run id>Un'esecuzione: l'avanzamento mentre l'agente lavora, poi il suo report. La aprono solo l'utente dell'esecuzione e gli amministratori.
/loginLa pagina di accesso. Vedi Accesso e ruoli.
/admin/dataLa pagina dei dati degli amministratori. Vedi Dati.
/admin/pushLa pagina delle notifiche push degli amministratori (quando l'app invia notifiche push). Vedi Messaggi.

Una chiave sconosciuta dà "not found".

Chi può aprire una vista

Il visitatorePuò aprire una vista quando
ha fatto l'accessola vista non ha roles, o lui ha uno dei suoi roles
non ha fatto l'accessola vista è in auth.anonymous.views, o auth.public è true, o auth.method è none

Un utente con accesso che non può aprire una vista riceve "not found". Un visitatore senza accesso viene mandato ad accedere, poi riportato alla vista.

Gli amministratori seguono la stessa regola: non scavalcano i roles. Aggiungi il ruolo amministratore alle viste che gli servono. Vedi Accesso e ruoli.

Alcuni tipi richiedono comunque un utente con accesso, qualunque siano le impostazioni: history, account e un form non aperto ai visitatori mandano il visitatore ad accedere. Avviare un'esecuzione, usare la chat e prenotare chiedono l'accesso nel momento in cui il visitatore agisce.

L'intestazione mostra un menu agli utenti con accesso. Una vista è nel menu quando:

  • nav non è false;
  • il suo tipo non è report o run;
  • l'utente può aprirla.

Il menu mantiene l'ordine di spec.views. Gli amministratori ricevono anche Data (quando l'app ha raccolte con proprietario shared, app o org) e Notifications (quando l'app invia notifiche push).

I visitatori senza accesso non vedono il menu: vedono header.links e il pulsante Sign in (o header.cta). Vedi Il manifest.

Imposta nav: false sulla pagina di benvenuto (home), sulle pagine a cui rimandi da altre pagine e sulle pagine mostrate solo dentro un'altra pagina.

Tipi di vista

TipoCos'èVisualizzata
pagePagine di benvenuto e di contenuto costruite con blocchisì
new_runIl modulo di esecuzione: avvia l'agente principalesì
reportDove viene mostrata un'esecuzione terminatatramite /r/<id>
runCome reporttramite /r/<id>
historyLe esecuzioni dell'utentesì
chatUna conversazione con un agentesì
table, cards, list, chartRighe da una sorgentesì
mapRighe come indicatori su una mappasì
formCrea o modifica un record di una raccoltasì
bookingPrenota una fascia orariasì
dashboardAltre viste affiancatesì
tabsAltre viste come schedesì
accountCrediti, acquisti, servizi collegatisì
adminUtenti, crediti ed esecuzioni, per gli amministratorisì
approvalsRichieste in attesa della decisione di una personasì
instancesGli agenti propri dell'utente creati da un modellosì
reviewRevisione umana dei risultatinon ancora: la pagina dice "This view is not rendered by the runtime yet (review)."

page

Una pagina mostra il content in Markdown (facoltativo), poi i suoi sections (blocchi) dall'alto in basso.

- 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 }

Tipi di blocco:

BloccoObbligatorioCosa mostra
herotitleUn titolo grande, un eyebrow facoltativo (una riga piccola sopra, eyebrowStyle: text, pill, pill-dot), text, actions (pulsanti, style: primary o ghost), note (una riga piccola sotto i pulsanti). layout: split mette il testo, o aside, in una colonna a destra; aside è una scheda in HTML, ripulita come un blocco html. band: true crea una fascia colorata a tutta larghezza. Le parole in grassetto nel titolo sono evidenziate.
stepsitemsElementi numerati, ognuno con title, text, badge. title e intro facoltativi.
cardsitemsGli stessi elementi come schede, senza numeri. Un badge composto da una sola emoji appare come icona.
textcontentMarkdown, con un title facoltativo.
notecontentMarkdown in un riquadro evidenziato.
htmlhtmlHTML tuo, ripulito secondo un elenco di elementi ammessi: niente script, form o iframe; link e immagini solo https:// o percorsi della stessa app; stile in linea limitato alle proprietà di layout e colore.
viewviewUn'altra vista dell'app, attiva, dentro la pagina.
datasource, displayRighe da una sorgente. Vedi Blocchi di dati.

Ogni blocco accetta un id facoltativo, l'ancora per link come #how.

Regole di una pagina:

  • Un pulsante dell'hero che punta a /login è nascosto agli utenti che hanno già fatto l'accesso.
  • Un blocco view mostra un solo livello: una pagina dentro una pagina viene esclusa.
  • Un blocco view viene escluso quando chi legge non può aprire quella vista. Per i visitatori sono escluse anche le viste history, account, report e run.
  • Un blocco view di tipo report o run mostra l'ultimo report terminato dell'utente, con un link per aprirlo, oppure "No report yet: start your first run.".

new_run

Il modulo di spec.inputForm. Inviarlo avvia l'agente principale dell'app e apre /r/<run id>. Il titolo è il title della vista, altrimenti inputForm.title. Avviare un'esecuzione richiede un utente con accesso; un visitatore che invia il modulo viene portato ad accedere. Vedi Dati per i tipi di campo e Agenti e automazione per cosa succede dopo.

report e run

Una vista report (o run) indica dove viene mostrata un'esecuzione terminata. Le esecuzioni si aprono a /r/<run id>, non a /v/<key>: aprire l'indirizzo proprio della vista porta alla home page. Lascia nav: false.

A /r/<run id> l'utente vede:

  • mentre l'agente lavora: "Running…" e "The agent is working. You can leave this page: the report stays here.";
  • quando fallisce: "Failed" e il motivo;
  • quando ha finito: il report, un pulsante Print / save PDF (a meno di printable: false) e i crediti addebitati.

La pagina usa il title e printable della prima vista report. Vedi Pagamenti e crediti per gli addebiti.

history

Le esecuzioni dell'utente con accesso, dalle più recenti: il titolo (o i valori del modulo), lo stato (Running…, Done, Failed) e la data, ognuna con un link a /r/<run id>. Quando non ce ne sono: "Nothing yet.".

chat

Una conversazione con un agente.

- 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? }
OpzioneSignificato
sourceagent:<key>: l'agente che risponde. Senza, l'agente principale.
examplesFino a 8 domande di esempio, mostrate come chip.
placeholderIl testo dentro l'input vuoto. Predefinito "Ask anything…".

Come funziona:

  • Inviare un messaggio richiede un utente con accesso. Un visitatore che scrive viene portato ad accedere.
  • Ogni messaggio avvia l'agente con la conversazione fin lì (gli ultimi 8 scambi) e il nuovo messaggio. La pagina controlla la risposta ogni 3 secondi. Un messaggio contiene al massimo 2000 caratteri.
  • La conversazione è conservata per browser: tornando alla pagina la si rivede.
  • Ogni messaggio costa il prezzo dell'agente (billing.costs["agent:<key>"]), tranne per gli amministratori. Vedi Pagamenti e crediti.
  • Al massimo 30 messaggi all'ora per utente.
  • Dove il browser lo supporta, un pulsante microfono detta il messaggio, e "Read the replies aloud" legge ad alta voce le risposte.
  • L'agente deve essere pubblicato: un agente con profilo inline risponde solo dopo la pubblicazione dell'app.

Lo schema accetta anche placement: floating (una bolla di chat su ogni pagina). Il runtime non la visualizza ancora.

table, cards, list, chart

Righe da una source, mostrate come tabella, schede, elenco o grafico. Funzionano come un blocco di dati:

- 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 }
OpzioneSignificato
sourcecollection:<name>, job:<key>, run (il predefinito) o catalog[:<category>]. collection:<name>.<list> è una forma breve di path: es. collection:signals.assets mostra ogni elemento di assets di ogni record.
datafields, filters, sort, limit, kpis, chart, groupBy, empty, path, actions, e display per sostituire il tipo. Vedi Blocchi di dati.
columnsUna forma breve di data.fields: un elenco di chiavi di campo.
exporttable, list, cards: un link Download CSV. Vedi Dati.
preview{rows, unlessPlan}: un'anteprima ridotta per gli utenti senza il piano. hideColumns è accettato ma non ancora applicato.

Una vista chart disegna sempre un grafico (data.chart: bar, line, pie, stacked; predefinito bar). Il primo campo dà le etichette, gli altri le serie.

Quali righe vede un utente segue le regole dei dati: i suoi record, quelli condivisi e quelli che il suo ruolo raggiunge. Vedi Dati. Quando non ci sono righe: data.empty, oppure "No data yet.".

Le opzioni di vista param e query sono accettate dallo schema ma il runtime non le usa ancora. Una source di vista agent:<key> non mostra righe: usala solo per chat.

map

Righe come indicatori su una mappa. Le righe seguono le stesse regole di una tabella.

- 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]
Opzione di mapPredefinitoSignificato
lat, lonlat, lonI campi con le coordinate. Le righe senza numeri validi vengono escluse.
titlenameIl campo mostrato in grassetto nel popup.
popup—Fino a 6 campi in più nel popup.
tilesOpenStreetMapUn modello di URL delle tile che inizia con https:// e contiene {z}.
attribution© OpenStreetMap contributorsLa riga di credito delle tile, fino a 200 caratteri.

Le tile predefinite di OpenStreetMap sono per un uso leggero. Un'app molto usata dovrebbe usare un proprio fornitore di tile. La mappa mostra al massimo 200 indicatori. Senza indicatori, mostra l'Italia.

form

Crea un record in una raccolta, o ne modifica uno. Non è coinvolto nessun agente; i trigger sulla raccolta scattano al salvataggio.

- 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." }
OpzioneSignificato
collectionLa raccolta che il modulo scrive. Obbligatoria.
fieldsI campi della raccolta da mostrare, in questo ordine. Predefinito: tutti.
edittrue: /v/<key>?id=<record id> apre quel record per modificarlo. Il pulsante allora dice Save.
submit.labelIl pulsante. Predefinito Send (Save in modifica).
submit.messageMostrato dopo il salvataggio. Predefinito "Saved — thank you.".
submit.redirectLa chiave di una vista da aprire dopo il salvataggio.

Chi può inviare quale modulo, e in quali raccolte, è in Dati. La validazione richiede che un modulo aperto ai visitatori scriva una raccolta ownedBy: org.

Quando si modifica un record che l'utente non può modificare, il modulo dice "Record not found.".

booking

L'utente sceglie un orario libero e lo prenota. Ogni prenotazione è un record proprio dell'utente 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
OpzioneSignificato
collectionLe prenotazioni. Deve essere ownedBy: user.
resourcesFacoltativo: collection:<name> di ciò che si prenota: persone, sale, tavoli. Deve essere ownedBy: app o shared. L'utente ne sceglie prima uno. Ognuno è elencato con il suo name, full_name, title o un campo simile, altrimenti con il primo campo di testo. I record con active: false vengono esclusi; ne sono elencati al massimo 100.
fieldsCampi aggiuntivi della raccolta chiesti al momento della prenotazione, es. note. I testi sono conservati fino a 2000 caratteri.
slotsLa regola di apertura, sotto.
Opzione di slotsPredefinitoSignificato
daysDa lunedì a venerdìGiorni della settimana: 1 = lunedì … 7 = domenica.
from, to09:00, 18:00Orario di apertura, HH:MM. from deve precedere to.
minutes30Durata di una fascia, da 5 a 480.
tzEurope/RomeIl fuso orario degli orari.
aheadDays14Con quanti giorni di anticipo si può prenotare, da 1 a 120.
minNoticeHours2La prima fascia disponibile è a questo numero di ore da adesso.
capacity1Prenotazioni per fascia (posti in una lezione), da 1 a 100.

Un record di risorsa può avere un proprio oggetto slots per restringere giorni e orari.

Cosa succede:

  1. La pagina mostra i prossimi giorni con fasce libere, nel fuso orario delle fasce. Una fascia è libera finché ha meno prenotazioni di capacity; le prenotazioni annullate non contano.
  2. L'utente sceglie un orario, compila i campi aggiuntivi e conferma. Prenotare richiede un utente con accesso.
  3. Il record riceve start, end, date, resource (se presente), status: booked, l'utente e bookedBy (la sua email). Due persone che cliccano sulla stessa fascia non possono ottenerla entrambe: la seconda riceve that slot is no longer free.
  4. La prenotazione è un evento dell'app: i trigger sulla raccolta scattano (avvisare il personale, ricordare il giorno prima).

Quando non c'è niente di libero: "No free times in the coming days.". Il runtime può annullare una prenotazione (una dell'utente, o una che un ruolo può modificare), il che libera la fascia, ma la vista di prenotazione non ha ancora un pulsante per annullare: mostra le prenotazioni in una tabella e lascia che un agente o un modulo gestisca gli annullamenti.

dashboard e tabs

Entrambe mostrano altre viste, elencate in children.

  • dashboard: le viste figlie affiancate. Un solo livello: una dashboard dentro una dashboard non viene mostrata.
  • tabs: una scheda per vista figlia; l'indirizzo ?tab=<key> apre una scheda. Per impostazione predefinita si apre la prima scheda.

Le viste figlie che chi legge non può aprire vengono escluse.

- key: overview
  type: dashboard
  title: { en: Overview, it: Panoramica }
  children: [kpis, latest, by_week]

account

I crediti dell'utente con accesso:

  • il saldo;
  • i pacchetti e i piani dell'app, con i pulsanti Buy e Subscribe quando l'app accetta pagamenti ("Payments are not enabled for this app yet." altrimenti; nell'anteprima della bozza i pagamenti sono sempre disattivati);
  • Connected services: le chiavi API che l'utente collega per gli strumenti dell'app (data.credentials). Le chiavi valide per tutta l'app (scope: org) sono mostrate solo agli amministratori;
  • i movimenti dei crediti.

La validazione richiede una vista account quando l'app dichiara credenziali con chiave API. Vedi Pagamenti e crediti.

admin

Per gli amministratori dell'app: tutti gli altri vedono "For the app's admins only.". Mostra:

  • gli utenti, dai più recenti, con data di registrazione, piani, saldo e un campo per aggiungere crediti;
  • le ultime 30 esecuzioni di tutti gli utenti;
  • le sue viste children sotto, un solo livello (una figlia admin viene saltata).

Ricorda di dare alla vista roles che includano il ruolo amministratore, oppure nessun ruolo.

approvals

Le richieste fatte dagli agenti che chi legge può decidere. Vedi Agenti e automazione per le approvazioni.

OpzioneSignificato
approvalsLe chiavi delle approvazioni da elencare. Predefinito: tutte quelle che chi legge può decidere.

Ogni richiesta in attesa mostra il tipo, il riepilogo, i dettagli, la data e la scadenza, con un campo per una nota e Approve / Reject. Sotto, fino a 20 richieste decise di recente. Quando non c'è niente in attesa: "No pending requests.". Un visitatore vede "Sign in to see the requests.".

Chi decide: il ruolo dell'approvazione, o gli amministratori dell'app. Una persona non decide mai la propria richiesta, tranne per le approvazioni con decidedBy: requester, che decide solo l'utente richiedente.

instances

Gli agenti propri dell'utente creati da un modello: crea, esegui ora, metti in pausa, riprendi, elimina, e l'ultimo risultato di ciascuno.

OpzioneSignificato
templateLa chiave del modello. Obbligatoria.

La pagina mostra il conteggio rispetto al massimo per utente del modello (predefinito 5), il costo per esecuzione e un modulo per crearne uno nuovo finché si è sotto il massimo. Un visitatore vede la descrizione del modello e un pulsante Sign in to create yours. Vedi Agenti e automazione.

Azioni sui record

Le righe di una tabella, di schede, di un elenco o di un blocco di dati possono avere fino a 4 pulsanti, impostati in data.actions (o actions su un blocco di dati):

typeUsaCosa fa
callfield: un numero di telefonoChiama il numero. Mostrato solo quando il numero ha almeno 5 cifre.
directionsfield: un indirizzo o una posizione "lat,lng"Apre un percorso verso di esso: Apple Maps su iPhone e iPad, Google Maps altrove.
sharefield: il testo da condividereApre il pannello di condivisione del sistema con il testo e il link della pagina. Dove non esiste, li copia e mostra "Copied". Senza field, il primo campo di testo della riga.
calendartitle, start, e facoltativi end, location (nomi di campo)Aggiunge un evento al calendario. Mostrato solo quando start è una data valida. Una data senza ora crea un evento di un giorno intero; senza end, l'evento dura un'ora.

label sostituisce il testo predefinito del pulsante (Call, Directions, Share, Add to calendar). I pulsanti sono nascosti in un'anteprima ridotta di un piano.

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 } }

Etichette in più lingue

Ogni testo di una vista (title, testi dei blocchi, etichette dei pulsanti, placeholder, examples, empty, testi di submit, etichette delle azioni) accetta una stringa semplice o una stringa per lingua. Vedi Il manifest.

Le etichette dei campi vengono dalla raccolta: una colonna, una riga di scheda o un campo di modulo senza etichetta propria usa la label del campo, e il valore di una select mostra l'etichetta della sua opzione nella lingua di chi legge.

Le parole proprie del runtime (Sign in, Start, Running…, Download CSV, No data yet…) esistono in inglese e in italiano; in ogni altra lingua compaiono in inglese.