타임리프(Thymeleaf) 개발자 가이드

타임리프와 스프링 부트를 활용하는 웹 개발

 

타임리프(Thymeleaf)는 서버 사이드 Java 템플릿 엔진으로, HTML 파일을 동적으로 생성하여 웹 페이지를 구축하는 데 사용됩니다. 주로 스프링 MVC와 함께 사용되며, HTML을 자연스럽게 템플릿으로 활용하여 프론트엔드와 백엔드 개발자 간 협업이 용이합니다.

 

이 가이드에서는 타임리프의 설정부터 주요 기능 및 다양한 활용 방법을 소개하겠습니다.

1. 타임리프 설정하기

타임리프를 스프링 부트 프로젝트에 설정하려면, 일반적으로 의존성 관리 도구를 사용하여 의존성을 추가합니다. 스프링 부트를 사용할 경우, spring-boot-starter-thymeleaf를 통해 쉽게 통합할 수 있습니다.

 

스프링 부트 프로젝트에 타임리프 추가

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
}

• 스프링 부트를 사용하면 위의 의존성만 추가하면 자동으로 타임리프와 스프링을 연동할 수 있습니다.

타임리프 설정 구성

스프링 부트에서는 타임리프 설정을 쉽게 커스터마이즈할 수 있습니다. 기본적으로 스프링 부트는 application.properties 또는 application.yml 파일에서 타임리프 관련 설정을 관리합니다.

 

다음은 타임리프 설정에서 자주 사용되는 몇 가지 구성 옵션입니다:

# Thymeleaf 템플릿 파일 경로 설정
spring.thymeleaf.prefix=classpath:/templates/

# 템플릿 파일의 접미사 설정
spring.thymeleaf.suffix=.html

# 캐시 설정 - 개발 중에는 false로 설정하여 변경 사항이 즉시 반영되도록 함
spring.thymeleaf.cache=false

# HTML 파일을 그대로 볼 수 있도록 타임리프의 타임리프 모드 설정
spring.thymeleaf.mode=HTML

# UTF-8 인코딩 설정
spring.thymeleaf.encoding=UTF-8

# 타임리프 템플릿 파일을 뷰로 사용하기 위한 Content-Type 설정
spring.thymeleaf.content-type=text/html

• spring.thymeleaf.prefix: 템플릿 파일의 기본 경로를 설정합니다. 일반적으로 템플릿은 classpath:/templates/ 폴더에 위치합니다.
• spring.thymeleaf.suffix: 템플릿 파일의 확장자를 지정합니다. 보통 .html을 사용합니다.
• spring.thymeleaf.cache: 템플릿 캐시를 사용할지 여부를 설정합니다. 개발 환경에서는 false로 설정하여 코드 변경 사항이 즉시 반영되도록 합니다.
• spring.thymeleaf.mode: 템플릿 모드를 설정합니다. HTML 파일을 브라우저에서 바로 열 수 있도록 HTML 모드를 주로 사용합니다.
• spring.thymeleaf.encoding: 템플릿 파일의 인코딩을 설정합니다. 일반적으로 UTF-8을 사용합니다.
• spring.thymeleaf.content-type: 응답 헤더에 설정될 Content-Type을 정의합니다. 보통 text/html로 설정합니다.

타임리프 뷰 리졸버(View Resolver) 설정

스프링 부트는 자동으로 타임리프 뷰 리졸버를 구성하지만, 커스터마이징이 필요할 경우 WebMvcConfigurer를 구현하여 설정할 수 있습니다. 뷰 리졸버는 클라이언트의 요청을 적절한 템플릿으로 매핑하는 역할을 합니다.

 

다음은 뷰 리졸버를 수동으로 설정하는 예시입니다:

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewResolverRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class ThymeleafConfig implements WebMvcConfigurer {
    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.jsp("/WEB-INF/views/", ".jsp");
    }
}

• 위의 예시는 타임리프가 아닌 JSP에 대한 설정이지만, 비슷한 방식으로 타임리프에 대한 설정도 가능합니다. 스프링 부트에서는 대부분의 경우 기본 뷰 리졸버 설정을 사용하는 것으로 충분합니다.

타임리프와 스프링 부트의 자동 설정

스프링 부트는 타임리프와의 통합을 위한 자동 설정을 제공합니다. spring-boot-starter-thymeleaf 의존성을 추가하면, 스프링 부트는 타임리프 템플릿을 사용하기 위해 자동으로 다음을 구성합니다:

• 뷰 리졸버(View Resolver): 스프링 MVC에서 요청을 처리하고 템플릿 파일을 반환하는 데 필요한 설정.
• 메시지 소스(Message Source): 국제화를 지원하는 메시지 번들을 설정하여 다국어 처리를 용이하게 합니다.
• 템플릿 엔진(Template Engine): HTML 파일을 파싱하고, 모델 데이터를 결합하여 최종 HTML을 생성하는 역할을 합니다.

스프링 부트의 자동 설정 덕분에 타임리프를 바로 사용할 수 있고, 필요에 따라 설정을 application.properties 파일을 통해 손쉽게 수정할 수 있습니다

2. 기본적인 타임리프 문법

타임리프는 HTML 파일에서 동적으로 데이터를 표현할 수 있도록 다양한 속성과 표현식을 제공합니다. 타임리프의 주요 기능과 속성을 살펴보겠습니다.

 

텍스트 삽입 (th:text)

• th:text 속성을 사용하여 HTML 태그 내부의 텍스트를 동적으로 설정합니다.

<p th:text="${user.name}">사용자 이름</p>

• 위 코드에서 ${user.name}은 모델 객체 user의 name 필드를 출력합니다.

URL 링크 (th:href)

• 동적 URL을 생성하기 위해 th:href 속성을 사용합니다.

<a th:href="@{/home}">홈으로 이동</a>

• 여기서 @{/home}은 기본 경로를 가리키며, 경로 변수도 쉽게 추가할 수 있습니다.

반복문 (th:each)

• th:each를 사용하여 컬렉션을 순회하면서 HTML 요소를 반복 생성할 수 있습니다.

<ul>
    <li th:each="item : ${items}" th:text="${item}">아이템</li>
</ul>

• items는 컨트롤러에서 전달된 컬렉션이며, 각 item에 대해 <li> 요소가 생성됩니다.

조건부 렌더링 (th:if, th:unless)

• 조건에 따라 HTML 요소를 표시하거나 숨기기 위해 th:if 또는 th:unless를 사용합니다.

<p th:if="${user != null}">환영합니다, <span th:text="${user.name}">사용자 이름</span>님!</p>
<p th:unless="${user != null}">로그인 해주세요.</p>

• th:if와 th:unless는 각각 조건이 참이거나 거짓일 때만 해당 요소를 렌더링합니다.

3. 타임리프 컨셉 이해하기

타임리프는 "자연 템플릿(Natural Templates)" 개념을 사용합니다. 즉, 타임리프 템플릿은 브라우저에서 유효한 HTML 파일로 동작합니다. 이러한 특성 덕분에 프론트엔드 개발자와의 협업이 쉬워지며, HTML 파일을 직접 브라우저에서 확인할 수 있습니다.

 

표현식 언어

타임리프는 여러 유형의 표현식을 통해 데이터를 다룰 수 있습니다:

• 변수 표현식 (${}): 모델 데이터를 출력합니다. 예: ${user.name}
• URL 표현식 (@{}): 동적 URL 생성. 예: @{/user/{id}(id=${user.id})}
• 메시지 표현식 (#{}): 국제화 메시지 처리. 예: #{welcome.message}
• 프래그먼트 표현식 (~{}): 다른 템플릿의 특정 부분을 삽입할 때 사용. 예: ~{fragments/header :: site-header}

4. 타임리프와 스프링 MVC 통합

타임리프는 주로 스프링 MVC 컨트롤러와 함께 사용됩니다. 컨트롤러에서 데이터를 모델에 담아 전달하면, 타임리프 템플릿에서 이를 동적으로 렌더링할 수 있습니다.

 

컨트롤러 예시

@Controller
public class UserController {
    @GetMapping("/profile")
    public String profile(Model model) {
        User user = new User("John", 30);
        model.addAttribute("user", user);
        return "profile";
    }
}

• 위의 예시에서 컨트롤러는 user 객체를 모델에 추가하고, profile.html 템플릿을 반환합니다. 타임리프 템플릿은 모델의 데이터를 렌더링합니다.

5. 타임리프의 레이아웃 기능 (프래그먼트와 재사용)

타임리프는 프래그먼트(Fragments)라는 개념을 통해 HTML의 특정 부분을 재사용할 수 있습니다. 예를 들어, 모든 페이지에 공통으로 포함되는 헤더와 푸터를 별도의 파일로 관리할 수 있습니다.

 

프래그먼트 정의와 사용

• 프래그먼트 정의 (header.html):

<div th:fragment="site-header">
    <header>
        <h1>사이트 헤더</h1>
    </header>
</div>

• 프래그먼트 사용 (main.html):

<div th:insert="~{fragments/header :: site-header}"></div>

• 이와 같은 방식으로 중복을 줄이고 유지보수를 쉽게 할 수 있습니다.

6. 타임리프 레이아웃

타임리프는 간단한 레이아웃 재사용 외에도 다양한 고급 레이아웃 기술을 제공하여 복잡한 페이지 구조를 쉽게 관리할 수 있도록 돕습니다. 이 섹션에서는 타임리프의 고급 레이아웃 기능을 다룹니다.

6.1 타임리프 레이아웃 구성 예시

타임리프의 레이아웃을 구성하는 구체적인 예제를 통해 이해를 돕겠습니다. 레이아웃을 사용하여 페이지의 일관성을 유지하면서 반복적인 요소를 쉽게 관리할 수 있습니다.

• 레이아웃 템플릿 (layouts/default.html):

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
    <meta charset="UTF-8">
    <title th:text="${pageTitle}">기본 페이지 제목</title>
    <link rel="stylesheet" href="/css/style.css" />
</head>
<body>
    <header layout:fragment="header">
        <nav>
            <ul>
                <li><a href="/home">Home</a></li>
                <li><a href="/about">About</a></li>
                <li><a href="/contact">Contact</a></li>
            </ul>
        </nav>
    </header>
    <main layout:fragment="content">
        <!-- 기본 콘텐츠가 여기에 들어갑니다 -->
    </main>
    <footer layout:fragment="footer">
        <p>Copyright &copy; 2024 My Website</p>
    </footer>
</body>
</html>

• 페이지별 콘텐츠 템플릿 (views/home.html):
  • 이 예시에서 home.html은 기본 레이아웃 default.html을 사용하여 페이지의 일관된 구조를 유지하며, 콘텐츠 부분만 정의합니다.

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
layout:decorate="~{layouts/default}">
<head>
    <title>홈페이지</title>
</head>
<body>
    <div layout:fragment="content">
        <h2>환영합니다!</h2>
        <p>이곳은 홈페이지입니다. 최신 소식을 확인하세요.</p>
    </div>
</body>
</html>

6.2 레이아웃 인클루드와 리플레이스 (th:insert와 th:replace)

• th:insert와 th:replace는 다른 템플릿의 특정 프래그먼트를 현재 페이지에 포함시키거나 대체하는 데 사용됩니다.
  • th:insert: 다른 템플릿을 현재 요소 내부에 삽입합니다. 이 방식은 HTML 구조를 그대로 유지합니다.

    <div th:insert="~{fragments/sidebar :: sidebar}"></div>

  • th:replace: 해당 요소를 다른 템플릿의 내용으로 완전히 대체합니다. 이를 통해 HTML 구조를 효율적으로 변경할 수 있습니다.

    <div th:replace="~{fragments/header :: site-header}"></div>

6.3 다중 프래그먼트 포함

타임리프에서는 여러 프래그먼트를 한 번에 포함할 수 있습니다. 이를 통해 복잡한 레이아웃을 좀 더 유연하게 구성할 수 있습니다.

<div th:insert="~{fragments/header :: site-header}, ~{fragments/sidebar :: sidebar}"></div>

• 위 예시는 header와 sidebar 프래그먼트를 모두 삽입하는 방식으로, 페이지의 여러 부분을 구성하는 데 유용합니다.

6.4 레이아웃의 동적 데이터 바인딩

레이아웃을 정의하면서 동적 데이터 바인딩도 가능합니다. 예를 들어, 페이지 제목이나 메타데이터를 공통 레이아웃 파일에서 정의하고 각 페이지에서 동적으로 변경할 수 있습니다.

<head>
    <title th:text="${pageTitle}">기본 제목</title>
</head>

• 각 페이지 템플릿에서 pageTitle 값을 모델에 담아 전달하면, 레이아웃 파일에서 동적으로 제목이 변경됩니다.

728x90

7. 폼 처리하기 (Form Handling)

타임리프는 폼 데이터를 처리하는 데 유용한 기능을 제공합니다. th:object를 사용하여 폼 객체를 설정하고, th:field를 통해 필드를 자동으로 바인딩할 수 있습니다.

<form th:action="@{/save}" th:object="${user}" method="post">
    <label for="name">이름:</label>
    <input type="text" id="name" th:field="*{name}" />
    <button type="submit">저장하기</button>
</form>

• 위의 폼은 user 객체와 바인딩되어, 폼 제출 시 자동으로 해당 객체의 필드 값이 업데이트됩니다.

8. 타임리프 유틸리티 객체

타임리프는 다양한 유틸리티 객체를 제공합니다:

• #dates: 날짜 관련 유틸리티. 예: #dates.format(localDate, 'yyyy-MM-dd')
• #numbers: 숫자 포맷 관련 유틸리티. 예: #numbers.formatDecimal(1234.56, 2, 'COMMA')
• #strings: 문자열 조작. 예: #strings.capitalize(user.name)

9. 타임리프의 국제화 (i18n)

타임리프는 국제화를 지원하여 다국어 웹 애플리케이션을 쉽게 개발할 수 있도록 도와줍니다. 메시지 번들 파일에 문자열을 정의하고, 이를 #{} 표현식을 통해 템플릿에서 사용할 수 있습니다.

<p th:text="#{welcome.message}">기본 환영 메시지</p>

• messages.properties 파일에서 welcome.message=환영합니다!를 정의하면, 타임리프가 이를 템플릿에 출력합니다.