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:
| Opzione | Significato |
|---|---|
key | La chiave della vista. È anche il suo indirizzo: /v/<key>. |
type | Uno dei tipi elencati sotto. |
title | Il titolo nella pagina e nel menu. Traducibile. Nel menu, una vista senza titolo mostra la sua chiave. |
roles | Chi può aprirla. Vedi Chi può aprire una vista. |
nav | false tiene la vista fuori dal menu. Predefinito true. |
Indirizzi
| Indirizzo | Cosa 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. |
/login | La pagina di accesso. Vedi Accesso e ruoli. |
/admin/data | La pagina dei dati degli amministratori. Vedi Dati. |
/admin/push | La 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 visitatore | Può aprire una vista quando |
|---|---|
| ha fatto l'accesso | la vista non ha roles, o lui ha uno dei suoi roles |
| non ha fatto l'accesso | la 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.
Menu e navigazione
L'intestazione mostra un menu agli utenti con accesso. Una vista è nel menu quando:
navnon èfalse;- il suo tipo non è
reportorun; - 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
| Tipo | Cos'è | Visualizzata |
|---|---|---|
page | Pagine di benvenuto e di contenuto costruite con blocchi | sì |
new_run | Il modulo di esecuzione: avvia l'agente principale | sì |
report | Dove viene mostrata un'esecuzione terminata | tramite /r/<id> |
run | Come report | tramite /r/<id> |
history | Le esecuzioni dell'utente | sì |
chat | Una conversazione con un agente | sì |
table, cards, list, chart | Righe da una sorgente | sì |
map | Righe come indicatori su una mappa | sì |
form | Crea o modifica un record di una raccolta | sì |
booking | Prenota una fascia oraria | sì |
dashboard | Altre viste affiancate | sì |
tabs | Altre viste come schede | sì |
account | Crediti, acquisti, servizi collegati | sì |
admin | Utenti, crediti ed esecuzioni, per gli amministratori | sì |
approvals | Richieste in attesa della decisione di una persona | sì |
instances | Gli agenti propri dell'utente creati da un modello | sì |
review | Revisione umana dei risultati | non 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:
| Blocco | Obbligatorio | Cosa mostra |
|---|---|---|
hero | title | Un 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. |
steps | items | Elementi numerati, ognuno con title, text, badge. title e intro facoltativi. |
cards | items | Gli stessi elementi come schede, senza numeri. Un badge composto da una sola emoji appare come icona. |
text | content | Markdown, con un title facoltativo. |
note | content | Markdown in un riquadro evidenziato. |
html | html | HTML 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. |
view | view | Un'altra vista dell'app, attiva, dentro la pagina. |
data | source, display | Righe 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
viewmostra un solo livello: una pagina dentro una pagina viene esclusa. - Un blocco
viewviene escluso quando chi legge non può aprire quella vista. Per i visitatori sono escluse anche le vistehistory,account,reporterun. - Un blocco
viewdi tiporeportorunmostra 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? }
| Opzione | Significato |
|---|---|
source | agent:<key>: l'agente che risponde. Senza, l'agente principale. |
examples | Fino a 8 domande di esempio, mostrate come chip. |
placeholder | Il 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 }
| Opzione | Significato |
|---|---|
source | collection:<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. |
data | fields, filters, sort, limit, kpis, chart, groupBy, empty, path, actions, e display per sostituire il tipo. Vedi Blocchi di dati. |
columns | Una forma breve di data.fields: un elenco di chiavi di campo. |
export | table, 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 map | Predefinito | Significato |
|---|---|---|
lat, lon | lat, lon | I campi con le coordinate. Le righe senza numeri validi vengono escluse. |
title | name | Il campo mostrato in grassetto nel popup. |
popup | — | Fino a 6 campi in più nel popup. |
tiles | OpenStreetMap | Un modello di URL delle tile che inizia con https:// e contiene {z}. |
attribution | © OpenStreetMap contributors | La 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." }
| Opzione | Significato |
|---|---|
collection | La raccolta che il modulo scrive. Obbligatoria. |
fields | I campi della raccolta da mostrare, in questo ordine. Predefinito: tutti. |
edit | true: /v/<key>?id=<record id> apre quel record per modificarlo. Il pulsante allora dice Save. |
submit.label | Il pulsante. Predefinito Send (Save in modifica). |
submit.message | Mostrato dopo il salvataggio. Predefinito "Saved — thank you.". |
submit.redirect | La 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
| Opzione | Significato |
|---|---|
collection | Le prenotazioni. Deve essere ownedBy: user. |
resources | Facoltativo: 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. |
fields | Campi aggiuntivi della raccolta chiesti al momento della prenotazione, es. note. I testi sono conservati fino a 2000 caratteri. |
slots | La regola di apertura, sotto. |
Opzione di slots | Predefinito | Significato |
|---|---|---|
days | Da lunedì a venerdì | Giorni della settimana: 1 = lunedì … 7 = domenica. |
from, to | 09:00, 18:00 | Orario di apertura, HH:MM. from deve precedere to. |
minutes | 30 | Durata di una fascia, da 5 a 480. |
tz | Europe/Rome | Il fuso orario degli orari. |
aheadDays | 14 | Con quanti giorni di anticipo si può prenotare, da 1 a 120. |
minNoticeHours | 2 | La prima fascia disponibile è a questo numero di ore da adesso. |
capacity | 1 | Prenotazioni 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:
- 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. - L'utente sceglie un orario, compila i campi aggiuntivi e conferma. Prenotare richiede un utente con accesso.
- Il record riceve
start,end,date,resource(se presente),status: booked, l'utente ebookedBy(la sua email). Due persone che cliccano sulla stessa fascia non possono ottenerla entrambe: la seconda ricevethat slot is no longer free. - 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
childrensotto, un solo livello (una figliaadminviene 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.
| Opzione | Significato |
|---|---|
approvals | Le 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.
| Opzione | Significato |
|---|---|
template | La 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):
type | Usa | Cosa fa |
|---|---|---|
call | field: un numero di telefono | Chiama il numero. Mostrato solo quando il numero ha almeno 5 cifre. |
directions | field: un indirizzo o una posizione "lat,lng" | Apre un percorso verso di esso: Apple Maps su iPhone e iPad, Google Maps altrove. |
share | field: il testo da condividere | Apre 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. |
calendar | title, 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.