[Spring + Thymeleaf] 레이아웃 구조 쉽게 잡기

Spring

[Spring + Thymeleaf] 레이아웃 구조 쉽게 잡기

🌟 Sean 🌟 2025. 6. 20. 17:32

웹 플랫폼에 접속해보면, 사이드 메뉴와 상단 헤더는 고정된 채로 가운데의 콘텐츠 영역만 바뀌는 구조를 자주 볼 수 있다

이처럼 레이아웃의 일관성을 유지하면서도 각 페이지의 콘텐츠를 효율적으로 관리하려면, Spring 프로젝트에서 Thymeleaf의 레이아웃 기능을 활용하는 것이 매우 유용합니다. 유지보수와 확장성 측면에서도 큰 장점을 갖고 있다.

실제 플랫폼 프로젝트를 개발하면서 이러한 구조를 적용한 경험이 있으며, 과제와 연습 겸 비슷한 레이아웃을 다시 설정해보는 과정에서 몇 가지 중요하지만 놓치기 쉬운 포인트들을 발견했다

이 포스팅에서는 제가 직접 겪은 시행착오를 바탕으로, 레이아웃 설정 시 주의할 점과 핵심 내용을 공유하고자 합니다.

1. Thymeleaf 의존성 주입

Thymeleaf는 Spring Boot에서 가장 많이 사용되는 템플릿 엔진 중 하나이다. 정적 HTML을 동적으로 렌더링해주며, 뷰(View)와 데이터를 자연스럽게 연결할 수 있도록 도와준다.

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

2. Layout Dialect 의존성 추가

Thymeleaf로 레이아웃 템플릿을 설정하려고 layout:decorate를 쓰는데 계속 적용이 안 되었다....

중요 ★ ★ ★ ★

dependencies {
    implementation 'nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect:3.0.0'
}

3. 부모 템플릿 basic.html 레이아웃 설정

basic.html은 모든 페이지의 공통 구조를 정의하는 부모 레이아웃이다.
즉, 헤더와 사이드바는 고정이고, <main> 부분은 자식 페이지에서 삽입되는 구조로 설정한다.

<!DOCTYPE html>
<html lang="ko" xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
    xmlns:sec="http://www.thymeleaf.org/extras/spring-security">

<head>
    <meta charset="UTF-8">
    .
    .
    <style>
    .
    .
    </style>
</head>

<body>

    <!-- 좌측 사이드바 -->
    <div class="sidebar p-3">
        <ul class="nav flex-column">
            <li class="nav-item">
                <a class="nav-link" th:href="@{/home}"><i class="bi bi-house"></i> 홈</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" th:href="@{/list}"><i class="bi bi-list-ul"></i> 게시판</a>
            </li>
        </ul>
    </div>

    <!-- 헤더 영역 -->
    <div class="header">
	.
    .
    </div>
    <main class="main-content">
        <div layout:fragment="home"></div>
        <div layout:fragment="content"></div>
    </main>
</body>
<div layout:fragment="script"></div>
</html>

4. Thymeleaf 레이아웃에서 가장 중요한 핵심 포인트

<main class="main-content">
    <div layout:fragment="home"></div>
    <div layout:fragment="content"></div>
</main>

layout:fragment는 부모 템플릿에서 자식 템플릿이 내용을 "삽입할 위치"를 정의하는 핵심 지점이다.
이 이름과 자식 페이지의 layout:fragment 값이 정확히 매칭되어야 콘텐츠가 정상적으로 렌더링된다.

5. 자식 페이지 구조

ⓐ 자식 페이지 최상단 <html> 태그에 아래와 같이 지정하여 부모 레이아웃을 상속 받는다.

layout:decorate="~{layout/basic}"

ⓑ 자식 페이지의 <body> 태그 안에서 layout:fragment=" fragment 이름 " 속성으로 영역을 감싸고, 그 안에 표시할 내용을 작성한다.

<div layout:fragment="content">
  <!-- 자식 페이지에서 보여줄 실제 내용 -->
</div>

<!DOCTYPE html>
<html lang="ko"
      xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
      layout:decorate="~{layout/basic}">
<head>
  <meta charset="UTF-8">
  <title>게시판</title>
  <style>
  .
  .
  </style>
</head>
<body>
    <div layout:fragment="content">
        <-- 보여줄 실제 내용 -->
    </div>
</body>

</html>

6. Thymeleaf 레이아웃 구성 시 자식 페이지 작성 시 유의사항

부모 레이아웃(basic.html)에는 <html>, <head>, <body> 태그가 포함되어 있음
자식 페이지에서는 콘텐츠만 layout:fragment로 작성하며, 별도의 <body> 태그 작성은 생략하는 것이 일반적
자식 페이지에 <body> 태그를 포함할 경우, 부모 레이아웃과 중복되어 충돌이 발생할 수 있으므로 권장하지 않음