.. _le_stampe/template/template_editor:

Template Editor
===============




I template possono essere usati all'interno di Genropy per una serie di scopi:

- `creare stampe personalizzate da template <https://www.genropy.org/docs/manuale_utente_genropy/stampe/stampe_personalizzate/stampe_personalizzate_template.html>`_
- `inviare e-mail automatizzate <https://www.genropy.org/docs/package/email/email.html>`_ personalizzate (stampe unione, mail con dati di record)
- rappresentare i dati di un record in un'area delimitata di una pagina con un `templateChunk <https://www.genropy.org/docs/widgetpedia/components/templateChunk.html>`_ o all'interno di un `linkerbox <https://www.genropy.org/docs/widgetpedia/components/linkerbox_bts.html>`_
- visualizzare un'anteprima dei dati del record nella griglia. 

In tutti questi casi, il Template Editor è lo strumento che consente di realizzare un template in formato HTML tramite una comoda interfaccia grafica.


Esso dà la possibilità di:

- utilizzare i classici elementi di formattazione (testi, tabelle, bottoni, immagini)
- modificare o inserire un  ``Codice sorgente`` direttamente in HTML
- includere nel template i valori di alcuni *parametri* (che l'utente inserirà al lancio della stampa) e delle *variabili* (le colonne della tabella a cui si applica il template o quelle in relazione)

.. image:: /_static/images/template_modifica.png
    :width: 600px
    :align: center
    
Si rimanda al manuale utente per la procedura generale di `creazione di un template <https://www.genropy.org/docs/manuale_utente_genropy/stampe/stampe_personalizzate/stampe_personalizzate_template.html>`_ di stampa/email, mentre si specificano di seguito alcuni dettagli per gli sviluppatori e gli utenti esperti.

Ci limitiamo di seguito a trattare quegli aspetti tipicamente gestiti dallo sviluppatore e non dall'utente.

*Mask* e *Modifica Pars*
************************

.. hint::
  L'utilizzo di ``Mask`` è deprecato, in quanto sostituito dall'utilizzo, all'interno del template, della sintassi presentata nel paragrafo seguente.

La colonna ``Mask`` del tab ``Metadata`` può essere utilizzata per personalizzare il contenuto (non solo il valore, quindi, ma la "maschera") che verrà inserito nel template. La maschera può per esempio essere utilizzata per aggiungere del testo prima o dopo (es: ``cliente: %s``), per mettere il contenuto tra parentesi (es: ``(%s)``), per aggiungere una valuta (es: ``€ %s``). Come si nota, il contenuto originale verrà inserito con il simbolo ``%s``. Si noti che lo stesso risultato può essere ottenuto utilizzando la sintassi presentata al paragrafo seguente.

``Modifica pars``, invece, di fatto è un campo utile esclusivamente per i `templateChunk <https://www.genropy.org/docs/widgetpedia/components/templateChunk.html>`_ utilizzati all'interno dei `linkerBox <https://www.genropy.org/docs/widgetpedia/components/linkerbox_bts.html>`_

Variabili e parametri
*********************
  
Le relazioni `molti a uno <https://www.genropy.org/docs/genropy_orm/model/relation.html>`_ sono percorribili direttamente, di conseguenza basterà trascinare la colonna di interesse che è in relazione con la tabella in cui si sta definendo il template (specificando eventualmente un ``As`` più leggibile), e i valori verranno correttamente richiamati.

Qualora invece si intendesse richiamare i dati di record in relazione "uno a molti" (come nell'esempio, dalla *Fattura* alle singole *Righe Fattura*), è necessario specificare la relazione da seguire (nel nostro caso ``@righe``, corrispondente al `relation_name <https://www.genropy.org/docs/genropy_orm/model/relation.html>`_ che abbiamo assegnato alla colonna in relazione) nella proprietà ``Row Datasource`` della tabella:
      
.. image:: /_static/images/proprieta_tabella.png
    :width: 400px
    :align: center
    
.. hint::
  
  L'indicazione del *Row Datasource* è l'unico modo possibile per consentire il reperimento del dato in questo contesto. Non è necessario utilizzare una tabella, ma è possibile usare un qualsiasi *div*, corredato del parametro ``row_datasource``. 


Si segnala la possibilità di rendere una parte di testo subordinata alla presenza o meno di uno dei *parametri* o delle *variabili* utilizzati nel template. Per esempio, se si volesse mostrare la dicitura "Sconto applicato: $sconto" solo se lo sconto è effettivamente stato applicato, sarebbe sufficiente indicare nel testo::

  ${Sconto applicato: $sconto}
  
.. hint::
  Per ulteriori esempi di funzionamento del Template Editor si rimanda alle Genropill `"Come creare rapidamente una stampa unione" <https://www.genropy.org/blog/come-creare-una-stampa-unione/>`_ e `"Come rappresentare i dati di un record in un blocco template" <https://www.genropy.org/blog/come-rappresentare-i-dati-di-un-record-in-un-blocco-template/>`_

.. sectionauthor:: Davide Paci