I widget

Tutto ciò che si vede in una schermata è un widget. La palette Widget, a sinistra del canvas, porta 32 widget di serie — da questa pagina esci sapendo a che cosa serve ognuno, e con i principali spiegati in dettaglio. Se l'app ha widget programmati da te, appaiono nella stessa palette, nella sezione Custom.

#Il catalogo, per categoria

#Campi di modulo

Tutti si collegano a un campo di un datastore di record (sezione Collegamento ai dati) ed entrano nella validazione — vedi i moduli.

Widget	A che cosa serve
Casella di testo	Testo di una riga. Ha Maschera, modalità Password (nascondi il testo) e placeholder.
Area di testo	Testo lungo, multiriga — note, descrizioni.
Numero	Valori numerici.
Sì/No	Un interruttore booleano.
Dropdown	Scelta di opzioni: Elenco fisso, Enum del modello o Datastore; con Ricercabile, Selezione multipla e modalità Albero (gerarchico).
Data	Data, Data e ora o solo Ora (il campo Tipo decide).
Colore	Scelta di un colore.
File	Upload per trascinamento e/o pulsante, con anteprima, limite di dimensione e scelta dell'archiviazione. Il limite non supera mai il File massimo (MB) delle impostazioni della piattaforma, fino a 100 MB. Con Nel campo stesso (base64), il file va dentro la richiesta e il limite è di circa 3 MB. Ogni account invia fino a 300 file e 3 GB all'ora (e ogni indirizzo fino a 20 GB); oltre, il widget dice che sono stati inviati troppi file e chiede di riprovare più tardi.

Ogni campo con un valore mostra a destra una × discreta che lo cancella — in una Lista usata come filtro è il modo di tornare a "tutti" senza scegliere nulla. La Lista semplice apre le opzioni sotto il campo; con Ricercabile apre una casella di ricerca e la lista si accorcia scrivendo; con Selezione multipla ogni opzione si attiva e disattiva con un segno di spunta.

Il Dropdown mostra 10 opzioni alla volta. La proprietà Opzioni visibili, in Comportamento, cambia questo numero (0 le mostra tutte). Quando ci sono più opzioni di questo numero, l'elenco ha una casella di ricerca, anche senza Ricercabile, e un piè di pagina con il totale, per esempio «10 di 245 · scrivi per cercare». La ricerca cerca in tutte le opzioni e ignora accenti e maiuscole. In una Selezione multipla, le opzioni già scelte compaiono per prime nell'elenco, e il campo mostra le prime due seguite da «+N».

Nel piè di pagina, la lente (Vedi tutto) apre una finestra con tutte le opzioni in una tabella, con ricerca e 50 righe per pagina. Con l'Origine delle opzioni su Datastore, le Colonne della finestra di scelta aggiungono campi accanto all'etichetta (per esempio, il codice fiscale, per distinguere due clienti con lo stesso nome), e la finestra ha una barra dei filtri su quei campi. In una scelta singola, fare clic su una riga sceglie l'opzione. In una Selezione multipla, ogni riga ha una casella, Seleziona tutti seleziona i risultati di tutte le pagine, e solo Applica salva la scelta; Annulla non cambia nulla. La finestra mantiene sempre la stessa dimensione, con pochi o molti risultati.

In KeplinGo, il Dropdown apre un foglio con la stessa regola: 10 opzioni, ricerca e il piè di pagina con il totale. Vedi tutto mostra tutte le opzioni nello stesso foglio, con i campi delle Colonne della finestra di scelta sotto ogni etichetta, e la Selezione multipla salva solo con Applica.

Con il Caricamento del datastore del Dropdown su Una pagina per volta, solo la prima pagina arriva alla schermata. La ricerca interroga allora il server, il totale nel piè di pagina è quello del server, la finestra di scelta chiede ogni pagina al server, e il campo recupera dal server il nome di un valore salvato che la prima pagina non ha portato. In questa modalità, la ricerca cerca nell'etichetta (che deve essere un campo di testo), maiuscole e accenti contano come li conta il database, e Seleziona tutti non compare, perché obbligherebbe a caricare tutti i record.

#Azioni e navigazione

Widget	A che cosa serve
Pulsante	L'azione classica. Mostra: Icona + Testo, Solo icona o Solo testo; l'Azione al clic naviga, apre un modale o esegue codice.
Pulsante con menu	Un pulsante che apre altre opzioni. Aspetto: Diviso (il corpo agisce, la freccia apre il menu), Menu o Hamburger. Ogni opzione può nascondersi o disattivarsi in base a condizioni.
Link	Testo cliccabile — Destinazione: Schermata dell'app (con parametri) o URL esterno (con Apri in una nuova scheda).
Breadcrumb	Il percorso "sei qui", con livelli cliccabili e l'ultimo livello fisso o collegato a un campo.
Esporta	Un pulsante che scarica i dati di un datastore in foglio di calcolo (.xlsx) — campi scelti, Riga di intestazione opzionale e Nome del file con {date}.

Esporta legge i dati al momento del clic, a blocchi, fino a 50 000 righe; oltre, il file esce con le prime 50 000 e compare un avviso. L'evento onExport dice se il file è stato tagliato (truncated).

In KeplinGo il file esce in CSV; un testo che Excel leggerebbe come formula (che inizia con = o @, per esempio) riceve un apostrofo davanti.

#Struttura

Widget	A che cosa serve
Pannello	Un contenitore con cornice e titolo — sistema widget che cominciano a muoversi insieme.
Schede	Un contenitore con schede; ogni widget figlio appartiene a una scheda. Stile delle schede: Riquadro, Pill o Sottolineato.
Barra fissa	Una barra a tutta larghezza, fissata In alto o al Piè di pagina della schermata — per barre di azioni sempre visibili.
Linea	Una linea separatrice, Orizzontale o Verticale — il colore e il tratto vengono dall'Aspetto.

#Contenuto e media

Widget	A che cosa serve
Etichetta	Testo semplice — titoli, didascalie, valori sciolti. Accetta i Valori della frase ({n} nel testo).
Markdown	Testo ricco scritto in Markdown — fisso o proveniente da un campo.
Immagine	Un'immagine per URL fisso, Asset dell'app o Campo (dinamico); Adattamento: Contieni, Riempi o Estendi.
Pagina esterna	Incorpora una pagina esterna (una mappa, un video, BI di terzi) o HTML scritto da te. Gira isolata: non vede la sessione né i dati dell'app.

#Dati

Widget	A che cosa serve
Tabella	La griglia dei record — colonne tipizzate, ordinamento, selezione e pulsanti di azione. Dettaglio più sotto.
Elenco	Record in elenco verticale, con campi in ruoli (Titolo, Sottotitolo, Corpo, Didascalia) e immagine opzionale.
Card	Lo stesso template dell'Elenco, ma in griglia di card con N Colonne.
Grafico	Serie disegnate — barre, linee, torte e altro. Dettaglio più sotto.
KPI	Una fascia di indicatori numerici con tendenze, obiettivo e sparkline. Dettaglio più sotto.
Barra dei filtri	Condizioni in chip (campo, operatore, valore) che filtrano una Tabella, Lista, Schede, Kanban o Grafico della schermata. Dettaglio sotto.

#Board e pianificazione

Widget	A che cosa serve
Kanban	Card trascinabili fra colonne di stato. Dettaglio più sotto.
Calendario	Eventi in viste Giorno/Settimana/Mese/Anno. Dettaglio più sotto.
Gantt	Barre di inizio→fine con avanzamento, gruppi e dipendenze. Dettaglio più sotto.

#Documenti e processi

Widget	A che cosa serve
Report	Mostra un report dell'app (PDF) dentro la schermata, con parametri collegati a ciò che sta nella schermata e Barra delle azioni per aggiornare e scaricare.
Stato del processo	Lo storico e il passaggio attuale dei workflow di un record, con pulsanti di decisione quando l'attività aperta è di chi sta guardando.
Le mie attività	La casella di posta delle attività di workflow dell'utente con sessione — apre la schermata dell'attività e si decide da lì.

#La Tabella

La Tabella è il widget più usato della piattaforma: si collega a un datastore di elenco e mostra i record in griglia, con paginazione, ordinamento e selezione.

Il piè di pagina con il totale e le frecce di pagina compare solo quando i record non stanno in una pagina. Lo stesso vale per i widget Elenco e Card.

Le date che arrivano dall'API si mostrano nella lingua dell'app, e una colonna con il solo giorno mostra solo il giorno.

#Colonne

Collegando il datastore, le colonne nascono una per campo. Poi si rifinisce: in Colonne, usa + colonna per aggiungerne, e clicca su una colonna nel canvas per modificarla — l'inspector passa a lei.

Ogni colonna ha Intestazione, Larghezza, Ordinabile dall'intestazione, Nascosta — e un Tipo:

Tipo	Che cosa fa
Testo	Il valore così com'è, con Maschera opzionale (# = carattere).
Numero	Formatta il valore: Numero (regionale) (con Cifre decimali, Separatore delle migliaia, Compatto — 1,2 M invece di 1 234 567 —, Prefisso e Suffisso) oppure Maschera (# = cifra).
Collegamento	La cella diventa cliccabile. Destinazione: Schermata dell'app (con parametri provenienti da Campo della riga, Parametro dell'URL o Valore fisso) oppure Script — codice tuo che gira al clic. È la colonna giusta per aprire la scheda di un record dalla lista: la colonna che identifica la riga (nome, descrizione, data) porta alla schermata della scheda con l'id della riga; una schermata in modalità modale o pannello laterale si apre sopra e, alla chiusura, la lista si ricarica.
Immagine	Mostra l'immagine il cui indirizzo/contenuto è nel campo.
File	Un link di download per il file indicato nel campo.
Grafico spark	Un grafico piccolo per riga, a Linee o Barre, senza assi né etichette. La serie viene da un Campo con lista (una lista di numeri in JSON o dall'API, o un testo come 3,5,4) o da Più campi della riga, un punto per campo. Puoi scegliere il Colore, Mostra ultimo valore accanto, e una Scala fissa (minimo e massimo) per confrontare le righe tra loro. Questa colonna non ordina dall'intestazione.

Una colonna di un campo di relazione (cliente.nome) non ordina dall'intestazione: l'ordinamento gira sul server, che conosce solo i campi della tabella stessa.

#Azioni della tabella

Nella categoria Comportamento, la sezione delle azioni crea i pulsanti CRUD: Aggiorna, Aggiungi nuovo, Modifica record, Elimina record ed Elimina multipli. Ogni azione attivata crea un pulsante sciolto nel canvas, collegato alla tabella — posizioni e dai stile a quel pulsante come a qualsiasi altro.

• Aggiungi nuovo e Modifica record aprono una schermata o un modale a tua scelta (tipicamente il modulo del record), con i parametri compilati a partire dalla riga.
• Modifica record ed Elimina record restano attivi solo con una riga selezionata; Elimina multipli lavora sulla Selezione multipla (l'interruttore che aggiunge la colonna di checkbox).
• Le azioni che scrivono richiedono che il datastore abbia una chiave primaria — l' inspector avvisa: Il datastore ha bisogno di una chiave primaria.

#Moduli (input + record + validazione)

Non esiste un widget "modulo": un modulo è la somma di tre pezzi, ed è questa libertà che ti lascia disegnare la scheda come vuoi.

1. Crea un datastore di record nella schermata (vedi Datastore e dati) — per esempio, conta, caricato con la chiave che arriva dal parametro id del percorso.
2. Trascina i campi di modulo (Casella di testo, Dropdown, Data…) e, in ognuno, collega il Collegamento ai dati al campo giusto del datastore.
3. Metti un Pulsante "Salva" il cui evento salva il datastore — l'azione predefinita Salva datastore dell'editor di eventi scrive il codice per te (vedi Eventi e SDK).

La validazione vive in ogni campo, nella categoria Validazione:

• Obbligatorio — il campo deve arrivare compilato.
• Le regole standard: Min caratteri, Max caratteri, È email, È telefono, È numero, Valore min., Valore max., Pattern (regex) e Uguale al campo (conferma della password, per esempio).
• Convalida con script — per la logica tua: il codice riceve value (il valore attuale del campo) e restituisce true se valido, oppure il messaggio di errore. Una partita IVA, un IBAN, una regola di business.

Al salvataggio, la validazione gira tutta: prima gli obbligatori, poi le regole, poi lo script. Il record procede solo se passa tutto.

Un campo con errore prende il bordo rosso, e il messaggio compare sotto di esso, nello spazio tra i widget. Il campo e la sua etichetta restano al loro posto. Perché il messaggio si veda per intero, lascia almeno 16 pixel tra un campo e il widget sottostante, e tra un campo e il fondo del pannello o della scheda che lo contiene.

#Il Grafico

Il Grafico si collega a un datastore e disegna serie. In Tipo di grafico scegli: Barre, Linea, Area, Torta / Donut, Dispersione, Radar, Gauge (indicatore), Imbuto o Mappa di calore.

L'essenziale è la mappatura, nella categoria Dati:

• Campo di categoria (asse X / fette) — ciò che separa le barre/fette.
• Campi di valore — uno o più campi numerici; ognuno è una serie.
• Campo di serie (raggruppamento) — in alternativa ai vari valori: pivota sul primo campo di valore e crea una serie per ogni valore distinto (senza valori, conta i record).

E poi la rifinitura:

Opzione	Che cosa fa
Impilato, Orizzontale, Linee morbide, Valori sui punti	Variazioni del disegno, a seconda del tipo.
Legenda, Posizione della legenda, Tooltip	Il chrome del grafico. La legenda si trascina anche direttamente nel grafico per posizionarla.
Formato dei valori	Lo stesso formato delle colonne Numero della tabella, applicato ad assi, etichette e tooltip.
Scala dei valori	Lineare o Logaritmica — la logaritmica serve quando le serie hanno ordini di grandezza diversi.
Usa un secondo asse	Un asse a destra con scala propria — per mettere insieme un totale in euro e un conteggio nello stesso grafico.
Serie	Tipo per serie (combinazioni di barre con linee) e quali serie vanno sul 2° asse.
Opzioni avanzate	Un editor di codice con tutte le proprietà del motore di grafici, con autocomplete — applicate sopra la configurazione, per i casi che i campi non coprono.

#Il KPI

Il KPI è una fascia di indicatori — quattro numeri affiancati si fanno con un widget di quattro indicatori, non con quattro widget: l' allineamento e la spaziatura restano garantiti.

Ogni indicatore (in Indicatori ▸ Aggiungi indicatore) ha:

• Etichetta e icona, con Posizione della didascalia (Sopra il valore / Sotto il valore).
• Valore (campo) + Aggregazione (Somma, Media, Conteggio, Massimo, Minimo, Primo, Ultimo) sull'insieme dei dati — oppure un Valore manuale quando non ci sono dati collegati.
• Tendenze (Aggiungi tendenza) — confronti sotto il numero, con Campo di riferimento, formato Percentuale o Valore assoluto, e Meno è meglio (inverte i colori): in un debito che cresce, la freccia deve essere rossa.
• Obiettivo — Nessun obiettivo, Valore manuale o Campo del datasource, con Barra di avanzamento opzionale.
• Mostra sparkline — la mini-linea dello storico, con Campo della serie.
• Periodo (dal campo) — di quale chiusura parla il numero (una data ISO si mostra come MM/AAAA).

L'insieme di dati è condiviso dal widget, ma ogni indicatore può avere un Set di dati proprio.

#Il Kanban

Il Kanban mostra i record come card in colonne — la pipeline di opportunità di Gestione Clienti è un kanban per stato.

1. Collega il datastore e scegli il Campo di stato (colonna) — il campo che dice in quale colonna si trova ogni card.
2. Definisci l'Origine delle colonne: Statica (aggiungi ogni colonna con Etichetta, Valore e colore) oppure Enum (le colonne vengono dai valori di un enum del modello).
3. Componi il Template della card — i campi e i ruoli, come nell'Elenco.

Con Consenti di trascinare le card attivo, spostare una card salva subito il nuovo stato nel record. Campo di ordine (un campo numerico) rende l'ordinamento dentro la colonna persistente. Colonna senza categoria raccoglie i record il cui stato non corrisponde a nessuna colonna; Conteggio delle card mostra il totale nell'intestazione.

Le azioni: Clic su una card (modifica) e Crea card (pulsante nella colonna) — ognuna può navigare verso una schermata, aprire un modale (con i parametri della riga e della colonna) o emettere un evento per codice tuo.

#Il Calendario

Il Calendario mostra i record con data come eventi, nelle viste Giorno, Settimana, Mese e Anno.

• Campi: Campo data (inizio), Campo di fine (opzionale) (eventi multigiorno), Campo del titolo.
• Colore degli eventi: Unico o Per campo — con una mappa valore → colore (un enum di tipo, per esempio).
• Vista: Vista iniziale, Viste disponibili, 1° giorno della settimana (Lunedì/Domenica), Max eventi per giorno nella vista mese, ore di Inizio/Fine nelle viste giorno/settimana, Barra di navigazione e Pulsanti di cambio vista.
• Azioni: Clic su un evento (modifica) e Selezione di giorno/intervallo (crea) — l'inizio/fine proseguono verso la schermata di destinazione come parametri, pronti a precompilare il modulo di creazione.

Il calendario carica solo i record dell'intervallo visibile — cambiare mese va a prendere il mese nuovo, non la tabella intera.

#Il Gantt

Il Gantt disegna barre di inizio→fine su una linea temporale — pianificazione di progetti, campagne, onboarding di clienti.

• Campi: Campo di inizio, Campo di fine, Campo dell'etichetta, Campo di avanzamento (0–100) e Campo di gruppo (raggruppa le righe).
• Campo delle dipendenze — gli ID (chiave primaria) dei predecessori, in elenco JSON o separati da virgola; il Gantt disegna le frecce.
• Zoom iniziale (Giorno, Settimana, Mese), Linea di oggi e Ombreggia i fine settimana.
• Azioni: Clic su una barra (modifica) e Clic su area vuota (crea) — la data cliccata prosegue come parametro.

Il Gantt è in lettura: le barre non si trascinano — le date si cambiano nel modulo del record.

#La Barra dei filtri

La Barra dei filtri permette a chi usa l'app di filtrare una lista per qualsiasi campo, senza che tu debba disegnare un campo di filtro per ogni colonna. Sta sopra una Tabella, Lista, Schede, Kanban o Grafico e scrive le condizioni in chip.

1. Trascina la Barra dei filtri nella schermata e, in Dati, scegli il Widget di destinazione — il widget di elenco il cui datastore riceve le condizioni.
2. In Campi filtrabili, scegli i campi da offrire. Senza scelta, la barra offre tutti i campi semplici del datastore della destinazione; le intestazioni delle colonne della tabella fanno da etichetta. I campi di relazione (cliente.nome) non vengono offerti: il filtro gira sul server, che conosce solo i campi della tabella stessa.
3. Facoltativo: in Valori visibili, scegli quanti valori suggeriti mostra l'elenco alla volta (10 per impostazione predefinita; 0 li mostra tutti). La ricerca cerca sempre in tutti i valori, e un piè di pagina indica quanti sono. Nel passo del valore, la lente nel piè di pagina apre la finestra di scelta con tutti i valori del campo.

Nell'app, ogni condizione si scrive in tre passi, sempre in vista: il campo, l'operatore e il valore. Le opzioni del passo seguente compaiono da sole; scrivere le filtra. I valori suggeriti vengono dai dati caricati, ma ciò che si scrive vale sempre, anche se non è nella lista.

Gli operatori dipendono dal tipo del campo: testo (contiene, uguale a, inizia con…), numero e data (confronti), e liste (uguale a, diverso da). Uno di e nessuno di accettano più valori nello stesso chip: ogni scelta entra, e Invio o Applica chiude la condizione. La × di un chip toglie quella condizione; la × della barra cancella tutto.

Quando una condizione si chiude, l'elenco non si riapre da solo: la barra resta pronta per scrivere. Per un altro filtro, scrivi, fai clic sulla barra o premi ↓.

Le condizioni si uniscono a quelle del datastore della destinazione (Filtri (where)) e la richiesta va al server con paginazione — filtrare non porta mai la tabella intera. I filtri per widget (una Lista collegata a una condizione del datastore) continuano a esistere e possono convivere nella stessa schermata: il menu rapido per il filtro più usato, la barra per tutto il resto.

Nei campi data, il valore si scrive come si legge: «26/09/2026», «26-09-2026», «26.09.2026» o «2026-09-26», con o senza ora. Quando giorno e mese si possono confondere, il giorno viene prima. Una data senza ora vale per l'intera giornata: minore o uguale a 26/09/2026 include i record di quel giorno, e maggiore di 26/09/2026 inizia dal giorno dopo. Diverso da e nessuno di includono i record con il campo vuoto.

#Perché no…?

• Perché non appare la sezione Validazione nel mio widget? Solo i campi di modulo validano — un Pulsante o un'Etichetta non hanno un valore da validare.
• Perché il widget appare nella palette ma grigio nel canvas? È disattivato (interruttore Attivo nella categoria Layout) oppure una regola/evento l'ha disattivato.
• Perché non vedo dati nel canvas? Il canvas mostra campioni — i dati reali appaiono nell'anteprima e nell'app pubblicata. Verifica il collegamento nel capitolo Datastore e dati.
• Perché la Barra dei filtri dice "Nessun widget di destinazione"? Manca il Widget di destinazione in Dati — solo i widget con datastore di lista (Tabella, Lista, Schede, Kanban, Grafico) possono essere destinazione.