Add dream-html example (#323)

aantron · Oct 14, 2024 · c8ec9d1 · c8ec9d1
1 parent 6a1a2f0
commit c8ec9d1
Show file tree

Hide file tree

Showing 8 changed files with 108 additions and 0 deletions.
diff --git a/example/7-template/README.md b/example/7-template/README.md
@@ -145,6 +145,10 @@ and not supported by Dream.
   OCaml's type system to prevent emitting many kinds of invalid HTML.
 - [**`r-tyxml`**](../r-tyxml#files) if you are using Reason. You can use TyXML
   with JSX syntax server-side!
+- [**`w-dream-html`**](../w-dream-html#files) shows how to use
+  [dream-html](https://github.com/yawaramin/dream-html), another alternative
+  library for generating HTML from OCaml, which is more closely integrated with
+  Dream.
 - [**`w-template-stream`**](../w-template-stream#files) streams templates to
   responses, instead of building up complete response strings.
 

diff --git a/example/README.md b/example/README.md
@@ -128,6 +128,8 @@ if something is missing!
   reverse proxy.
 - [**`w-tyxml`**](w-tyxml#files) &nbsp;&mdash;&nbsp; uses TyXML for type-checked
   HTML templating.
+- [**`w-dream-html`**](../w-dream-html#files) &nbsp;&mdash;&nbsp; uses
+  dream-html for convenient HTML generation from OCaml.
 - [**`w-long-polling`**](w-long-polling#files) &nbsp;&mdash;&nbsp; old form of
   asynchronous communication without WebSockets.
 - [**`w-query`**](w-query#files) &nbsp;&mdash;&nbsp; reads URL query parameters.

diff --git a/example/w-dream-html/README.md b/example/w-dream-html/README.md
@@ -0,0 +1,67 @@
+# `w-dream-html`
+
+<br>
+
+[Dream-html](https://github.com/yawaramin/dream-html) can be used with Dream for
+generating HTML. Dream-html is a library that offers functions for generating
+HTML, SVG, and MathML, as well as out-of-the-box support for
+[htmx](https://htmx.org/) attributes. It is closely integrated with Dream for
+convenience.
+
+```ocaml
+let greet who =
+  let open Dream_html in
+  let open HTML in
+  html [lang "en"] [
+    head [] [
+      title [] "Greeting";
+    ];
+    comment "Embedded in the HTML";
+    body [] [
+      h1 [] [txt "Good morning, %s!" who];
+    ];
+  ]
+
+let () =
+  Dream.run
+  @@ Dream.logger
+  @@ Dream.router [
+
+    Dream.get "/"
+      (fun _ -> Dream_html.respond (greet "world"));
+
+  ]
+```
+
+<pre><code><b>$ cd example/w-dream-html</b>
+<b>$ opam install --deps-only --yes .</b>
+<b>$ dune exec --root . ./main.exe</b></code></pre>
+
+Try it in the [playground](https://dream.as/w-dream-html).
+
+Some notes:
+
+- All text nodes and attributes are HTML-escaped by default for security, with
+  exceptions noted in the documentation
+- All text nodes and attributes accept format strings for conveniently embedding
+  variables in the HTML
+- Functions like `Dream_html.respond`, `Dream_html.send`, `Dream_html.csrf_tag`
+  provide convenient integration with Dream
+- The `<!DOCTYPE html>` prefix is automatically rendered before the `<html>` tag
+- The `SVG` and `MathML` modules provide their corresponding markup. The `Hx`
+  module provides htmx attributes.
+
+<br>
+<br>
+
+**See also:**
+
+- [**`7-template`**](../7-template#security) section *Security* on output
+  security. Dream-html escapes strings by default, just as the built-in templater
+  does.
+- [**`w-tyxml`**](../w-tyxml#files) is a similar library that also generates
+  HTML, with different design tradeoffs.
+
+<br>
+
+[Up to the example index](../#examples)
diff --git a/example/w-dream-html/dune b/example/w-dream-html/dune
@@ -0,0 +1,3 @@
+(executable
+ (name html)
+ (libraries dream-html))
diff --git a/example/w-dream-html/dune-project b/example/w-dream-html/dune-project
@@ -0,0 +1 @@
+(lang dune 2.0)
diff --git a/example/w-dream-html/html.ml b/example/w-dream-html/html.ml
@@ -0,0 +1,23 @@
+let greet who =
+  let open Dream_html in
+  let open HTML in
+  html [lang "en"] [
+    head [] [
+      title [] "Greeting";
+    ];
+    comment "Embedded in the HTML";
+    body [] [
+      h1 [] [txt "Good morning, %s!" who];
+    ];
+  ]
+
+let () =
+  Dream.run
+  @@ Dream.logger
+  @@ Dream.router [
+
+    Dream.get "/"
+      (fun _ -> Dream_html.respond (greet "world"));
+
+  ]
+
diff --git a/example/w-dream-html/w-dream-html.opam b/example/w-dream-html/w-dream-html.opam
@@ -0,0 +1,7 @@
+opam-version: "2.0"
+
+depends: [
+  "ocaml" {>= "4.08.0"}
+  "dream-html" {>= "3.3.1"}
+  "dune" {>= "2.0.0"}
+]
diff --git a/example/z-playground/server/sync.sh b/example/z-playground/server/sync.sh
@@ -52,6 +52,7 @@ example k-websocket
 example w-query
 example w-flash
 example w-tyxml
+example w-dream-html
 example w-chat
 example w-graphql-subscription
 example w-long-polling