[ANN] dream-html 1.0.0

Ecosystem
,
1

Hi, dream-html 1.0.0 has been released to opam: dream-html 1.0.0 (latest) · OCaml Package

Repo: GitHub - yawaramin/dream-html: Generate HTML markup from your OCaml Dream backend server
API docs: Dream_html (dream-html.Dream_html)

Dream-html is a library for generating HTML, closely integrated with Dream. It can be used as an alternative to Dream’s built-in Embedded ML templating language. Here’s the Dream home page example using dream-html:

let hello who =
  let open Dream_html in
  let open HTML in
  html [] [
    body [] [
      h1 [] [txt "Hello, %s!" who]]]

let () =
  Dream.run
  @@ Dream.logger
  @@ Dream.router [Dream.get "/" (fun _ -> Dream_html.respond (hello "world"))]

In this release, I made a breaking change (hence major version bump) to group all HTML tags and attributes under the same HTML module, so only two opens are needed to access all HTML functionality directly.

Another smaller improvement is more granular escaping of HTML text nodes and attribute values, following browser rules more closely. E.g. I’m no longer escaping ' and " in text nodes, and not escaping &, <, > in attribute values.

More details in the repo readme and documentation. Enjoy!

18 Likes
2

[ANN] dream-html 1.1.0

Small update to add some minimal SVG support (PRs to add more SVG tags and attributes welcome). Also added fetchpriority attribute. E.g.

open Dream_html

let osi_logo =
  let open SVG in
  svg [xmlns; viewbox ~min_x:0 ~min_y:0 ~width:100 ~height:100] [
    path [
      d "M34,93l11,-29a15,15 0,1,1 9,0l11,29a45,45 0,1,0 -31,0z";
      stroke "#142";
      stroke_width "2";
      fill "#4a5"] []
  ]

let unimportant =
  let open HTML in
  img [
    src "/images/in_viewport_but_not_important.svg";
    fetchpriority `low;
    alt "I'm an unimportant image!";
  ]
6 Likes
3

How does this compare to TyXML? (Other than being more tailored to Dream, I guess)

4

We make different tradeoffs. TyXML enforces the rules of valid HTML to the furthest possible extend. For example, it enforces that <select> elements can contain only <option> or <optgroup> elements. Dream-html does not do this. So you give up some awesome type modelling power, but in exchange you get more flexibility. For example, now the <hr> element is a valid child of <option> as per HTML Standard . Tyxml has to be updated with a new release, to allow this. Dream-html doesn’t, because it doesn’t model the rules of what HTML may appear where at the type level. That’s the core difference.

Although there are several other differences which I feel are ergonomic but important. For example, when you use the html value, Dream-html knows to automatically put a doctype declaration on top of that, because in valid HTML there’s no other way to do it. So let’s do it automatically. Also, every string-valued attribute and text node automatically uses format strings without having to remember another special formatting function, just because it’s a super common use case.

Also, Dream-html ships out-of-the-box with all current valid htmx attributes, as a bit of an easter egg.

4 Likes
5

[ANN] dream-html 1.2.0

Small addition to allow checking if a node or attr is ‘null’ (i.e. empty). This can be useful when you get a node or attr passed in to your function and you need to decide what to render depending on whether it’s empty or not.

As a reminder, ‘null’ or empty nodes and attributes are ones which are simply not rendered into the final HTML.

1 Like