formalize use of HTMX templates (#82)

Author: wakingrufus

docs/htmx.md

@@ -47,6 +47,19 @@ class TestKotlinApplication : SpringFunkApplication {
 }
 ```
 
+### Templates
+Templates can be declared which define how a given binding response should be rendered to htmx.
+
+```kotlin
+val myTemplate = htmxTemplate<ResponseDataClass> {
+    div {
+        span {
+            +it.name
+        }
+    }
+}
+```
+
 ### Initial Load
 
 You must declare the "landing page" for each page, which is the initial content to show on load. The `initialLoad` function lets you do this, which exposes the HTML DSL to define that view.
@@ -88,17 +101,45 @@ Each interaction which binds to a backend route will need a route declared to ha
 
 ### HTMX routes
 
+Routes are server-side handers for handling HTMX interactions. They consist of 4 main components:
+
+1) HttpVerb: the HTTP verb/method to listen for (eg, GET, POST, etc).
+2) route: the url path
+3) handler: a function reference to call. This method must take a single parameter. The incoming request from HTMX will be deserialized into this parameter, then passed to the function.
+4) renderer: a template for rendering the result of the handler call in HTMX. renderers can be templates, or defined inline.
+
+#### Example route (inline)
+```kotlin
+route(HttpVerb.POST, helloWorldUrl, ExampleService::sayHello) {
+    div {
+        span {
+            +it.message
+        }
+    }
+}
+```
+
+#### Example route (template)
+```kotlin
+val myTemplate = htmxTemplate<ResponseDataClass> {
+    div {
+        span {
+            +it.message
+        }
+    }
+}
+route(HttpVerb.POST, helloWorldUrl, ExampleService::sayHello, myTemplate)
+```
+
 #### GET
 GET requests may have a parameter or no parameter.
 
 ##### GET requests with no parameter
 ```kotlin
 page("/index") {
     get("things", TestController::getAll) {
-        {
-            span {
-                +it.id.toString()
-            }
+        span {
+            +it.id.toString()
         }
     }
 }
@@ -108,10 +149,8 @@ page("/index") {
 ```kotlin
 page("/index") {
     route(HttpVerb.GET, "thing/1", TestController::get) {
-        {
-            span {
-                +it.id.toString()
-            }
+        span {
+            +it.id.toString() 
         }
     }
 }

spring-funk-htmx/src/main/kotlin/com/github/wakingrufus/funk/htmx/HtmxPage.kt

@@ -4,6 +4,7 @@ import com.github.wakingrufus.funk.core.SpringDslMarker
 import com.github.wakingrufus.funk.htmx.route.HxRoute
 import com.github.wakingrufus.funk.htmx.route.noParam
 import com.github.wakingrufus.funk.htmx.route.withParam
+import com.github.wakingrufus.funk.htmx.template.HtmxTemplate
 import kotlinx.html.BODY
 import kotlinx.html.TagConsumer
 import kotlinx.html.body
@@ -16,7 +17,6 @@ import org.springframework.beans.factory.BeanFactory
 import org.springframework.http.MediaType
 import org.springframework.web.servlet.function.RouterFunctionDsl
 import org.springframework.web.servlet.function.ServerResponse
-import org.w3c.dom.Document
 
 class HtmxPage(val path: String) {
     var initialLoad: BODY.() -> Unit = {}
@@ -42,24 +42,44 @@ class HtmxPage(val path: String) {
     inline fun <reified CONTROLLER : Any, RESP : Any> get(
         path: String,
         noinline binding: CONTROLLER.() -> RESP,
-        noinline renderer: (RESP) -> TagConsumer<Document>.() -> Document
+        renderer: HtmxTemplate<RESP>
     ): HxRoute {
-        return noParam(RouterFunctionDsl::GET,
+        return noParam(
+            RouterFunctionDsl::GET,
             path = path,
             controllerClass = CONTROLLER::class.java,
             binding = binding,
             renderer = renderer
-            )
+        )
             .also { addRoute(it) }
     }
 
+    @SpringDslMarker
+    inline fun <reified CONTROLLER : Any, RESP : Any> get(
+        path: String,
+        noinline binding: CONTROLLER.() -> RESP,
+        crossinline renderer: TagConsumer<*>.(RESP) -> Unit
+    ): HxRoute {
+        return get(path, binding) { appendable, input -> renderer.invoke(appendable, input) }
+    }
+
     @SpringDslMarker
     inline fun <reified CONTROLLER : Any, reified REQ : Record, RESP : Any> route(
         verb: HttpVerb,
         path: String,
         noinline binding: CONTROLLER.(REQ) -> RESP,
-        noinline renderer: (RESP) -> TagConsumer<Document>.() -> Document
-    ): HxRoute{
+        crossinline renderer: TagConsumer<*>.(RESP) -> Unit
+    ): HxRoute {
+        return route(verb, path, binding) { appendable, input -> renderer.invoke(appendable, input) }
+    }
+
+    @SpringDslMarker
+    inline fun <reified CONTROLLER : Any, reified REQ : Record, RESP : Any> route(
+        verb: HttpVerb,
+        path: String,
+        noinline binding: CONTROLLER.(REQ) -> RESP,
+        renderer: HtmxTemplate<RESP>
+    ): HxRoute {
         return withParam(
             routerFunction = when (verb) {
                 HttpVerb.GET -> RouterFunctionDsl::GET

spring-funk-htmx/src/main/kotlin/com/github/wakingrufus/funk/htmx/route/HxRoute.kt

@@ -1,11 +1,10 @@
 package com.github.wakingrufus.funk.htmx.route
 
-import kotlinx.html.TagConsumer
+import com.github.wakingrufus.funk.htmx.template.HtmxTemplate
 import org.springframework.beans.factory.BeanFactory
 import org.springframework.web.servlet.function.RouterFunctionDsl
 import org.springframework.web.servlet.function.ServerRequest
 import org.springframework.web.servlet.function.ServerResponse
-import org.w3c.dom.Document
 
 interface HxRoute {
     fun registerRoutes(beanFactory: BeanFactory, dsl: RouterFunctionDsl)
@@ -17,7 +16,7 @@ fun <CONTROLLER : Any, REQ : Record, RESP : Any> withParam(
     requestClass: Class<REQ>,
     controllerClass: Class<CONTROLLER>,
     binding: CONTROLLER.(REQ) -> RESP,
-    renderer: (RESP) -> TagConsumer<Document>.() -> Document
+    renderer: HtmxTemplate<RESP>
 ): HxRoute {
     return ParamRoute(routerFunction, path, requestClass, controllerClass, binding, renderer)
 }
@@ -27,7 +26,7 @@ fun <CONTROLLER : Any, RESP : Any> noParam(
     path: String,
     controllerClass: Class<CONTROLLER>,
     binding: CONTROLLER.() -> RESP,
-    renderer: (RESP) -> TagConsumer<Document>.() -> Document
+    renderer: HtmxTemplate<RESP>
 ): HxRoute {
     return NoParamRoute(routerFunction, path, controllerClass, binding, renderer)
 }

spring-funk-htmx/src/main/kotlin/com/github/wakingrufus/funk/htmx/route/NoParamRoute.kt

@@ -1,22 +1,20 @@
 package com.github.wakingrufus.funk.htmx.route
 
-import kotlinx.html.TagConsumer
-import kotlinx.html.dom.createHTMLDocument
-import kotlinx.html.dom.serialize
+import com.github.wakingrufus.funk.htmx.template.HtmxTemplate
+import kotlinx.html.stream.appendHTML
 import org.springframework.beans.factory.BeanFactory
 import org.springframework.http.MediaType
 import org.springframework.web.servlet.function.RouterFunctionDsl
 import org.springframework.web.servlet.function.ServerRequest
 import org.springframework.web.servlet.function.ServerResponse
 import org.springframework.web.servlet.function.contentTypeOrNull
-import org.w3c.dom.Document
 
 class NoParamRoute<CONTROLLER : Any, RESP : Any>(
     val routerFunction: RouterFunctionDsl.(String, (ServerRequest) -> ServerResponse) -> Unit,
     val path: String,
     private val controllerClass: Class<CONTROLLER>,
     val binding: CONTROLLER.() -> RESP,
-    val renderer: (RESP) -> TagConsumer<Document>.() -> Document
+    val renderer: HtmxTemplate<RESP>
 ) : HxRoute {
     override fun registerRoutes(beanFactory: BeanFactory, dsl: RouterFunctionDsl) {
         dsl.apply {
@@ -31,7 +29,10 @@ class NoParamRoute<CONTROLLER : Any, RESP : Any>(
                     ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(resp)
                 } else {
                     ServerResponse.ok().contentType(MediaType.TEXT_HTML)
-                        .body(createHTMLDocument().run { renderer.invoke(resp).invoke(this) }.serialize(false))
+                        .body(buildString {
+                            appendHTML(false)
+                                .apply { renderer.render(this, resp) }
+                        })
                 }
             }
         }

spring-funk-htmx/src/main/kotlin/com/github/wakingrufus/funk/htmx/route/ParamRoute.kt

@@ -1,26 +1,24 @@
 package com.github.wakingrufus.funk.htmx.route
 
 import com.fasterxml.jackson.databind.ObjectMapper
+import com.github.wakingrufus.funk.htmx.template.HtmxTemplate
 import io.github.oshai.kotlinlogging.KotlinLogging
-import kotlinx.html.TagConsumer
-import kotlinx.html.dom.createHTMLDocument
-import kotlinx.html.dom.serialize
+import kotlinx.html.stream.appendHTML
 import org.springframework.beans.factory.BeanFactory
 import org.springframework.beans.factory.getBean
 import org.springframework.http.MediaType
 import org.springframework.web.servlet.function.RouterFunctionDsl
 import org.springframework.web.servlet.function.ServerRequest
 import org.springframework.web.servlet.function.ServerResponse
 import org.springframework.web.servlet.function.contentTypeOrNull
-import org.w3c.dom.Document
 
 class ParamRoute<CONTROLLER : Any, REQ : Record, RESP : Any>(
     val routerFunction: RouterFunctionDsl.(String, (ServerRequest) -> ServerResponse) -> Unit,
     val path: String,
     private val requestClass: Class<REQ>,
     private val controllerClass: Class<CONTROLLER>,
     val binding: CONTROLLER.(REQ) -> RESP,
-    val renderer: (RESP) -> TagConsumer<Document>.() -> Document
+    val renderer: HtmxTemplate<RESP>
 ) : HxRoute {
     private val log = KotlinLogging.logger {}
     override fun registerRoutes(beanFactory: BeanFactory, dsl: RouterFunctionDsl) {
@@ -45,7 +43,10 @@ class ParamRoute<CONTROLLER : Any, REQ : Record, RESP : Any>(
                     ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(resp)
                 } else {
                     ServerResponse.ok().contentType(MediaType.TEXT_HTML)
-                        .body(createHTMLDocument().run { renderer.invoke(resp).invoke(this) }.serialize(false))
+                        .body(buildString {
+                            appendHTML(false)
+                                .apply { renderer.render(this, resp) }
+                        })
                 }
             }
         }

spring-funk-htmx/src/main/kotlin/com/github/wakingrufus/funk/htmx/template/HtmxTemplate.kt

@@ -0,0 +1,11 @@
+package com.github.wakingrufus.funk.htmx.template
+
+import kotlinx.html.TagConsumer
+
+fun interface HtmxTemplate<I> {
+    fun render(appendable: TagConsumer<Any?>, input: I)
+}
+
+fun <I> htmxTemplate(template: TagConsumer<*>.(I) -> Unit): HtmxTemplate<I> {
+    return HtmxTemplate { appendable, data -> template.invoke(appendable, data) }
+}

spring-funk-htmx/src/test/kotlin/com/github/wakingrufus/funk/htmx/HtmxPageTest.kt

@@ -1,5 +1,6 @@
 package com.github.wakingrufus.funk.htmx
 
+import com.github.wakingrufus.funk.htmx.template.htmxTemplate
 import kotlinx.html.span
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
@@ -25,10 +26,8 @@ class HtmxPageTest {
     fun `test no param get`() {
         val htmxPage = HtmxPage("").apply {
             get("", TestController::noParamGet) {
-                {
-                    span {
-                        +it.id.toString()
-                    }
+                span {
+                    +it.id.toString()
                 }
             }
         }
@@ -39,10 +38,8 @@ class HtmxPageTest {
     fun `test get with params`() {
         val htmxPage = HtmxPage("").apply {
             route(HttpVerb.GET, "", TestController::get) {
-                {
-                    span {
-                        +it.id.toString()
-                    }
+                span {
+                    +it.id.toString()
                 }
             }
         }

spring-funk-htmx/src/test/kotlin/com/github/wakingrufus/funk/htmx/template/HtmxTemplateTest.kt

@@ -0,0 +1,53 @@
+package com.github.wakingrufus.funk.htmx.template
+
+import kotlinx.html.body
+import kotlinx.html.dom.createHTMLDocument
+import kotlinx.html.dom.serialize
+import kotlinx.html.head
+import kotlinx.html.html
+import kotlinx.html.span
+import kotlinx.html.stream.appendHTML
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.jupiter.api.Test
+
+class HtmxTemplateTest {
+    @Test
+    fun `test fragment`() {
+        val template = htmxTemplate<String> {
+            span {
+                +it
+            }
+        }
+        val output = buildString {
+            appendHTML(false).apply {
+                template.render(this, "Hello")
+            }
+        }
+        assertThat(output).isEqualTo("<span>Hello</span>")
+    }
+
+    @Test
+    fun `test document`() {
+        val template = htmxTemplate<String> {
+            span {
+                +it
+            }
+        }
+
+        val output = createHTMLDocument().html {
+            head {
+            }
+            body {
+                template.render(consumer, "Hello")
+            }
+        }.serialize(false)
+        assertThat(output)
+            .isEqualTo(
+                "<!DOCTYPE html>\n" +
+                        "<html>" +
+                        "<head><META http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"></head>" +
+                        "<body><span>Hello</span></body>" +
+                        "</html>"
+            )
+    }
+}

test-application/src/main/kotlin/com/github/wakingrufus/funk/example/ExampleApplication.kt

@@ -20,6 +20,7 @@ import org.springframework.boot.logging.LogLevel
 import org.springframework.web.servlet.function.ServerResponse
 
 const val helloWorldUrl = "/load"
+
 class ExampleApplication : SpringFunkApplication {
     private val log = KotlinLogging.logger {}
     override fun dsl(): SpringDslContainer.() -> Unit = {
@@ -34,11 +35,9 @@ class ExampleApplication : SpringFunkApplication {
             page("/index") {
 
                 route(HttpVerb.POST, helloWorldUrl, ExampleService::sayHello) {
-                    {
-                        div {
-                            span {
-                                +it.message
-                            }
+                    div {
+                        span {
+                            +it.message
                         }
                     }
                 }