NVelocity
NVelocity è il porting .NET di un template engine per java (Velocity).
AGGIORNAMENTO 17/01/2006: Suggerisco di scaricare l'assembly di NVelocity dal sito del progetto CastleProject, che ne ha fatto una fork e la tiene aggiornata, rimuovendo inoltre la dipendenza da una vecchia versione di Log4Net che in certi casi poteva essere fastidiosa. I sorgenti possono essere scaricati dal loro repositorio SVN:https://svn.castleproject.org/svn/castle/trunk (non sono inclusi nel pacchetto .msi) e si trovano nella directory Sandbox.
Con NVelocity è possibile fare una grande quantità di cose, ma quello per cui ho iniziato è la necessità di effettuare il merging di messaggi email per la gestione di un sistema di newsletter.
Email Merging
In altre parole, quando si invia una newsletter, è più professionale avere ogni email personalizzata a seconda del destinatario, pur avendo tutte le email un modello comune, ed evitando ovviamente di dover personalizzare tutti i messaggi _più o meno manualmente_.
Ad esempio potrebbe essere più carino inserire in testa al messaggio un saluto contenente nome e cognome del destinatario, e ancora più spesso è necessario inserire un link con una query string personalizzata che rimandi alla pagina di modifica delle opzioni di sottoscrizione...
Tutorial
NVelocity consente di fare tutto questo, ma manca enormemente di esempi e documentazione, perciò ho deciso di scrivere un breve tutorial per utilizzarlo velocemente.
Quello che vogliamo fare è scrivere una classe che può essere utilizzata da qualsiasi altra classe (ad esempio una pagina aspx) per generare un documento (ad esempio il testo di una email) sulla base di un modello.
- Innanzitutto scarichiamo NVelocity (AGGIORNAMENTO: dal sito di CastleProject perchè ne pubblicano una versione più aggiornata)
- Quindi aggiungiamo al progetto di visual studio in cui si trova la classe che utilizza NVelocity un riferimento a NVelocity.dll, che si trova nella directory "build" del archivio appena scaricato.
- Dopodichè creiamo un semplice template, utilizzando un linguaggio chiamato VTL (Velocity Template Language) [niente paura, per quello che dobbiamo fare non c'è bisogno di nessuna precedente conoscenza], che è il modello che vorremo in output. Supponiamo di voler personalizzare il messaggio email inserendo un saluto contenente nome e cognome del destinatario, anche se ovviamente è possibile inserire qualsiasi altro tipo di informazione.
L'unica cosa che è necessario sapere qui su VTL è che le variabili si indicano con $nomevariabile, nient'altro.
Ecco il nostro template:
Ciao $firstName $surname,
ecco una email di prova creata e personalizzata con NVelocity!
Possiamo scriverlo con Notepad, e poi lo salviamo ad esempio in una cartella chiamata "templates" presente nella root del nostro progetto web come miotemplate.vm.
- Ora scriviamo la nostra classe:
using System;
using System.IO;
using System.Web;
using NVelocity;
using NVelocity.App;
using NVelocity.Exception;
using NVelocity.Runtime;
namespace MioProgetto
{
public class NVelocityTemplateEngine
{
static NVelocityTemplateEngine()
{
// IMPORTANTE: specificare la directory del file system in cui si trovano i file template
// Ad esempio, supponiamo di metterli in una cartella chiamata "templates" nella root del progetto web
Velocity.SetProperty( RuntimeConstants_Fields.FILE_RESOURCE_LOADER_PATH,
HttpContext.Current.Server.MapPath("~/templates"));
// Se non specifichiamo altre proprietà a runtime, NVelocity utilizzerà quelle di default
// Inizializziamo NVelocity
Velocity.Init();
}
public static string Process(string nome, string cognome)
{
// Creiamo un oggetto VelocityContext, simile in qualche modo ad HttpContext
// Serve per contenere gli oggetti di cui fare il merging nel template
VelocityContext context = new VelocityContext();
StringWriter writer = new StringWriter();
// Inseriamo i nostri dati in context
context.Put("firstName", nome);
context.Put("surname", cognome);
try
{
Template template = Velocity.GetTemplate("miotemplate.vm");
template.Merge(context, writer);
}
catch (ResourceNotFoundException)
{
// il template non è stato trovato
}
catch (ParseErrorException)
{
// errore durante il merging del template
}
return writer.GetStringBuilder().ToString();
}
}
}
- Infine, per utilizzarlo, è sufficiente passare al metodo Process i dati che vogliamo siano inseriti nella stringa di output:
string output = NVelocityTemplateEngine.Process("Simone", "Busoli");
Nella stringa output otterremo quindi:
Ciao Simone Busoli,
ecco una email di prova creata e personalizzata con NVelocity!