package dream-html
Module Dream_htmlSource
Input
Typed, extensible HTML form decoder with error reporting for form field validation failures. Powerful chained decoding functionality–the validation of one field can depend on the values of other decoded fields.
val form :
'a Form.t ->
?csrf:bool ->
Dream.request ->
[> 'a Dream.form_result | `Invalid of (string * string) list ] Dream.promiseType-safe wrapper for Dream.form. Similarly to that, you can match on the result:
type new_user = { name : string; email : string }
let new_user =
let open Dream_html.Form in
let+ name = required string "name"
and+ email = required string "email" in
{ name; email }
(* POST /users *)
let post_users req =
match%lwt Dream_html.form new_user req with
| `Ok { name; email } -> (* ... *)
| `Invalid errors -> Dream.json ~code:422 ( (* ...render errors... *) )
| _ -> Dream.empty `Bad_RequestType-safe wrapper for Dream.all_queries. Can be used to decode the query parameters into a typed value.
Output
include module type of Pure_html
Core types
These are the types of the final values which get rendered.
E.g. id="toast".
Either a tag, a comment, or text data in the markup.
Output
Same as to_string but render void tags as XML-style self-closing tags.
Same as pp but render void tags as XML-style self-closing tags.
Constructing nodes and attributes
Special handling for string-value attributes so they can use format strings i.e. string interpolation.
A 'void element': https://developer.mozilla.org/en-US/docs/Glossary/Void_element with no children.
Tags which can have attributes but can contain only text. The text can be formatted.
attr name is a new attribute which does not carry any payload. E.g.
let required = attr "required"string_attr name fmt is a new string-valued attribute which allows formatting i.e. string interpolation of the value. Note, the fmt argument is required due to the value restriction.
Convenience for attributes whose values should be URIs. Takes care of both URI-encoding and attribute escaping, as recommended in https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#common-mistake.
Examples
a [href "/blog?tags=iamsafe\"></a><script>alert('Pwned')</script>"] [txt "Tags: tag1 | tag2"]
==>
<a href="/blog?tags=iamsafe%22%3E%3C/a%3E%3Cscript%3Ealert('Pwned')%3C/script%3E">Tags: tag1 | tag2</a>
a [href "/foo?a=1&b=2 3&c=4<5&d=6>5"] [txt "Test"]
==>
<a href="/foo?a=1&b=2%203&c=4%3C5&d=6%3E5">Test</a>A text node inside the DOM e.g. the 'hi' in <b>hi</b>. Allows string interpolation using the same formatting features as Printf.sprintf:
b [] [txt "Hello, %s!" name]Or without interpolation:
b [] [txt "Bold of you."]HTML-escapes the text value. You can use the ~raw param to bypass escaping:
let user_input = "<script>alert('I like HTML injection')</script>" in
txt ~raw:true "%s" user_inputA comment that will be embedded in the rendered HTML, i.e. <!-- comment -->. The text is HTML-escaped.
Accessors for tags
Add an attribute to a tag.
let toast msg = p [id "toast"] [txt "%s" msg]
let toast_oob = toast "ok." +@ Hx.swap_oob "true"Get the value of an existing attribute.
let toast = p [id "toast"] [txt "OK."]
let toast_id = toast.@["id"]Get whether a node is null (empty) or not. Useful for conditional rendering of UIs when you are passed in a node and you don't know if it's empty or not.
Standard attributes and tags
All standard HTML attributes and tags. Some attributes and tags have the same name, e.g. style. To disambiguate them, attributes have a _ (underscore) suffix.
ARIA support
htmx support
htmx support https://htmx.org/reference/
val respond :
?status:[< Dream.status ] ->
?code:int ->
?headers:(string * string) list ->
node ->
Dream.response Dream.promiseval send :
?text_or_binary:[< Dream.text_or_binary ] ->
?end_of_message:[< Dream.end_of_message ] ->
Dream.websocket ->
node ->
unit Dream.promiseType-safe wrapper for Dream.send.
Type-safe wrapper for Dream.set_body. Sets the body to the given node and sets the Content-Type header to text/html.
Type-safe wrapper for Dream.write.
Convenience to add a CSRF token generated by Dream into your form. Type-safe wrapper for Dream.csrf_tag.
form [action "/foo"] [
csrf_tag req;
input [name "bar"];
input [type_ "submit"];
]Live reload support
Live reload script injection and handling. Adapted from Dream.livereload middleware. This version is not a middleware so it's not as plug-and-play as that, but on the other hand it's much simpler to implement because it uses type-safe dream-html nodes rather than parsing and printing raw HTML. See below for the 3-step process to use it.