diff options
| -rw-r--r-- | API.md | 58 | ||||
| -rw-r--r-- | README.md | 31 | ||||
| -rw-r--r-- | bb.edn | 3 | ||||
| -rw-r--r-- | src/dompa/nodes.cljc | 21 |
4 files changed, 88 insertions, 25 deletions
@@ -7,10 +7,11 @@ - [`->coordinates`](#dompa.html/->coordinates) - Transform a <code>html</code> string into a vector of coordinates indicating where an HTML node ends and begins. - [`->nodes`](#dompa.html/->nodes) - Transform a <code>html</code> string into a tree of nodes, each representing one HTML node and its children. - [`dompa.nodes`](#dompa.nodes) - - [`$`](#dompa.nodes/$) - Creates a new node Usage: <code></code><code>clojure ($ :div ($ "hello world" )) </code><code></code>. + - [`$`](#dompa.nodes/$) - Creates a new node. - [`->html`](#dompa.nodes/->html) - Transform a vector of <code>nodes</code> into an HTML string. - [`defhtml`](#dompa.nodes/defhtml) - Creates a new function with <code>name</code> that outputs HTML. - [`traverse`](#dompa.nodes/traverse) - Recursively traverses given tree of <code>nodes</code> with a <code>traverser-fn</code> that gets a single node passed to it and returns a new updated tree. + - [`zip`](#dompa.nodes/zip) - Creates a zipper for given a given <code>node</code>. ----- # <a name="dompa.coordinates">dompa.coordinates</a> @@ -39,7 +40,7 @@ Transform given `html` according to given `coordinates` into coordinates/unify coordinates/->nodes) ``` -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/coordinates.cljc#L330-L353">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/coordinates.cljc#L327-L350">Source</a></sub></p> ## <a name="dompa.coordinates/compose">`compose`</a> ``` clojure @@ -59,7 +60,7 @@ Composes a given `html` string into a vector of coordinates. will return 3 coordinates (div, text, div) instead of 2 (div, text). To unify the coordinates in a context-aware way, you pass the result of this function to the [`unify`](#dompa.coordinates/unify) function. -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/coordinates.cljc#L65-L85">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/coordinates.cljc#L65-L85">Source</a></sub></p> ## <a name="dompa.coordinates/unify">`unify`</a> ``` clojure @@ -71,7 +72,7 @@ Function. Joins together given `coordinates` that represent one HTML node in `html`, using a stack-based approach to correctly handle nested and void tags. -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/coordinates.cljc#L159-L167">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/coordinates.cljc#L159-L167">Source</a></sub></p> ----- # <a name="dompa.html">dompa.html</a> @@ -90,7 +91,7 @@ Function. Transform a `html` string into a vector of coordinates indicating where an HTML node ends and begins. -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/html.cljc#L5-L11">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/html.cljc#L5-L11">Source</a></sub></p> ## <a name="dompa.html/->nodes">`->nodes`</a> ``` clojure @@ -101,7 +102,7 @@ Function. Transform a `html` string into a tree of nodes, each representing one HTML node and its children. -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/html.cljc#L13-L19">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/html.cljc#L13-L19">Source</a></sub></p> ----- # <a name="dompa.nodes">dompa.nodes</a> @@ -114,19 +115,23 @@ Transform a `html` string into a tree of nodes, ## <a name="dompa.nodes/$">`$`</a> ``` clojure -($ name & opts) +($ & opts) ``` Function. -Creates a new node +Creates a new node. + Children can be passed directly - strings, numbers, and other values + are automatically converted to text nodes. Nil values are filtered out. + Usage: ```clojure - ($ :div - ($ "hello world" )) + ($ :div "hello world") + ($ :div {:class "container"} "Hello, " name "!") + ($ :<> "one" "two" "three") ``` -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/nodes.cljc#L97-L117">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/nodes.cljc#L191-L207">Source</a></sub></p> ## <a name="dompa.nodes/->html">`->html`</a> ``` clojure @@ -155,7 +160,7 @@ Transform a vector of `nodes` into an HTML string. - `:track` - `:wbr` -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/nodes.cljc#L53-L77">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/nodes.cljc#L69-L93">Source</a></sub></p> ## <a name="dompa.nodes/defhtml">`defhtml`</a> ``` clojure @@ -166,17 +171,28 @@ Macro. Creates a new function with `name` that outputs HTML. + Optionally accepts a docstring between the name and the argument vector. + + Functions created with [`defhtml`](#dompa.nodes/defhtml) can be nested and composed with each other. + Example usage: ```clojure - (defhtml about-page [who] + (defhtml greeting [who] + ($ :span who)) + + (defhtml about-page + "Renders the about page." + [who] ($ :div - ($ "hello " who))) + "Hello, " + (greeting who))) (about-page "world") + ;;=> "<div>Hello, <span>world</span></div>" ``` -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/nodes.cljc#L79-L95">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/nodes.cljc#L95-L125">Source</a></sub></p> ## <a name="dompa.nodes/traverse">`traverse`</a> ``` clojure @@ -190,4 +206,14 @@ Recursively traverses given tree of `nodes` with a `traverser-fn` If the traverses function returns `nil`, the node will be removed. In any other case the node will be replaced. If you wish to keep a node unchanged, just return it as-is. -<p><sub><a href="https://github.com/askonomm/dompa/blob/main/src/dompa/nodes.cljc#L39-L51">Source</a></sub></p> +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/nodes.cljc#L43-L55">Source</a></sub></p> + +## <a name="dompa.nodes/zip">`zip`</a> +``` clojure + +(zip node) +``` +Function. + +Creates a zipper for given a given `node`. +<p><sub><a href="https://git.nmm.ee/asko/dompa/src/branch/main/src/dompa/nodes.cljc#L57-L67">Source</a></sub></p> @@ -144,9 +144,7 @@ You can also use fragment nodes, which are nodes with a name of `:<>` and whose (:require [dompa.nodes :refer [$ ->html]])) (->html [($ :button - ($ :<> - ($ "hello ") - ($ "world")))]) + ($ :<> "hello " "world"))]) ;;=> <div>hello world</div> ``` @@ -185,6 +183,33 @@ It works seamlessly with standard Clojure functions like `map`: ;;=> "<ul><li>john</li><li>mike</li><li>jenna</li></ul>" ``` +#### Docstrings + +`defhtml` supports optional docstrings, just like `defn`: + +```clojure +(defhtml about-page + "Renders the about page for a person." + [who] + ($ :div "Hello, " who "!")) +``` + +#### Composition + +Functions created with `defhtml` can be nested and composed with each other: + +```clojure +(defhtml greeting [who] + ($ :span who)) + +(defhtml page [who] + ($ :div + (greeting who))) + +(page "world") +;;=> "<div><span>world</span></div>" +``` + **Note for ClojureScript:** Remember to use `:refer-macros` instead of `:refer` when requiring `defhtml`. ----- @@ -13,5 +13,6 @@ :extra-deps {io.github.borkdude/quickdoc {:git/tag "v0.2.5", :git/sha "25784ca"}} :task (exec 'quickdoc.api/quickdoc) :exec-args {:git/branch "main" - :github/repo "https://github.com/askonomm/dompa" + :github/repo "https://git.nmm.ee/asko/dompa" + :source-uri "{repo}/src/branch/{branch}/{filename}#L{row}-L{end-row}" :source-paths ["src/dompa"]}}}} diff --git a/src/dompa/nodes.cljc b/src/dompa/nodes.cljc index 7e8f769..73bc11f 100644 --- a/src/dompa/nodes.cljc +++ b/src/dompa/nodes.cljc @@ -96,17 +96,24 @@ "Creates a new function with `name` that outputs HTML. Optionally accepts a docstring between the name and the argument vector. + + Functions created with `defhtml` can be nested and composed with each other. Example usage: ```clojure + (defhtml greeting [who] + ($ :span who)) + (defhtml about-page - \"Renders the about page for the given person.\" + \"Renders the about page.\" [who] ($ :div - ($ \"hello \" who))) + \"Hello, \" + (greeting who))) (about-page \"world\") + ;;=> \"<div>Hello, <span>world</span></div>\" ``` " [name & args-and-elements] @@ -182,13 +189,17 @@ (first nodes)))) (defn $ - "Creates a new node + "Creates a new node. + Children can be passed directly - strings, numbers, and other values + are automatically converted to text nodes. Nil values are filtered out. + Usage: ```clojure - ($ :div - ($ \"hello world\" )) + ($ :div \"hello world\") + ($ :div {:class \"container\"} \"Hello, \" name \"!\") + ($ :<> \"one\" \"two\" \"three\") ```" [& opts] (if (keyword? (first opts)) |