Module `Htmlit.El`

HTML elements and fragments.

See the element constructors and minimal page generation.

HTML fragments

type html

The type for HTML fragments. A fragment is either:

A single HTML element.
Text: character data.
A splice: a list of fragments.
Unsafe raw data: character data output as is, without escaping.

Elements

type name = string

The type for element names.

val v : ?at:At.t list -> name -> html list -> html

v ?at n cs is an element with name n, attributes at and children cs. Favour element constructors whenever possible. Regarding at:

at defaults to [].
Except for At.class' and At.style attributes, at must not specify an attribute more than once. This is not checked by the module and what happens on multiple definitions is undefined.
For At.class' attributes, multiple specifications are gathered to form a single, space separated, attribute value for the class HTML attribute.
For At.style attributes, multiple specifications are gathered to form a single, semi-colon separated, attribute value for the style HTML attribute.

Text

val txt : string -> html

txt d is character data d.

val txt_of : ('a -> string) -> 'a -> html

txt_of f v is txt (f v). Cuts a bit on delimiter orgies.

val sp : html

sp is El.txt " ".

val nbsp : html

nbsp is El.txt "\u{00A0}".

Splices

val splice : ?sep:html -> html list -> html

splice ?sep hs is the list of fragments hs separated by sep (if any). When added to an element's children, the list is spliced in the element's children.

Unsafe raw data

val unsafe_raw : string -> html

unsafe_raw s is the raw string s without escaping markup delimiters. s must be well-formed HTML otherwise invalid markup is generated. This can be used to:

Include foreign markup, for example markup generated by another mechanism.
Avoid unpleasant surprises with the style element.
Let user-generated content create XSS attacks in your application.

Voids

Like void attributes, void fragments render nothing.

val void : html

void is splice []. See also is_void.

val is_void : html -> bool

is_void h is true iff h is an empty splice, an empty txt or an empty unsafe_raw. These fragments render nothing. See also void.

Rendering

val buffer_add : doctype:bool -> Buffer.t -> html -> unit

buffer_add ~doctype b h adds the HTML fragment h to b. If doc_type is true an HTML doctype declaration is prepended.

val to_string : doctype:bool -> html -> string

to_string is like buffer_add but returns directly a string.

module Low : sig ... end

Low level representation (unstable).

Page

There's more than one way to generate a basic minimal HTML page. The following provides good defaults for quick minimal pages.

val page : 
  ?lang:string ->
  ?generator:string ->
  ?styles:string list ->
  ?scripts:string list ->
  ?more_head:html ->
  title:string ->
  html ->
  html

page ~lang ~title body is an El.html element with an At.lang attribute of lang (if specified and non-empty) containing a El.head element followed by body which must be a El.body element.

The children of the El.head element are in order:

An El.meta charset with value utf-8, unconditional.
An El.meta generator with value generator, if specified and non-empty.
An El.meta viewport with value width=device-width, initial-scale=1, unconditional.
For each non-empty element href of styles (defaults to []), an El.link with At.type' text/css and At.href value href. In order.
For each non-empty element src of scripts (defaults to []), an El.script with At.defer, At.type' value text/javascript and At.src value src. In order.
more_head fragment (defaults to El.void). Be careful if you add style tags with direct CSS source.
An El.title with value title which is String.trimed. If the result is empty falls back to "Untitled". See also title_of_filepath to derive titles from file paths.

val title_of_filepath : string -> string

title_of_filepath f is a non-empty page title for filepath f. Either the basename of f without extension or if that results in "index" or "" the basename of the parent directory without extension or if that results in "" the value "Untitled". Directory separators can be '/' or '\\' regardless of the platform.