Thymeleaf — es un motor de plantillas moderno para Java, que ofrece una forma cómoda y flexible de crear páginas HTML dinámicas. Se integra con Spring MVC y soporta renderizado de doble vía: los archivos HTML pueden usarse como plantillas estáticas (por ejemplo, para probar el front-end) y también como páginas generadas dinámicamente en el servidor.
Thymeleaf — un ayudante inteligente en el desarrollo web
¿Sabes por qué los desarrolladores adoran Thymeleaf? Hace que el código HTML sea vivo y dinámico. Imagínate: escribes HTML normal y solo le añades unos atributos especiales — ese es todo el truco. Incluso si el servidor no está funcionando, el navegador igual mostrará tu código sin errores.
Además Thymeleaf es bueno porque encaja en cualquier proyecto. No importa si haces una página simple o un portal complejo. Y sí, con Spring se lleva bien desde el primer momento.
¿Quieres entender cómo funciona? Es parecido a crear un juego. Tienes una plantilla HTML — es como el esqueleto del juego. Y los datos son como los recursos del juego. Thymeleaf toma ese esqueleto y lo anima, justo como un motor de juego. Coloca los datos donde hace falta, añade efectos y transforma el código simple en una página dinámica completa.
Conectar Thymeleaf en un proyecto Spring MVC
Dependencias Maven. Para empezar hay que añadir Thymeleaf a tu proyecto. Agrega en el pom.xml la siguiente dependencia:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
Si usas Gradle, añade la siguiente línea en build.gradle:
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
Estructura del proyecto. Tras añadir Thymeleaf aparecerá un nuevo directorio para las plantillas. Por defecto es:
src/main/resources/templates
Todas tus plantillas HTML deben guardarse en ese directorio. Spring Boot las "verá" y las cargará automáticamente.
Fundamentos de la sintaxis de Thymeleaf
Extender HTML con atributos. Thymeleaf usa atributos propios que comienzan con th:. Por ejemplo:
- th:text — para mostrar texto.
- th:href — para enlaces.
- th:each — para bucles.
- th:if/th:unless — para condiciones.
Ejemplo más sencillo
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>¡Hola, Thymeleaf!</title>
</head>
<body>
<h1>Bienvenido, <span th:text="${username}"></span>!</h1>
</body>
</html>
Aquí th:text="${username}" reemplazará el contenido del span por el valor de la variable username pasada desde el controlador.
Pasar datos desde el controlador
Creemos un controlador sencillo que pase datos a la plantilla.
@Controller
public class WelcomeController {
@GetMapping("/")
public String welcome(Model model) {
model.addAttribute("username", "Programador Junior");
return "welcome"; // indica la plantilla welcome.html
}
}
Nota:
- Usamos el objeto
Modelpara pasar datos a la plantilla. - El valor retornado
return "welcome";indica el archivowelcome.htmlen la carpetatemplates.
Ejemplo de plantilla HTML (welcome.html)
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Bienvenido</title>
</head>
<body>
<h1>¡Hola, <span th:text="${username}"></span>!</h1>
</body>
</html>
Si abres el navegador verás:
¡Hola, Programador Junior!
Tablas dinámicas con Thymeleaf
Vamos a hacer algo un poco más avanzado. Por ejemplo, muestra una lista de estudiantes en forma de tabla.
Controlador
@Controller
public class StudentController {
@GetMapping("/students")
public String listStudents(Model model) {
List<String> students = List.of("Anna", "Ivan", "Maria", "Sergey");
model.addAttribute("students", students);
return "students"; // plantilla students.html
}
}
Usamos el método de Java 9+ List.of(...) para simplificar.
Plantilla (students.html)
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Lista de estudiantes</title>
</head>
<body>
<h1>Lista de estudiantes</h1>
<table border="1">
<thead>
<tr>
<th>Nombre</th>
</tr>
</thead>
<tbody>
<tr th:each="student : ${students}">
<td th:text="${student}"></td>
</tr>
</tbody>
</table>
</body>
</html>
Aquí:
th:each="student : ${students}"— itera sobre la colecciónstudents.- Dentro del bucle mostramos el nombre del estudiante con
th:text="${student}".
Resultado en el navegador:
Lista de estudiantes
-------------------
Nombre
Anna
Ivan
Maria
Sergey
Condicionales en Thymeleaf
A veces necesitas mostrar u ocultar elementos según condiciones.
Ejemplo usando th:if y th:unless
<p th:if="${isAdmin}">¡Bienvenido, administrador!</p>
<p th:unless="${isAdmin}">¡Bienvenido, usuario!</p>
En el controlador:
model.addAttribute("isAdmin", true);
Resultado. Si isAdmin = true, verás:
¡Bienvenido, administrador!
Crear hipervínculos
Thymeleaf permite crear fácilmente enlaces usando rutas.
Ejemplo
<a th:href="@{/students}">Lista de estudiantes</a>
Salida:
<a href="/students">Lista de estudiantes</a>
El uso de @{} también sirve para parámetros dinámicos:
<a th:href="@{/student/{id}(id=${studentId})}">Ver estudiante</a>
Integración de formularios con Thymeleaf
Thymeleaf soporta trabajar con formularios HTML. Esto es especialmente útil para recoger datos de usuarios.
Ejemplo de controlador
@Controller
public class FormController {
@GetMapping("/form")
public String showForm(Model model) {
model.addAttribute("student", new Student());
return "form";
}
@PostMapping("/form")
public String processForm(@ModelAttribute Student student) {
System.out.println("Estudiante recibido: " + student);
return "form-success";
}
}
Plantilla del formulario (form.html)
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Formulario</title>
</head>
<body>
<form action="#" th:action="@{/form}" th:object="${student}" method="post">
Nombre: <input type="text" th:field="*{name}"><br>
Edad: <input type="number" th:field="*{age}"><br>
<button type="submit">Enviar</button>
</form>
</body>
</html>
th:action y
th:field para el bind automático al modelo a través del objeto
student.
Consejos útiles y errores típicos
La mayoría de errores al usar Thymeleaf vienen de:
- Falta de dependencias. Comprueba que tienes incluida la dependencia
spring-boot-starter-thymeleaf. - Estructura de directorios incorrecta. Asegúrate de que las plantillas HTML estén en la carpeta
resources/templates. - Error en la sintaxis de Thymeleaf. Revisa que los atributos
th:*estén bien escritos.
Para profundizar puedes consultar la documentación oficial de Thymeleaf.
GO TO FULL VERSION