KTOR-6782 Add an example of the PlaceHolderList class usage (#557)

Co-authored-by: Gleb Nazarov <[email protected]> Co-authored-by: Vik Nikolova <[email protected]>
ktorio · Dec 19, 2024 · 2df3b24 · 2df3b24
1 parent 74023c2
commit 2df3b24
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 8 deletions.
diff --git a/codeSnippets/snippets/html-templates/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/html-templates/src/main/kotlin/com/example/Application.kt
@@ -21,6 +21,10 @@ fun Application.module() {
                     articleText {
                         +"Kotlin Framework for creating connected systems."
                     }
+                    list {
+                        item { +"One" }
+                        item { +"Two" }
+                    }
                 }
             }
         }
@@ -29,20 +33,21 @@ fun Application.module() {
 
 class LayoutTemplate: Template<HTML> {
     val header = Placeholder<FlowContent>()
-    val content = TemplatePlaceholder<ContentTemplate>()
+    val content = TemplatePlaceholder<ArticleTemplate>()
     override fun HTML.apply() {
         body {
             h1 {
                 insert(header)
             }
-            insert(ContentTemplate(), content)
+            insert(ArticleTemplate(), content)
         }
     }
 }
 
-class ContentTemplate: Template<FlowContent> {
+class ArticleTemplate : Template<FlowContent> {
     val articleTitle = Placeholder<FlowContent>()
     val articleText = Placeholder<FlowContent>()
+    val list = TemplatePlaceholder<ListTemplate>()
     override fun FlowContent.apply() {
         article {
             h2 {
@@ -51,6 +56,28 @@ class ContentTemplate: Template<FlowContent> {
             p {
                 insert(articleText)
             }
+            insert(ListTemplate(), list)
         }
     }
 }
+
+class ListTemplate : Template<FlowContent> {
+    val item = PlaceholderList<UL, FlowContent>()
+    override fun FlowContent.apply() {
+        if (!item.isEmpty()) {
+            ul {
+                each(item) {
+                    li {
+                        if (it.first) {
+                            b {
+                                insert(it)
+                            }
+                        } else {
+                            insert(it)
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/topics/server-html-dsl.md b/topics/server-html-dsl.md
@@ -98,6 +98,10 @@ Let's see on the [example](https://github.com/ktorio/ktor-documentation/tree/%kt
 <article>
     <h2>Hello from Ktor!</h2>
     <p>Kotlin Framework for creating connected systems.</p>
+    <ul>
+       <li><b>One</b></li>
+       <li>Two</li>
+    </ul>
 </article>
 </body>
 ```
@@ -120,7 +124,7 @@ Let's implement these layouts step-by-step:
 2. A root layout template will look in the following way:
    ```kotlin
    ```
-   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="30-41"}
+   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="34-45"}
 
    The class exposes two properties:
    * The `header` property specifies a content inserted within the `h1` tag.
@@ -129,13 +133,21 @@ Let's implement these layouts step-by-step:
 3. A child template will look as follows:
    ```kotlin
    ```
-   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="43-56"}
+   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="47-62"}
 
-   This template exposes the `articleTitle` and `articleText` properties, whose values will be inserted inside the `article`.
+   This template exposes the `articleTitle`, `articleText` and `list` properties, whose values will be inserted inside the `article`.
 
-4. Now we are ready to send HTML built using the specified property values:
+4. To provide a list of values as the template, create the following new class: 
    ```kotlin
    ```
-   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="12-26"}
+   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="64-83"}
+
+   This template uses the `PlaceholderList` class to generate an unordered list (`UL`) from the provided items.
+   It also wraps the first item in a `<b>` element for emphasis.
+
+5. Now we are ready to send HTML built using the specified property values:
+   ```kotlin
+   ```
+   {src="snippets/html-templates/src/main/kotlin/com/example/Application.kt" include-lines="12-30"}
 
 You can find the full example here: [html-templates](https://github.com/ktorio/ktor-documentation/tree/%ktor_version%/codeSnippets/snippets/html-templates).