docs

yawaramin · Mar 10, 2024 · 7c32010 · 7c32010
1 parent 1bf6187
commit 7c32010
Showing 1 changed file with 2 additions and 54 deletions.
diff --git a/dream-html/Dream_html/index.html b/dream-html/Dream_html/index.html
@@ -7,7 +7,7 @@
 let () =
   Dream.run
   @@ Dream.logger
-  @@ Dream.router [Dream.get &quot;/&quot; (fun _ -&gt; Dream_html.respond (hello &quot;world&quot;))]</code></pre><p>More examples shown below.</p></header><nav class="odoc-toc"><ul><li><a href="#core-types">Core types</a></li><li><a href="#output">Output</a></li><li><a href="#constructing-nodes-and-attributes">Constructing nodes and attributes</a></li><li><a href="#accessors-for-tags">Accessors for tags</a></li><li><a href="#standard-attributes-and-tags">Standard attributes and tags</a></li><li><a href="#aria-support">ARIA support</a></li><li><a href="#htmx-support">htmx support</a></li><li><a href="#interop-example–markdown-to-html">Interop example–Markdown to HTML</a></li></ul></nav><div class="odoc-content"><h3 id="core-types"><a href="#core-types" class="anchor"></a>Core types</h3><p>These are the types of the final values which get rendered.</p><div class="odoc-spec"><div class="spec type anchored" id="type-attr"><a href="#type-attr" class="anchor"></a><code><span><span class="keyword">type</span> attr</span></code></div><div class="spec-doc"><p>E.g. <code>id=&quot;toast&quot;</code>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-node"><a href="#type-node" class="anchor"></a><code><span><span class="keyword">type</span> node</span></code></div><div class="spec-doc"><p>Either a tag, a comment, or text data in the markup.</p></div></div><h3 id="output"><a href="#output" class="anchor"></a>Output</h3><div class="odoc-spec"><div class="spec value anchored" id="val-to_string"><a href="#val-to_string" class="anchor"></a><code><span><span class="keyword">val</span> to_string : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-respond"><a href="#val-respond" class="anchor"></a><code><span><span class="keyword">val</span> respond : 
+  @@ Dream.router [Dream.get &quot;/&quot; (fun _ -&gt; Dream_html.respond (hello &quot;world&quot;))]</code></pre><p>More examples shown below.</p></header><nav class="odoc-toc"><ul><li><a href="#core-types">Core types</a></li><li><a href="#output">Output</a></li><li><a href="#constructing-nodes-and-attributes">Constructing nodes and attributes</a></li><li><a href="#accessors-for-tags">Accessors for tags</a></li><li><a href="#standard-attributes-and-tags">Standard attributes and tags</a></li><li><a href="#aria-support">ARIA support</a></li><li><a href="#htmx-support">htmx support</a></li></ul></nav><div class="odoc-content"><h3 id="core-types"><a href="#core-types" class="anchor"></a>Core types</h3><p>These are the types of the final values which get rendered.</p><div class="odoc-spec"><div class="spec type anchored" id="type-attr"><a href="#type-attr" class="anchor"></a><code><span><span class="keyword">type</span> attr</span></code></div><div class="spec-doc"><p>E.g. <code>id=&quot;toast&quot;</code>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-node"><a href="#type-node" class="anchor"></a><code><span><span class="keyword">type</span> node</span></code></div><div class="spec-doc"><p>Either a tag, a comment, or text data in the markup.</p></div></div><h3 id="output"><a href="#output" class="anchor"></a>Output</h3><div class="odoc-spec"><div class="spec value anchored" id="val-to_string"><a href="#val-to_string" class="anchor"></a><code><span><span class="keyword">val</span> to_string : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> string</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-respond"><a href="#val-respond" class="anchor"></a><code><span><span class="keyword">val</span> respond : 
   <span><span class="optlabel">?status</span>:<span>[&lt; <span class="xref-unresolved">Dream</span>.status ]</span> <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?code</span>:int <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?headers</span>:<span><span>(string * string)</span> list</span> <span class="arrow">&#45;&gt;</span></span>
@@ -22,56 +22,4 @@
   [action &quot;/foo&quot;]
   [csrf_tag req; input [name &quot;bar&quot;]; input [type_ &quot;submit&quot;]]</code></pre></div></div><h3 id="accessors-for-tags"><a href="#accessors-for-tags" class="anchor"></a>Accessors for tags</h3><div class="odoc-spec"><div class="spec value anchored" id="val-(+@)"><a href="#val-(+@)" class="anchor"></a><code><span><span class="keyword">val</span> (+@) : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> <span><a href="#type-attr">attr</a> <span class="arrow">&#45;&gt;</span></span> <a href="#type-node">node</a></span></code></div><div class="spec-doc"><p>Add an attribute to a tag.</p><pre class="language-ocaml"><code>let toast msg = p [id &quot;toast&quot;] [txt &quot;%s&quot; msg]
 let toast_oob = toast &quot;ok.&quot; +@ Hx.swap_oob &quot;true&quot;</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the node is not a tag (i.e. if it is a text or comment node).</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.0.3.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(-@)"><a href="#val-(-@)" class="anchor"></a><code><span><span class="keyword">val</span> (-@) : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> <span>string <span class="arrow">&#45;&gt;</span></span> <a href="#type-node">node</a></span></code></div><div class="spec-doc"><p>Remove an attribute from a tag.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the node is not a tag (i.e. if it is a text or comment node).</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.0.3.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(.@[])"><a href="#val-(.@[])" class="anchor"></a><code><span><span class="keyword">val</span> (.@[]) : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> <span>string <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p>Get the value of an existing attribute.</p><pre class="language-ocaml"><code>let toast = p [id &quot;toast&quot;] [txt &quot;OK.&quot;]
-let toast_id = toast.@[&quot;id&quot;]</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the node is not a tag (i.e. if it is a text or comment node).</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Not_found</code> <p>if the tag does not have the given attribute.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.0.3.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_null"><a href="#val-is_null" class="anchor"></a><code><span><span class="keyword">val</span> is_null : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p>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.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2.0.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_null_"><a href="#val-is_null_" class="anchor"></a><code><span><span class="keyword">val</span> is_null_ : <span><a href="#type-attr">attr</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p>Get whether an attribute is null (empty) or not.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2.0.</li></ul></div></div><h3 id="standard-attributes-and-tags"><a href="#standard-attributes-and-tags" class="anchor"></a>Standard attributes and tags</h3><div class="odoc-spec"><div class="spec module anchored" id="module-HTML"><a href="#module-HTML" class="anchor"></a><code><span><span class="keyword">module</span> <a href="HTML/index.html">HTML</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>All standard HTML attributes and tags. Some attributes and tags have the same name, e.g. <code>style</code>. To disambiguate them, attributes have a <code>_</code> (underscore) suffix.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-SVG"><a href="#module-SVG" class="anchor"></a><code><span><span class="keyword">module</span> <a href="SVG/index.html">SVG</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-MathML"><a href="#module-MathML" class="anchor"></a><code><span><span class="keyword">module</span> <a href="MathML/index.html">MathML</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="aria-support"><a href="#aria-support" class="anchor"></a>ARIA support</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Aria"><a href="#module-Aria" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Aria/index.html">Aria</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/">https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/</a></p></div></div><h3 id="htmx-support"><a href="#htmx-support" class="anchor"></a>htmx support</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Hx"><a href="#module-Hx" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Hx/index.html">Hx</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>htmx support <a href="https://htmx.org/reference/">https://htmx.org/reference/</a></p></div></div><h3 id="interop-example–markdown-to-html"><a href="#interop-example–markdown-to-html" class="anchor"></a>Interop example–Markdown to HTML</h3><p>In this section we show an extended example of interoperability of dream-html with other formats, e.g. the Markdown format defined by the <code>omd</code> library:</p><pre class="language-ocaml"><code>open Dream_html
-open HTML
-
-let omd_attr (k, opt_v) =
-  string_attr k &quot;%s&quot; @@ Option.fold ~none:&quot;&quot; ~some:Fun.id opt_v
-
-let rec omd_node elements = elements |&gt; List.map element_node |&gt; null
-and item omd = li [] [omd_node omd]
-
-and element_node = function
-  | Omd.H1 omd -&gt; h1 [] [omd_node omd]
-  | H2 omd -&gt; h2 [] [omd_node omd]
-  | H3 omd -&gt; h3 [] [omd_node omd]
-  | H4 omd -&gt; h4 [] [omd_node omd]
-  | H5 omd -&gt; h5 [] [omd_node omd]
-  | H6 omd -&gt; h6 [] [omd_node omd]
-  | Paragraph omd -&gt; p [] [omd_node omd]
-  | Text str -&gt; txt &quot;%s&quot; str
-  | Emph omd -&gt; em [] [omd_node omd]
-  | Bold omd -&gt; b [] [omd_node omd]
-  | Ul omds | Ulp omds -&gt; ul [] @@ List.map item omds
-  | Ol omds | Olp omds -&gt; ol [] @@ List.map item omds
-  | Code (cls, str) -&gt; code [class_ &quot;%s&quot; cls] [txt &quot;%s&quot; str]
-  | Code_block (cls, str) -&gt;
-    pre [class_ &quot;%s&quot; cls] [code [class_ &quot;%s&quot; cls] [txt &quot;%s&quot; str]]
-  | Br -&gt; br []
-  | Hr -&gt; hr []
-  | NL -&gt; txt &quot;\n&quot;
-  | Url (hre, omd, titl) -&gt;
-    a
-      [ href &quot;%s&quot; hre;
-        target &quot;_blank&quot;;
-        class_ &quot;after:content-['_↗️']&quot;;
-        title &quot;%s&quot; titl ]
-      [omd_node omd]
-  | Html (&quot;details&quot;, attrs, omd) -&gt;
-    details (List.map omd_attr attrs) [omd_node omd]
-  | Html (&quot;summary&quot;, attrs, omd) -&gt;
-    summary (List.map omd_attr attrs) [omd_node omd]
-  | Html_block (&quot;details&quot;, attrs, omd) -&gt;
-    details (List.map omd_attr attrs) [omd_node omd]
-  | Html_block (&quot;summary&quot;, attrs, omd) -&gt;
-    summary (List.map omd_attr attrs) [omd_node omd]
-  | Ref (_, _, _, _)
-  | Img_ref (_, _, _, _)
-  | Html (_, _, _)
-  | Html_block (_, _, _)
-  | X _ -&gt; null []
-  | Html_comment str -&gt; comment str
-  | Raw str -&gt; txt ~raw:true &quot;%s&quot; str
-  | Raw_block str -&gt; pre [] [txt ~raw:true &quot;%s&quot; str]
-  | Blockquote omd -&gt; blockquote [] [omd_node omd]
-  | Img (al, sr, titl) -&gt; img [alt &quot;%s&quot; al; src &quot;%s&quot; sr; title &quot;%s&quot; titl]</code></pre><p>The entrypoint of the functionality is the <code>omd_node</code> function, which converts from the <code>Omd.t</code> value which can be obtained by, for example, parsing Markdown with the <code>Omd.of_string</code> function, to a type-safe <code>node</code> value.</p><p>In the <code>element_node</code> function we traverse the Markdown structure and convert it into specific nodes–tags, comments, etc.. Text is escaped as appropriate and some specific conversions are handled specially:</p><ul><li>All hyperlinks are made to open new tabs and suffixed using a Tailwind CSS style class.</li><li>We support the <code>&lt;details&gt;</code> and <code>&lt;summary&gt;</code> HTML tags, but no others.</li></ul><p>This is just an example, but it shows the idea that we can take various formats and interop with them using type-sdfe HTML generated by dream-html.</p></div></body></html>
+let toast_id = toast.@[&quot;id&quot;]</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the node is not a tag (i.e. if it is a text or comment node).</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Not_found</code> <p>if the tag does not have the given attribute.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.0.3.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_null"><a href="#val-is_null" class="anchor"></a><code><span><span class="keyword">val</span> is_null : <span><a href="#type-node">node</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p>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.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2.0.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_null_"><a href="#val-is_null_" class="anchor"></a><code><span><span class="keyword">val</span> is_null_ : <span><a href="#type-attr">attr</a> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p>Get whether an attribute is null (empty) or not.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2.0.</li></ul></div></div><h3 id="standard-attributes-and-tags"><a href="#standard-attributes-and-tags" class="anchor"></a>Standard attributes and tags</h3><div class="odoc-spec"><div class="spec module anchored" id="module-HTML"><a href="#module-HTML" class="anchor"></a><code><span><span class="keyword">module</span> <a href="HTML/index.html">HTML</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>All standard HTML attributes and tags. Some attributes and tags have the same name, e.g. <code>style</code>. To disambiguate them, attributes have a <code>_</code> (underscore) suffix.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-SVG"><a href="#module-SVG" class="anchor"></a><code><span><span class="keyword">module</span> <a href="SVG/index.html">SVG</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-MathML"><a href="#module-MathML" class="anchor"></a><code><span><span class="keyword">module</span> <a href="MathML/index.html">MathML</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h3 id="aria-support"><a href="#aria-support" class="anchor"></a>ARIA support</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Aria"><a href="#module-Aria" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Aria/index.html">Aria</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/">https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/</a></p></div></div><h3 id="htmx-support"><a href="#htmx-support" class="anchor"></a>htmx support</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Hx"><a href="#module-Hx" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Hx/index.html">Hx</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>htmx support <a href="https://htmx.org/reference/">https://htmx.org/reference/</a></p></div></div></div></body></html>