package pure-html

  1. Overview
  2. Docs
HTML generator eDSL

Install 

dune-project
 Dependency

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

Authors

  1. Y
    Yawar Amin <yawar.amin@gmail.com>

Maintainers

  1. Y
    Yawar Amin <yawar.amin@gmail.com>

Sources

dream-html-3.11.0.tbz
sha256=d1ac64685188a5b41834c8e1ffc4187f8dfdbc27a972898e6bb833ca4c715811
sha512=43ae60f49d3ada8cd633e0fbe6bf892094eb46a8f8ff1c7605c33724e6f44abcb3466dc61511994a8ac63a5ccd9421c53ce6f5f703bd307d9da3de7b6dbdf85e

doc/pure-html/Pure_html/index.html

Module Pure_htmlSource

Use this module for constructing HTML without any dependency on the Dream web framework.

  • since 3.5.0.

Core types

These are the types of the final values which get rendered.

Sourcetype attr = string * string

E.g. id="toast".

  • since 3.11.0 reveal the type definition in the interface.
Sourcetype node

Either a tag, a comment, or text data in the markup.

Output

Sourceval to_string : node -> string
Sourceval to_xml : ?header:bool -> node -> string

Same as to_string but render void tags as XML-style self-closing tags.

  • parameter header

    print the XML header string if true. This is to allow both use cases where the XML code is embedded inside HTML, and standalone XML documents. Default is false. Since 3.6.0.

  • since 3.3.0.
Sourceval pp : Format.formatter -> node -> unit
Sourceval pp_xml : Format.formatter -> ?header:bool -> node -> unit

Same as pp but render void tags as XML-style self-closing tags.

  • parameter header

    print the XML header string if true. This is to allow both use cases where the XML code is embedded inside HTML, and standalone XML documents. Default is false. Since 3.6.0.

  • since 3.3.0.

Constructing nodes and attributes

Sourcetype 'a to_attr = 'a -> attr

Attributes can be created from typed values.

Sourcetype 'a string_attr = ('a, unit, string, attr) format4 -> 'a

Special handling for string-value attributes so they can use format strings i.e. string interpolation.

Sourcetype std_tag = attr list -> node list -> node

A 'standard' tag with attributes and children.

Sourcetype void_tag = attr list -> node

A 'void element': https://developer.mozilla.org/en-US/docs/Glossary/Void_element with no children.

Sourcetype 'a text_tag = attr list -> ('a, unit, string, node) format4 -> 'a

Tags which can have attributes but can contain only text. The text can be formatted.

Sourceval attr : string -> attr

attr name is a new attribute which does not carry any payload. E.g.

  let required = attr "required"
  • since 0.1.0.
Sourceval string_attr : string -> ?raw:bool -> _ string_attr

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.

Sourceval uri_attr : string -> _ string_attr

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&amp;b=2%203&amp;c=4%3C5&amp;d=6%3E5">Test</a>
Sourceval bool_attr : string -> bool to_attr
Sourceval float_attr : string -> float to_attr
Sourceval int_attr : string -> int to_attr
Sourceval std_tag : string -> std_tag
Sourceval void_tag : string -> void_tag
Sourceval text_tag : string -> ?raw:bool -> _ text_tag

Build a tag which can contain only text.

Sourceval uri_tag : string -> _ text_tag

Build a tag which can contain only a URI. The URI is escaped with the same rules as a uri_attr.

  • since 3.10.0
Sourceval txt : ?raw:bool -> ('a, unit, string, node) format4 -> '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_input
Sourceval comment : string -> node

A comment that will be embedded in the rendered HTML, i.e. <!-- comment -->. The text is HTML-escaped.

Sourceval concat : node -> node list -> node

concat node list is the list of nodes joined together into a single node, with each element separated by node.

  • since 3.10.0

Accessors for tags

Sourceval (+@) : node -> attr -> node

Add an attribute to a tag.

  let toast msg = p [id "toast"] [txt "%s" msg]
  let toast_oob = toast "ok." +@ Hx.swap_oob "true"

If adding the class attribute to a tag which already has a class attribute, join together the values of the CSS classes:

  p [class_ "foo"] [] +@ class_ "bar"

Result:

  <p class="foo bar"></p>
  • raises Invalid_argument

    if the node is not a tag (i.e. if it is a text or comment node), or if it is a duplicate attribute other than class.

  • since 0.0.3.
Sourceval (-@) : node -> string -> node

Remove an attribute from a tag.

  • raises Invalid_argument

    if the node is not a tag (i.e. if it is a text or comment node).

  • since 0.0.3.
Sourceval (.@[]) : node -> string -> string

Get the value of an existing attribute.

  let toast = p [id "toast"] [txt "OK."]
  let toast_id = toast.@["id"]
  • raises Invalid_argument

    if the node is not a tag (i.e. if it is a text or comment node).

  • raises Not_found

    if the tag does not have the given attribute.

  • since 0.0.3.
Sourceval is_null : node -> bool

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.

  • since 1.2.0.
Sourceval is_null_ : attr -> bool

Get whether an attribute is null (empty) or not.

  • since 1.2.0.
Sourceval fold : tag:(string -> attr list -> 'a -> 'a) -> txt:(string -> 'a -> 'a) -> comment:(string -> 'a -> 'a) -> 'a -> node -> 'a

fold ~tag ~txt ~comment value node is the value resulting from 'folding over' the node with an initial value and calling the following callbacks for each child in the node's tree:

  • parameter tag

    tag name attrs value is the value resulting from processing the given tag node's name, attrs, and the value calculated recursively from the tag's children.

  • parameter txt

    txt string value is the value resulting from processing the given text node's string and the value calculated up until now.

  • parameter comment

    comment string value is the value resulting from processing the given comment node's string and the value calculated up until now.

Eg calculate a list of all the classes used by a node and its children:

  let tag _name attrs classes =
    match List.find_opt (fun (n, _) -> n = "class") attrs with
    | Some (_name, c) -> c :: classes
    | None -> classes
  and txt_or_comment _string classes = classes in
  fold ~tag ~txt:txt_or_comment ~comment:txt_or_comment [] node
  • since 3.11.0

HTML

Sourcemodule HTML : sig ... end

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.

SVG

Sourcemodule SVG : sig ... end

MathML

Sourcemodule MathML : sig ... end

ARIA

Sourcemodule Aria : sig ... end

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/

RSS and Atom

Sourcemodule Atom : sig ... end
Sourcemodule RSS : sig ... end

RSS support

htmx

Sourcemodule Hx : sig ... end

htmx support