Creare un report

Un report è un documento stampato a partire dai dati dell'app: un elenco, una fattura, un prospetto di chiusura del mese. Esce in PDF — paginato, con intestazioni che si ripetono e totali alla fine — oppure in Excel, e può essere generato a mano, da un pulsante di una schermata, da uno script, da un workflow, o da una pianificazione che lo invia per email.

Il modello è quello delle bande: un report non è una schermata che cresce verso il basso, è una sequenza di fasce che il motore ripete secondo la regola di ciascuna — una volta, per pagina, per riga, per gruppo. È questo che rende possibile la paginazione.

L'unità è il millimetro, dappertutto. È l'unità della carta e sopravvive al passaggio da A4 a Letter.

In questa pagina disegniamo il report Oportunidades por conta dell'app Gestione Clienti: il pipeline commerciale raggruppato per account, con i contatti di ciascuno, il totale per account e un grafico alla fine.

#Dove vivono i report

I report stanno nel minitab Dati dell'albero dell'app, sotto le fonti di dati. Cliccare sul nome apre il disegno in una scheda.

Un'app senza report mostra "Nessun report — creane uno per disegnarlo.".

#Creare un report

1. Passa il mouse sulla riga del gruppo Report e clicca su Nuovo report.
2. Scrivi il Nome — per esempio Fatture del mese.
3. Clicca su Crea.

"Crea un report nella radice. Puoi spostarlo in una cartella dopo." Il report nasce in A4 verticale, con le cinque bande fisse e senza dati collegati, e il disegno si apre subito.

#Il disegno

La scheda ha tre colonne e una barra in alto:

Zona	Che cos'è
Barra in alto	Il nome, l'identificatore del report (rpt_…, quello che il codice usa per richiamarlo), lo stato del salvataggio, annulla/ripeti, le misure della carta e i pulsanti Excel e Anteprima.
Colonna di sinistra	La palette Elementi, i Dati, i Raggruppamenti, i Parametri e le Pianificazioni.
Centro	La superficie di disegno: un righello in millimetri e le bande, una sopra l'altra nell'ordine in cui escono sulla carta.
Destra	Le proprietà — del report, della banda selezionata o dell'elemento selezionato.

Come nel resto della piattaforma, non c'è un pulsante per salvare: il disegno si salva da solo.

#Le bande

Le bande sono un insieme fisso — non si aggiungono fasce a piacere, perché ciascuna ha una propria regola di ripetizione che il motore conosce dal nome.

Banda	Quando compare
Intestazione del report	"Compare una sola volta, all'inizio della prima pagina." Logo, titolo, data di emissione.
Intestazione di pagina	"Si ripete in alto in tutte le pagine — logo, titoli di colonna."
Dettaglio	"Compare una volta per ogni riga di dati. È questa banda che riempie il report."
Piè di pagina	"Si ripete in basso in tutte le pagine — numero di pagina, data."
Piè di pagina del report	"Compare una sola volta, alla fine — totali generali." Nasce disattivata.

A queste si aggiungono, quando ci sono raggruppamenti, un'intestazione e un piè di pagina per livello — vedi Grafici e sotto-report.

Cliccare sul titolo di una banda la seleziona; il pannello di destra passa a mostrarne le proprietà.

Proprietà	Cosa fa
Altezza (mm)	L'altezza della fascia. Si trascina anche la linea divisoria, sulla superficie di disegno.
Attiva	"Disattivata, la banda non compare nel report né occupa spazio."
Regole della banda	Sopprimere la banda in base ai dati.

Sulle regole: "sopprimere la banda in base ai dati. Soppressa, non compare né occupa spazio — è ciò che sostituisce l'avere più bande di dettaglio". Invece di tre fasce di dettaglio con condizioni diverse, una fascia e regole che la nascondono quando non è il caso.

#La carta

Con niente selezionato, il pannello di destra mostra le proprietà del report e della pagina:

Campo	Opzioni
Nome / Descrizione	Identificazione, per chi costruisce.
Formato	A4, A3, A5, Letter, Legal o Personalizzato (larghezza e altezza in mm).
Orientamento	Verticale o Orizzontale.
Margini (mm)	Superiore, Inferiore, Sinistra, Destra.

"Lo spazio tra la carta e il contenuto. La larghezza utile che resta è quella della superficie di disegno" — cambiare i margini cambia la larghezza su cui disegni, e il righello si adegua.

La sezione Vista, in fondo al pannello, ha lo Zoom della superficie di disegno. Non tocca il documento; è solo la lente di chi disegna.

#I dati

Un report senza dati collegati non ha campi da trascinare. Apri Set di dati dal + della sezione Dati:

Ogni set ha:

Campo	Note
Nome del set	Come lo chiamano gli elementi (oportunidades, contactos).
Ruolo	principale, collegato o autonomo — vedi la tabella qui sotto.
API di tabella	L'API dell'app da cui vengono le righe.
Filtri (where)	La stessa grammatica di filtri del resto della piattaforma. Può confrontare con i parametri del report.
Caricamento / Per pagina	Come vengono lette le righe.

I tre ruoli:

Ruolo	Cosa significa
principale	"La banda di dettaglio lo percorre, una riga stampata per ogni sua riga." Ce n'è uno solo.
collegato	"Appartiene a una riga di un altro set tramite il campo che indichi — la fattura e le sue righe."
autonomo	"Né percorso né collegato, serve per l'intestazione o per un totale generale."

Un set collegato chiede altri tre campi: il Set padre, il Campo nel padre ("il campo che identifica la riga del padre — di solito la chiave") e il Campo in questo set ("il campo che punta indietro al padre").

Nella colonna di sinistra, ogni set compare con il numero di campi e si espande con la freccia. Trascinare un campo su una banda crea un elemento Campo già collegato — è il modo più rapido di riempire la banda di dettaglio.

#I parametri

I parametri sono "valori che il report riceve da chi lo esegue" — il mese, la fase, il cliente. Si usano nei filtri dei set di dati.

Campo	Note
Nome	Come lo chiamano il filtro e il codice.
Etichetta	Quello che si legge quando il valore viene chiesto.
Tipo	Testo, Numero, Data o Sì/No.
Obbligatorio	Senza valore, il report si rifiuta di partire.
Valore predefinito	Usato quando chi lo chiama non ne dà nessuno.

#Gli elementi

La palette Elementi ha tutto quello che si mette in una banda. Si trascina sulla banda; si lascia dove deve stare.

Elemento	A cosa serve
Testo	Testo fisso — titoli, etichette, piè di pagina.
Campo	Il valore di un campo del set. È quello che esce dal trascinare un campo.
Aggregato	Un calcolo su un set: Somma, Media, Conteggio, Minimo, Massimo.
Campo di sistema	Numero di pagina, Totale pagine, Pagina X di Y, Data di emissione, Nome del report.
Linea	Separatori e cornici.
Rettangolo	Sfondi e riquadri, con riempimento, bordo e angoli.
Immagine	Un file dell'app, un indirizzo, o il contenuto di un campo.
Grafico	Nove tipi, con gli stessi dati delle schermate.
Sotto-report	Un altro report disegnato dentro questo.
Codice a barre	Code 128, EAN-13 o QR.

Gli ultimi tre hanno una pagina propria: Grafici e sotto-report.

#Le proprietà di un elemento

Clicca su un elemento sulla superficie di disegno:

Sezione	Cosa contiene
Posizione e dimensione	X (mm), Y (mm), Larghezza (mm), Altezza (mm). La y conta a partire dall'alto della banda.
Aspetto	Carattere, Corpo (pt), grassetto/corsivo/sottolineato, allineamento, Allineamento verticale, colore, Riempimento, Bordo (mm) e Colore del bordo, Testo a capo.
Formato (campi e aggregati)	Maschera di presentazione, con la stessa grammatica delle colonne della tabella.
Esportazione	Nome della colonna in Excel. "Vuoto usa il nome del campo. Sulla carta non appare — lì l'intestazione è un testo che disegni dove vuoi."
Regole di formattazione	Vedi sotto.

Su Testo a capo: "disattivato, il testo che non ci sta viene tagliato invece di passare alla riga successiva" — è quello che si vuole in una colonna di tabella, perché una riga lunga non spinga via l'intera pagina.

Selezionando più elementi (con il riquadro di selezione o con Shift), il pannello dice quanti sono e li sposta insieme, con il mouse o con le frecce.

#Regole di formattazione

Ogni elemento può avere regole che "cambiano l'aspetto in base ai dati della riga: colorare un valore in ritardo, nascondere un'etichetta, mettere un totale in grassetto quando è negativo". Sono lo stesso motore e lo stesso editor delle regole dei widget.

L'ultima regola che corrisponde è quella che comanda — ordinale dalla più generale alla più specifica.

#Vedere il risultato

Due pulsanti, nell'angolo in alto a destra:

• Anteprima genera il PDF con i dati reali dell'app e lo apre lì stesso, paginato. È così che si controlla il disegno: non sempre quello che sta nella superficie di disegno sta nella pagina.
• Excel genera il foglio di calcolo e lo scarica. Qui non ci sono bande né pagine: esce una tabella, con una colonna per ogni elemento della banda di dettaglio, e le intestazioni vengono dal Nome della colonna di ciascuno.

Se il report ha parametri obbligatori, vengono chiesti prima di generare.

#Domande frequenti

La banda di dettaglio esce vuota. Non c'è un set principale, oppure il suo filtro non restituisce righe. Apri Set di dati e controlla che ce ne sia uno con il ruolo principale, e che i parametri usati dal filtro abbiano un valore.

Un campo in una banda di intestazione esce vuoto. È previsto fuori dalle bande di gruppo. Nell'Intestazione del report e nel Piè di pagina del report non c'è una "riga corrente" — mostrare la prima di tutte sarebbe inventarsi un valore. In un'intestazione di gruppo, il campo legge la prima riga del gruppo, che è quello che si vuole.

Il report è lento o tronca. Ogni set ha un tetto di righe per lettura. Filtra di più — per data, per stato — invece di stampare l'intera tabella. Un report di 4.000 pagine non lo legge nessuno.

Mi serve più di quello che una pianificazione sa fare. Scrivi uno script Python e chiama reports.render(...) — vedi Pianificare e inviare.