Generazione documenti

In molti casi potresti aver bisogno di generare documenti scaricabili dai dati della tua app Bobuild. Questa potente funzionalità ti permette di progettare un template completamente personalizzato e farlo compilare da Bobuild al volo nella tua app.

Bobuild supporta due tipi di template:

• Template Docx — progettali in Microsoft Word o LibreOffice Writer; possono generare file .docx o .pdf.
• Template Xlsx — progettali in Microsoft Excel o LibreOffice Calc; generano file .xlsx.

Alcuni esempi di documenti che potresti voler generare:

• fatture
• report
• certificati
• fogli di calcolo ed export dati

Gestire i template nel Builder

Apri Document templates nell'area impostazioni dell'app per aggiungere template Docx o Xlsx, nominarli, collegarli a un oggetto, caricare o scaricare il file template e mappare variabili a valore singolo e liste. Tieni i design incompleti come template separati finché non sei pronto a puntare i Task su di essi — così eviti di rompere azioni generate-document live mentre iteri.

Creare un template Docx

Usa Microsoft Word o LibreOffice e progetta il template senza restrizioni. Poi inserisci placeholder nel documento dove vuoi che Bobuild inietti i dati.

Per iniettare una variabile semplice, usa questa sintassi:

{{ myvariable }}

Nota: metti sempre uno spazio prima e dopo il nome della variabile!

Se vuoi usare logica condizionale, usa questa sintassi:

My house is located {% if living_in_town %} in urban area 
{% else %} in countryside {% endif %} and I love it.

Se vuoi ripetere un blocco, usa questa sintassi:

{% for p in products %}
- Product: {{ p.name }}
{% endfor %}

Se vuoi ripetere una riga di tabella, usa questa sintassi:

Products
{%tr for p in products %}
Product: {{ p.name }}
{%tr endfor %}

Come funziona? Se un tag inizia con {%tr invece che solo {%, l'intera riga della tabella dove si trova verrà rimossa dall'output. Quindi, in questo esempio, la seconda e la quarta riga verranno rimosse, e solo la terza riga verrà ripetuta per ogni elemento.

Creare un template Xlsx

Usa Microsoft Excel o LibreOffice Calc e progetta il template senza restrizioni. I placeholder usano la stessa sintassi basata su Jinja dei template Docx.

Per iniettare una variabile semplice:

{{ foo }}

Per trasformare un valore con un filtro Jinja:

{{ foo|upper }}

Per logica condizionale:

{% if foo %}bar{% else %}baz{% endif %}

Per ripetere un blocco di righe, usa il prefisso tr così la riga che contiene il tag stesso viene rimossa dall'output:

{%tr for item in items %}
{{ item.name }}
{%tr endfor %}

Se un tag inizia con {%tr invece che solo {%, l'intera riga dove si trova verrà rimossa dall'output, e solo le righe tra i tag di apertura e chiusura verranno ripetute per ogni elemento della collezione.

I placeholder funzionano anche nei nomi dei fogli, così puoi nominare le schede dinamicamente dai tuoi dati.

Sintassi Jinja

I template Docx e Xlsx usano entrambi Jinja2, un linguaggio di templating molto diffuso. Gli esempi sopra coprono variabili, condizionali e loop; la documentazione Jinja template designer è il riferimento completo per tutto il resto che puoi usare in un template.

Alcune convenzioni utili da ricordare:

• Metti uno spazio dentro le doppie parentesi graffe: {{ myvariable }}, non {{myvariable}}.
• Accedi ai campi oggetto con la notazione punto: {{ customer.name }}.
• Concatena i filtri con |: {{ value|filter1|filter2 }}.

Filtri utili

I filtri trasformano un valore con la sintassi pipe {{ value|filter }}. Questi filtri sono particolarmente utili nei template documento:

length — conta gli elementi in una collezione:

You have {{ products|length }} products in this order.

round — arrotonda un numero (opzionalmente specifica le cifre decimali):

Total: {{ invoice.total|round(2) }}

format — costruisce una stringa da un pattern di formato (simile al formatting % di Python):

{{ "Invoice #%s dated %s"|format(invoice.number, invoice.date) }}

selectattr — mantiene solo gli elementi in una collezione il cui attributo soddisfa un test. Utile quando ti servono le righe che appartengono a un record genitore (vedi la sezione successiva):

{% for order in orders|selectattr("customer_id", "equalto", customer.id) %}
Order: {{ order.number }} - {{ order.date }}
{% endfor %}

Report con record genitore e figli

Molti report elencano un record genitore (come un cliente) e, sotto, i record figli correlati (come gli ordini di quel cliente). Tipicamente esponi entrambe le collezioni al template — customers e orders — e annidi i loop così il loop interno stampa solo le righe che appartengono al genitore corrente:

{% for customer in customers %}
Customer: {{ customer.name }}
{% for order in orders %}
{% if order.customer_id == customer.id %}
Order: {{ order.number }} - {{ order.date }}
{% endif %}
{% endfor %}
{% endfor %}

Lo stesso risultato è spesso più leggibile con selectattr, che filtra la collezione interna invece di avvolgere ogni riga in {% if %}:

{% for customer in customers %}
Customer: {{ customer.name }}
{% for order in orders|selectattr("customer_id", "equalto", customer.id) %}
Order: {{ order.number }} - {{ order.date }}
{% endfor %}
{% endfor %}

Nelle tabelle Docx e negli intervalli di righe Xlsx, usa {%tr for %} / {%tr endfor %} sulle righe che vuoi ripetere, come descritto nelle sezioni sopra.

Configurare il template

Una volta creato il template, devi andare nel Builder e configurare la sorgente dati del template. Definirai due cose:

1. quali campi oggetto devono essere resi disponibili al template (negli esempi sopra, i campi myvariable, foo e living_in_town)
2. quali dati tabulari devono essere resi disponibili al template (negli esempi sopra, le variabili products o items che contengono una collezione di record estratti con certi criteri)

Usare il template

A questo punto sei pronto! Configura semplicemente il Task dove ti serve nell'app e puntalo al tuo template. Dovrai configurare le seguenti impostazioni:

Impostazione	Descrizione
File name	Il nome file da usare per il file generato
Format	.docx o .pdf per template Docx; .xlsx per template Xlsx
Field	Il campo oggetto dove vuoi memorizzare il documento generato.

Quando il formato è PDF, Bobuild genera un file PDF/A-2b (con PDF/UA per l'accessibilità) adatto ad archiviazione e workflow con firma digitale.

Se la generazione fallisce (errori di template, problemi di conversione e simili), il fallimento viene registrato sotto Error Logs nel Builder (tipo Document generation), con contesto di template e record quando disponibile. Vedi Error Logs.

Pattern comuni

Un modo comune per far generare e scaricare un documento agli utenti è mettere un form vuoto, con solo un pulsante di invio, che ha un Task "Generate document", e poi reindirizzare a un'altra pagina (o anche alla stessa pagina) dove viene mostrato il campo che contiene il documento generato così gli utenti possono cliccarci e scaricarlo.