Índice de contenidos
1. Entorno
-
- Hardware: Portátil MacBook Pro 15 pulgadas (2,5 GHz Intel Core i7, 16GB RAM)
- Sistema Operativo: MacOS Monterey 12.4
- Java 17
- Micronaut v3.5.3
- Micronaut Views Velocity v3.4.0
2. Introducción
¿Qué es Velocity?
Es un motor de plantillas basado en Java. Permite hacer páginas web con métodos definidos en código Java y su responsabilidad se centra en la capa de presentación.
Se puede usar como aplicación independiente o como componente integrado, alguno de sus usos son mails personalizados, pdf, XML’s dinámicos o cualquier otro tipo de salida de plantillas como JSON. Pero el uso más importante de Velocity es crear templates como html que serán la capa de presentación de una página web.
Ventajas
- Se adapta e integra a cualquier aplicación
- Plantillas con una sintaxis simple y clara, no siendo muy difícil su desarrollo
- Independencia entre plantillas y código
- Permite acceder a cualquier método público de objetos, esto es muy importante, ya que no se necesita crear objetos propios para las plantillas y permite reutilizar las clases existentes.
3. Conceptos Básicos
Velocity sigue un lenguaje particular llamado Lenguajes de Plantillas de Velocity (VTL), esto permite que un desarrollador con poca experiencia pueda rápidamente aprender a utilizar Velocity.
Se puede decir que hay dos tipos de elementos en Velocity, las referencias y las directivas. Las referencias empiezan por $ y se utilizan para obtener algo, las directivas comienzas por # y se utilizan para hacer algo.
Referencias
Hay 3 tipos de referencias:
- Variables: puede referirse a algo definido dentro del código Java u obtener su valor de un enunciado VTL.
Los nombres de las variables de Velocity están restringidos a los siguientes tipos de caracteres:-
- Alfabéticos (a-z, A-Z)
- Numéricos (0-9)
- Guion ( – )
- Guion bajo ( _ )
Ejemplo como asignar valor a una variable. El valor debe ir entre comillas y una vez que se asigna un valor esta variable se puede usar por todo el documento html.
#set( $a = "Velocity" )
-
- Propiedades: Se refieren a atributos de objetos o métodos. Se compone por el signo $ seguido de un identificador VTL, seguido de un punto y de otro identificador VTL.
Ejemplo:$ejemplo.texto
- Métodos: Son referencias compuestas de un signo $ inicial, seguido en un identificador VTL, seguido de un Cuerpo de Método VTL.
La diferencia principal entre las propiedades y los métodos es que se le puede dar una lista de parámetros a un Método.$ejemplo.setTitulo( "Titulo Ejemplo" ) $ejemplo.getTotal()
Notaciones de referencias
- Notación abreviada: es la que se utiliza normalmente y no requiere ninguna notación adicional, todos los ejemplos anteriores son con esta notación
$prueba - Notación formal: requiere llaves al inicio y final
${prueba} - Notación silenciosa: permite que en caso de que no tenga valor no se muestre nada por pantalla, requiere un signo de exclamación al inicio:
value="$!prueba"
Directivas
Permiten manipular la salida del código Java. Existen varios tipos, estos son alguno de ellos:
- #set: permite establecer el valor de una referencia
#set( $ejemplo = "valor" )
- #if-else: permite condiciones dentro de la plantilla. Requiere del elemento #end al final de la parte del código
#if( $ejemplo < 10 ) <strong>Primer texto</strong> #elseif( $ejemplo == 10 ) <strong>Segundo texto</strong> #elseif( $valor == 6 ) <strong>Tercer texto</strong> #else <strong>Último texto</strong> #end - #for-each: permite ciclos dentro de la plantilla. Requiere del elemento #end al final de la parte del código
<ul> #foreach( $valor in $valores ) <li>$valor</li> #end </ul> - #include: permite incluir en la plantilla un archivo local
#include( "archivo.txt" )
4. Integración con Micronaut
Como he dicho anteriormente, Velocity se puede integrar a muchos frameworks, permitiendo así encargarse de la parte de presentación de nuestra aplicación web. En el ejemplo que voy a explicar en este tutorial se va a utilizar Velocity con Micronaut, por lo que voy a explicar un poco como es imposible integrar Velocity junto con Micronaut.
Micronaut Views es un módulo de Micronaut que permite la representación de las vistas en el lado del servidor. Permite usar diferentes motores de plantilla como es nuestro caso con Velocity, será necesario incluir la dependencia correspondiente.
<dependency> <groupId>io.micronaut.views</groupId> <artifactId>micronaut-views-velocity</artifactId> <scope>compile</scope> </dependency>
Para relacionar nuestra vista de Velocity con el controlador correspondiente se debe establecer la anotación @View junto con el nombre del archivo de nuestra vista en el método correspondiente de nuestro controlador:
@Controller("/views")
class ViewsController {
@View("home")
@Get("/")
public HttpResponse index() {
return HttpResponse.ok();
}
}
5. Ejemplo
A continuación voy a explicar un ejemplo básico con Micronaut, Velocity y Maven. Este ejemplo consistirá en la visualización de las calificaciones de unas asignaturas, los datos de las calificaciones se crearán en un servicio llamado por un controlador que se conecta con una vista de Velocity y permite su visualización por pantalla.
Lo primero es incluir en nuestro pom las dependencias necesarias para nuestro ejemplo. Las más básicas para el uso de Micronaut y Velocity son las siguientes, aunque se pueden añadir las que se necesiten para cada caso:
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-inject</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-validation</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-http-server-netty</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-runtime</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.micronaut.views</groupId>
<artifactId>micronaut-views-velocity</artifactId>
<scope>compile</scope>
</dependency>
El controlador tendrá este aspecto:
@Controller("/")
class ViewsController {
private final AsignaturaService asignaturaService;
@Inject
public ViewsController(AsignaturaService asignaturaService) {
this.asignaturaService = asignaturaService;
}
@View("home")
@Get()
public HttpResponse<Map<String,Object>> index() {
Map<String, Object> map = new HashMap<>();
List<Asignatura> calificaciones = asignaturaService.getCalificaciones();
map.put("calificaciones",calificaciones);
return HttpResponse.ok(map);
}
}
@View("home"): enlazando con la vista correspondiente de Velocity- Devolvemos un Map para luego poder acceder fácilmente al elemento calificaciones en la vista, haciendo uso de la sentencia
$calificacionespropia de Velocity
Para la visualización de los datos debemos incluir en nuestra plantilla de Velocity lo siguiente:
<table>
<tr>
<th>Asignatura</th>
<th>Nota</th>
</tr>
#foreach($asignatura in $calificaciones)
#set($nota = $asignatura.getNota())
<tr class="fila">
<td>$asignatura.getNombre()</td>
#if($nota<5)
<td>$nota - SUSPENSO</td>
#elseif( $nota>=5 && $nota<6.99)
<td>$nota - APROBADO</td>
#elseif( $nota>=7 && $nota<8.99)
<td>$nota - NOTABLE</td>
#elseif( $nota>=9)
<td>$nota - SOBRESALIENTE</td>
#end
</tr>
#end
</table>
Hacemos uso de los elementos de Velocity como:
$calificaciones: accedemos directamente al elemento calificaciones de nuestro Map#foreach: para recorrer nuestra lista con las calificaciones e ir formando la tabla#set: para declarar la variable nota y poder usarla sin la necesidad de repetir código#if–#elseif: condición para poder trabajar con la nota recibida$asignatura.getNombre(): accedemos al método getNombre del objeto asignatura
Y añadiendo un poco de estilos de CSS, este sería el resultado final:
Puedes ver el código completo en mi repositorio de Github: velocity-micronaut-tutorial
6. Conclusiones
Trabajar con Velocity es muy fácil, solo hay que conocer los conceptos básicos y lenguaje para sus plantillas, y dependiendo del Framework que se use en el proyecto ver como es la integración. Como hemos visto en nuestro caso con Micronaut la integración es muy sencilla gracias a Micronaut Views.
El nivel de customización como todo es bastante amplio, pudiéndose adaptar a las necesidades de cada uno.
Y además, una de sus grandes ventajas es que permite llamar a métodos públicos Java de los objetos que estamos enviando a nuestra plantilla.
