package dream-html

You can search for identifiers within the package.

in-package search v0.2.0

HTML generator eDSL for Dream

Install

Dune Dependency

github.com Readme Changelog Edit opam file Versions (17)

Authors

Y

Yawar Amin <yawar.amin@gmail.com>

Maintainers

Y

Yawar Amin <yawar.amin@gmail.com>

Sources

dream-html-3.2.0.tbz

sha256=0c0745e6225cb50e40b6663e1ac5e3fa14ed9f8f1e078b8bc25c2c32c9cd66e7

sha512=52b131fe5326318a1cd399868aa43506d266f61dc2c1f11336c7f0f68a0aca985268587dab41b48589bf5b031be7e06501a04e072f308a81bcf577d127f81c14

Description

Write HTML directly in your OCaml source files with editor support.

Published: 11 Mar 2024

README

dream-html - generate HTML markup from your Dream backend server

This file is part of dream-html.

dream-html is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

dream-html is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with dream-html. If not, see https://www.gnu.org/licenses/.

What

An HTML, SVG, and MathML library that is closely integrated with Dream. Most HTML elements and attributes from the Mozilla Developer Network references are included. Almost all non-standard or deprecated tags/attributes deliberately omitted. CSS support is out of scope. htmx attributes supported out of the box.

Why

TyXML is a bit too complex.
Dream's built-in eml (Embedded ML) has some drawbacks like no editor support, quirky syntax that can be hard to debug and refactor, and manual dune rule setup for each view file
In general string-based HTML templating is suboptimal.

First look

let page req =
  let open Dream_html in
  let open HTML in
  (* automatically injects <!doctype html> *)
  html [lang "en"] [
    head [] [
      title [] "Dream-html" ];
    body [] [
      h1 [] [txt "Dream-html"];
      p [] [txt "Is cool!"];
      form [method_ `POST; action "/feedback"] [
        (* Integrated with Dream's CSRF token generation *)
        csrf_tag req;

        label [for_ "what-you-think"] [txt "Tell us what you think!"];
        input [name "what-you-think"; id "what-you-think"];
        input [type_ "submit"; value "Send"] ] ] ]

(* Integrated with Dream response *)
let handler req = Dream_html.respond (page req)

Security (HTML escaping)

Attribute and text values are escaped using rules very similar to standards- compliant web browsers:

utop # open Dream_html;;
utop # open HTML;;
utop # #install_printer pp;;

utop # let user_input = "<script>alert('You have been pwned')</script>";;
val user_input : string = "<script>alert('You have been pwned')</script>"

utop # p [] [txt "%s" user_input];;
- : node = <p>&lt;script&gt;alert('You have been pwned')&lt;/script&gt;</p>

utop # div [title_ {|"%s|} user_input] [];;
- : node = <div title="&quot;<script>alert('You have been pwned')</script>"></div>

How to install

Make sure your local copy of the opam repository is up-to-date first:

opam update
opam install dream-html

Usage

A convenience is provided to respond with an HTML node from a handler:

Dream_html.respond greeting

You can compose multiple HTML nodes together into a single node without an extra DOM node, like React fragments:

let view = null [p [] [txt "Hello"]; p [] [txt "World"]]

You can do string interpolation of text nodes using txt and of any attribute which takes a string value:

let greet name = p [id "greet-%s" name] [txt "Hello, %s!" name]

You can conditionally render an attribute, and void elements are statically enforced as childless:

let entry =
  input
    [ if should_focus then autofocus else null_;
      id "email";
      name "email";
      value "Email address" ]

You can also embed HTML comments in the generated document:

div [] [comment "TODO: xyz."; p [] [txt "Hello!"]]

Explore in the REPL

$ utop
utop # #require "dream-html";;
utop # open Dream_html;;
utop # open HTML;;
utop # #install_printer pp;;
utop # p [class_ "hello"] [txt "world"];;
- : node = <p class="hello">world</p>

Import HTML

One issue that you may come across is that the syntax of HTML is different from the syntax of dream-html markup. To ease this problem, you may use the bookmarklet import_html.js provided in this project. Simply create a new bookmark in your browser with any name, and set the URL to the content of that file (make sure it is exactly the given content).

Then, whenever you have a web page open, just click on the bookmarklet to copy its markup to the clipboard in dream-html format. From there you can simple paste it into your project.

Note that the dream-html version is not formatted nicely, because the expectation is that you will use ocamlformat to fix the formatting.

Also note that the translation done by this bookmarklet is on a best-effort basis. Many web pages don't strictly conform to the rules of correct HTML markup, so you will likely need to fix those issues for your build to work.

Test

Run the test and print out diff if it fails:

dune runtest # Will also exit 1 on failure

Set the new version of the output as correct:

dune promote

Prior art/design notes

Surface design obviously lifted straight from elm-html.

Implementation inspired by both elm-html and Scalatags.

Many languages and libraries have similar HTML embedded DSLs:

Phlex - Ruby
hiccl - Common Lisp
scribble-html-lib - Racket
hiccup - Clojure
std/htmlgen - Nim
Falco.Markup - F#
html_dsl - Python
Arbre - Ruby

Dependencies (2)

dream >= "1.0.0~alpha3"
dune >= "2.7"

Dev Dependencies (1)

odoc with-doc

Used by

None

Conflicts