Templates
Come creare modelli di documento Word che si compilano da soli con i dati di UtiliX.
Cos'è un Template documentale
Un Template è un file Word "modello": invece di scrivere un contratto o un modulo da zero per ogni cliente, lo prepari una volta sola, con dei segnaposto al posto dei dati che cambiano (nome del cliente, indirizzo, data...). Da quel momento, chiunque in agenzia può generare in un secondo un documento Word già compilato con i dati reali di un cliente o di un contratto specifico, semplicemente scegliendo il template giusto.
Non serve saper programmare
Creare un template significa semplicemente scrivere un normale documento Word e, dove normalmente scriveresti "Mario Rossi", scrivere invece un segnaposto come {{ nome }}. Il resto lo fa UtiliX. Le prossime sezioni spiegano passo passo come funziona.
Come funziona la generazione
Ogni template è collegato a un'Entità di Riferimento, cioè al tipo di dato da cui prende le informazioni per compilarsi. Al momento sono supportate:
- Cliente: i dati dell'Account (nome, cognome/ragione sociale, codice fiscale, indirizzo, contatti...).
- Contratto Energia: i dati del contratto (prodotto, fornitore, PDP, prezzo, cliente collegato...).
Quando un utente genera un documento (ad esempio dal pulsante nella scheda di un Cliente), UtiliX:
- individua l'entità reale scelta (es. "Mario Rossi");
- sostituisce ogni segnaposto del template con il valore corrispondente preso da quell'entità;
- genera un file Word pronto, che viene scaricato immediatamente.
Solo template Attivi sono selezionabili
Un template appena creato non è visibile agli utenti finché non lo attivi esplicitamente. Verifica sempre il documento generato prima di attivare un template nuovo: un errore di sintassi o un segnaposto sbagliato produrrebbe documenti compilati male per tutta l'agenzia.
Il motore Jinja: come si scrivono i segnaposto
UtiliX compila i template Word usando Jinja, un linguaggio di "templating" molto diffuso (motore anche di moltissimi siti web e strumenti professionali). Non è un linguaggio di programmazione da imparare per intero: per il 95% dei casi ti basteranno due sole regole.
1. Inserire un dato singolo
Scrivi il nome del campo tra doppie parentesi graffe, direttamente nel testo del documento Word:
Gentile {{ nome }} {{ cognome }},
con la presente Le confermiamo l'attivazione del contratto {{ contratto.name }}
sul punto di fornitura {{ contratto.pdp.nome }}, a partire dal {{ data_oggi }}.
Ogni {{ ... }} viene sostituito dal valore reale al momento della generazione. Come si vede nell'esempio, un segnaposto può anche "scendere" dentro un dato collegato: {{ contratto.pdp.nome }} significa "dal contratto, prendi il PDP collegato, e da lì il suo nome".
2. Ripetere una tabella (elenchi di elementi)
Quando un'entità ha una lista di elementi collegati (ad esempio i vari prodotti applicati a un contratto), puoi ripetere automaticamente una riga di tabella per ciascun elemento, usando un ciclo:
{% tr for item in prodotti %}
{{ item.nome }} {{ item.prezzo }}
{% endtr %}
Questa sintassi (da inserire dentro una vera tabella Word, riga per riga) dice a UtiliX: "per ogni elemento della lista, aggiungi una riga con questi dati".
Non serve indovinare i nomi dei campi
Non devi ricordare a memoria i nomi esatti dei campi disponibili: la sezione Dizionario Variabili del template, descritta più sotto, elenca tutti i segnaposto disponibili già pronti da copiare e incollare nel tuo documento Word.
Vuoi approfondire?
Jinja supporta anche condizioni ({% if %}), formattazioni e molto altro. UtiliX copre la stragrande maggioranza dei casi d'uso con le sole due regole sopra, ma se vuoi approfondire la sintassi completa puoi consultare la documentazione ufficiale di Jinja (in inglese).
Creare un template
Permessi
Solo gli utenti con ruolo Backoffice o Admin possono creare, modificare, attivare/disattivare o eliminare un template. Tutti gli utenti possono invece usarli per generare documenti. Consulta la pagina Permessi e ruoli per la lista completa.
Apri la sezione Templates
Dal menu, apri Templates (in File e Documenti).
Crea un nuovo template
Premi . Inserisci un Nome riconoscibile (es. "Contratto Iren Luce") e una Descrizione opzionale, per aiutare i colleghi a capire quando usarlo.
Scegli tipo ed entità
Seleziona il Tipo di Template: al momento solo Word Template (Jinja) è disponibile (il formato PDF editabile è in arrivo). Scegli poi l'Entità di Riferimento (Cliente o Contratto Energia): determina sia da dove arrivano i dati, sia in quale punto del gestionale comparirà il pulsante per generare il documento con questo template.
Carica il file Word
Prepara il tuo documento Word con i segnaposto Jinja come spiegato sopra, e caricalo (massimo 10 MB).
Il file viene validato al caricamento
UtiliX controlla automaticamente che la sintassi Jinja del file sia corretta prima di accettarlo. Se hai lasciato una graffa aperta o scritto un segnaposto malformato, il caricamento viene rifiutato con un messaggio d'errore che indica il problema di sintassi: correggi il file Word e ricaricalo.
Attiva quando sei pronto
Il template nasce non attivo. Genera un documento di prova, verificalo con attenzione, e solo a quel punto attivalo dal menu azioni per renderlo disponibile a tutta l'agenzia.
Il Dizionario Variabili
Ogni template ha una pagina di dettaglio con il Dizionario Variabili: l'elenco completo di tutti i segnaposto disponibili per l'entità scelta (Cliente o Contratto), con una breve descrizione di ciascuno e un pulsante per copiarlo negli appunti. Include anche i campi "calcolati" come {{ data_oggi }} (la data del giorno in cui viene generato il documento) e i segnaposto per le tabelle/liste (es. i prodotti di un contratto), già formattati nella sintassi corretta del ciclo {% tr for %}.
Usalo mentre scrivi il documento
Il modo più comodo di lavorare è tenere aperta la pagina del Dizionario Variabili in una scheda del browser, cercare lì il campo che ti serve (es. digitando "indirizzo" nella barra di ricerca), copiarlo, e incollarlo nel punto giusto del tuo file Word.
Generare un documento da un template
Dalla scheda di un Cliente (o di un Contratto, quando supportato), premi il pulsante : si apre una finestra con l'elenco dei template attivi disponibili per quel tipo di record. Seleziona quello desiderato: UtiliX compila il file al volo e lo scarica automaticamente, pronto per essere firmato, stampato o archiviato nella sezione Documenti.
Vedi anche