Variabili Template

🚧 BOZZA

Le variabili template sono placeholder dinamici utilizzabili nei contenuti delle notifiche.

---

🧠 Concetti chiave

Le variabili template sono campi dinamici che possono essere inseriti nei contenuti dei canali di notifica. Permettono di personalizzare i messaggi con dati specifici dell'utente, del progetto, del contratto o di altre entità del sistema.

Ogni variabile template è composta da:

• Nome: Il nome descrittivo della variabile (es. "Nome Utente", "Indirizzo Progetto")
• Slug: L'identificatore utilizzato nei placeholder (es. user_name, project_address)
• Categoria: Determina la provenienza/tipologia della variabile:
  • Core: Dati di sistema (es. nome piattaforma, email supporto)
  • User: Dati dell'utente (es. nome, email, ruolo)
  • Project: Dati della commessa (es. indirizzo, importo)
  • Customer: Dati del cliente
  • Company: Dati dell'impresa
  • Supplier: Dati del fornitore
  • Professional: Dati del professionista
  • Contract: Dati del contratto
  • Signatures: Dati relativi alle firme
  • Attachments: Allegati
  • Date: Date specifiche
• Tipo: Il formato del valore:
  • text: Testo semplice
  • email: Indirizzo email
  • date: Data (formato YYYY-MM-DD)
  • datetime: Data e ora
  • number: Numero
  • currency: Importo in valuta
  • boolean: Vero/Falso
  • fiscal_code: Codice fiscale
  • vat_number: Partita IVA
  • province: Provincia
  • country: Paese
• Descrizione: Spiegazione di cosa rappresenta la variabile
• Placeholder: Testo di esempio per aiutare nella compilazione

---

🔄 Utilizzo nei contenuti

Le variabili possono essere utilizzate nei contenuti dei canali con due formati:

Formato 1: HTML Span (nei body/title)

Ciao <span>@user_name</span>,
hai un nuovo contratto: <span>@contract_name</span>

Formato 2: Doppie graffe (negli URL)

https://app.com/contracts/{{contract_id}}

---

🎯 Gestione delle variabili per categoria

Variabili CORE

Le variabili di categoria core contengono dati di sistema che vengono forniti automaticamente:

• Sono sempre disponibili in tutte le notifiche
• Il loro valore è costante e configurato a livello di sistema
• Non richiedono input dal modulo che invia la notifica

Esempi:

• platform_name: Nome della piattaforma
• platform_email: Email di supporto
• platform_phone: Telefono del supporto

Variabili CONTESTUALI

Tutte le altre categorie sono contestuali e dipendono dal contesto in cui viene inviata la notifica:

• Vengono fornite dal modulo che invia la notifica
• Possono essere passate esplicitamente come array di valori
• Possono essere risolte automaticamente dal contesto usando NtVariableResolver

Esempi:

• user_name, user_email (categoria: User)
• project_address, project_amount (categoria: Project)
• contract_name, contract_status (categoria: Contract)

---

⚙️ Risoluzione automatica dal contesto

Quando si passa un contesto invece di variabili esplicite, il NtVariableResolver estrae automaticamente i valori:

NtNotificationService::send(
    NotificationClass::class,
    [],
    [],
    ['user' => $user, 'contract' => $contract, 'project' => $project]
);

Il resolver:

1. Legge le variabili associate al template dal database
2. Per ogni variabile, identifica l'entità corrispondente nel contesto in base alla categoria
3. Estrae il valore dall'entità usando la configurazione della variabile
4. Formatta il valore in base al tipo (date → "01/01/2025", currency → "1.500,00 €", ecc.)

---

📝 Associazione variabili ai template

Le variabili vengono associate ai template tramite la tabella pivot nt_notification_variable_template:

• Un template può avere molte variabili associate
• Una variabile può essere usata in molti template
• Solo le variabili associate al template sono disponibili per la sostituzione nei contenuti

In piattaforma è possibile:

• Visualizzare tutte le variabili disponibili
• Filtrare per categoria
• Associare/dissociare variabili dai template
• Vedere quali variabili sono utilizzate in quali template

Logiche rilevanti

• Le variabili sono create lato codice e memorizzate nel database
• Solo le variabili associate al template tramite la pivot possono essere utilizzate
• Il NtVariableResolver gestisce la risoluzione automatica dal contesto
• In strict mode, se una variabile richiesta non viene trovata, viene lanciata un'eccezione
• Il tipo della variabile determina come viene formattato il valore (es. date → formato italiano, currency → formato con simbolo €)
• Le variabili di categoria core devono essere sempre fornite dal sistema

---

🔧 Formattazione dei valori

Il NtVariableResolver formatta automaticamente i valori in base al tipo:

Tipo	Formato Output	Esempio
text	Testo semplice	"Mario Rossi"
email	Email	"mario@example.com"
date	gg/mm/aaaa	"15/03/2025"
datetime	gg/mm/aaaa HH:mm	"15/03/2025 14:30"
number	Numero formattato	"1.500"
currency	Importo con simbolo	"1.500,00 €"
boolean	Sì/No	"Sì" o "No"
fiscal_code	Maiuscolo	"RSSMRA80A01H501Z"
vat_number	Formattato	"IT12345678901"

---