HTMX 통합
필수 의존성: io.ktor:ktor-htmx, io.ktor:ktor-htmx-html, io.ktor:ktor-server-htmx
코드 예제: htmx-integration
HTMX는 HTML 속성을 사용하여 동적인 클라이언트 측 동작을 가능하게 하는 경량 JavaScript 라이브러리입니다. JavaScript를 작성하지 않고도 AJAX, CSS 트랜지션(transition), WebSocket, Server-Sent Events와 같은 기능을 지원합니다.
Ktor는 서버와 클라이언트 컨텍스트 모두에서 통합을 간소화하는 공통 모듈 세트를 통해 HTMX에 대한 실험적인 일급(first-class) 지원을 제공합니다. 이러한 모듈은 HTMX 헤더 작업, Kotlin DSL을 사용한 HTML 속성 정의, 서버에서의 HTMX 전용 라우팅 로직 처리 등을 위한 도구를 제공합니다.
모듈 개요
Ktor의 HTMX 지원은 세 가지 실험적 모듈을 통해 제공됩니다:
| 모듈 | 설명 |
|---|---|
ktor-htmx | 핵심 정의 및 헤더 상수 |
ktor-htmx-html | Kotlin HTML DSL과의 통합 |
ktor-server-htmx | HTMX 전용 요청에 대한 라우팅 지원 |
모든 API는 @ExperimentalKtorApi로 표시되어 있으며, @OptIn(ExperimentalKtorApi::class)를 통한 사용 동의가 필요합니다.
HTMX 헤더
핵심 모듈인 ktor-htmx에서 제공하는 미리 정의된 상수를 사용하여 타입 안전한 방식으로 HTMX 헤더에 접근하거나 설정할 수 있습니다. 이러한 상수를 사용하면 트리거(trigger), 기록 복구(history restoration) 또는 콘텐츠 스왑(content swapping)과 같은 HTMX 동작을 감지할 때 매직 문자열(magic string) 사용을 피할 수 있습니다.
요청 헤더(Request headers)
애플리케이션에서 HTMX 요청 헤더를 읽거나 일치시키려면 HxRequestHeaders 객체를 사용하십시오:
true입니다.응답 헤더(Response headers)
HxResponseHeaders 객체를 사용하여 HTMX 응답 헤더용 상수에 접근할 수 있습니다:
스왑 모드(Swap modes)
ktor-htmx 핵심 모듈의 HxSwap 객체를 사용하여 다양한 HTMX 스왑 모드 상수에 접근할 수 있습니다.
HTML DSL 확장
ktor-htmx-html 모듈은 Kotlin의 HTML DSL에 확장 함수를 추가하여 HTML 요소에 HTMX 속성을 직접 추가할 수 있게 해줍니다:
@OptIn(ExperimentalKtorApi::class)
html {
body {
button {
attributes.hx {
get = "/data"
target = "#result"
swap = HxSwap.outerHtml
trigger = "click"
}
+"Load Data"
}
}
}위의 예제는 다음과 같은 HTMX 속성이 포함된 HTML을 생성합니다:
<button hx-get="/api/data" hx-target="#result-div" hx-swap="outerHTML" hx-trigger="click">Load Data</button>서버 측 라우팅
ktor-server-htmx 모듈은 hx DSL 블록을 통해 HTMX를 인식하는 라우팅을 제공합니다:
@OptIn(ExperimentalKtorApi::class)
routing {
route("api") {
// 일반 라우트 (HTMX 및 비 HTMX 요청 모두 해당)
get {
call.respondText("Regular response")
}
// HTMX 요청만 일치 (HX-Request 헤더가 있는 경우)
hx.get {
call.respondText("HTMX response")
}
// 특정 대상을 가진 HTMX 요청과 일치
hx {
target("#result-div") {
get {
call.respondText("Response for #result-div")
}
}
// 특정 트리거를 가진 HTMX 요청과 일치
trigger("#load-button") {
get {
call.respondText("Response for #load-button clicks")
}
}
}
}
}이러한 기능을 사용하면 클라이언트가 보낸 HTMX 헤더에 따라 애플리케이션이 다르게 응답하도록 만들 수 있습니다.