Public api for the Datastar SDK.
The main api consists several functions that operate on SSE generators, see:
These function take options map whose keys are:
To help manage SSE generators's underlying connection there is:
Helper to extract datastar specific data from ring requests:
Some common utilities for HTTP are also provided:
Some scripts are provided:
Public api for the Datastar SDK. The main api consists several functions that operate on SSE generators, see: - [[patch-elements!]] - [[patch-elements-seq!]] - [[remove-element!]] - [[patch-signals!]] - [[execute-script!]] These function take options map whose keys are: - [[id]] - [[retry-duration]] - [[selector]] - [[patch-mode]] - [[use-view-transition]] - [[only-if-missing]] - [[auto-remove]] - [[attributes]] To help manage SSE generators's underlying connection there is: - [[close-sse!]] - [[lock-sse!]] - [[with-open-sse]] Helper to extract datastar specific data from ring requests: - [[get-signals]] - [[datastar-request?]] Some common utilities for HTTP are also provided: - [[sse-get]] - [[sse-post]] - [[sse-put]] - [[sse-patch]] - [[sse-delete]] Some scripts are provided: - [[console-log!]] - [[console-error!]] - [[redirect!]]
execute-script! option, map:
A map of attributes to add to the script element.
[[execute-script!]] option, map: A map of attributes to add to the script element.
execute-script! option, boolean:
Whether to remove the script after execution, if not provided the Datastar client side will default to true.
[[execute-script!]] option, boolean: Whether to remove the script after execution, if not provided the Datastar client side will default to true.
URL for the Datastar js source map
URL for the Datastar js source map
(close-sse! sse-gen)Close the connection of a sse generator.
Return value:
sse-gen closedClose the connection of a sse generator. Return value: - true if `sse-gen` closed - false if it was already closed
(console-error! sse-gen msg)(console-error! sse-gen msg opts)Log error msg in the browser console.
Same behavior as execute-script!.
Log error msg in the browser console. Same behavior as [[execute-script!]].
(console-log! sse-gen msg)(console-log! sse-gen msg opts)Log msg in the browser console.
Same behavior as execute-script!.
Log msg in the browser console. Same behavior as [[execute-script!]].
(datastar-request? request)Test for the presence of the datastar header in a ring request. The presence of the header means the request is issued from a datastar action.
Test for the presence of the datastar header in a ring request. The presence of the header means the request is issued from a datastar action.
(execute-script! sse-gen script-text)(execute-script! sse-gen script-text opts)Construct a HTML script tag using script-text as its content. Then sends it
to the brower using patch-elements! with patch-mode set to
pm-append and selector set to "body".
The default behavior is to auto remove the script after it has run.
Args:
sse-gen: the sse generator to send fromscript-text: string that represents the JavaScript to be executed
by the browser.opts: An options mapOptions keys:
idretry-durationauto-remove defaults to trueattributesReturn value:
false if the connection is closedtrue otherwiseConstruct a HTML script tag using `script-text` as its content. Then sends it to the brower using [[patch-elements!]] with [[patch-mode]] set to [[pm-append]] and [[selector]] set to `"body"`. The default behavior is to auto remove the script after it has run. Args: - `sse-gen`: the sse generator to send from - `script-text`: string that represents the JavaScript to be executed by the browser. - `opts`: An options map Options keys: - [[id]] - [[retry-duration]] - [[auto-remove]] defaults to true - [[attributes]] Return value: - `false` if the connection is closed - `true` otherwise
(get-signals ring-request)Extract datastar signals from a ring request map.
This function returns either a string or an InputStream depending on the HTTP method of the request.
:query-params map of the request)InputStream is returned (the signals are the
:body of the request)We do not impose any json parsing library. This means that you need to bring your own to parse the returned value into Clojure data.
Extract datastar signals from a ring request map. This function returns either a string or an InputStream depending on the HTTP method of the request. - In the case of a GET request a string is returned (the signals are found in the `:query-params` map of the request) - For all other HTTP methods an `InputStream` is returned (the signals are the `:body` of the request) We do not impose any json parsing library. This means that you need to bring your own to parse the returned value into Clojure data.
SSE option use in all event functions, string:
Each event may include an eventId. This can be used by the backend to replay events. This is part of the SSE spec and is used to tell the browser how to handle the event. For more details see https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#id
SSE option use in all event functions, string: Each event may include an eventId. This can be used by the backend to replay events. This is part of the SSE spec and is used to tell the browser how to handle the event. For more details see https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#id
(lock-sse! sse-gen & body)Hold onto the lock of a sse-gen while executing body. This allows for
preventing concurent sending of sse events. Sse generators use
[[java.util.concurrent.locks.ReentrantLock]] under the hood.
Ex:
(lock-sse! my-sse-gen
(patch-elements! sse frags)
(patch-signals! sse signals))
Hold onto the lock of a `sse-gen` while executing `body`. This allows for
preventing concurent sending of sse events. Sse generators use
[[java.util.concurrent.locks.ReentrantLock]] under the hood.
Ex:
```clojure
(lock-sse! my-sse-gen
(patch-elements! sse frags)
(patch-signals! sse signals))
```
patch-signals! option, boolean:
Whether to patch the signal only if it does not already exist. If not provided, the Datastar client side will default to false, which will cause the data to be patchd into the signals.
[[patch-signals!]] option, boolean: Whether to patch the signal only if it does not already exist. If not provided, the Datastar client side will default to false, which will cause the data to be patchd into the signals.
(patch-elements! sse-gen elements)(patch-elements! sse-gen elements opts)Send HTML elements to the browser to be patchd into the DOM.
Args:
sse-gen: the sse generator to send fromelements: A string of HTML elements.opts: An options mapOptions keys:
Return value:
false if the connection is closedtrue otherwiseSend HTML elements to the browser to be patchd into the DOM. Args: - `sse-gen`: the sse generator to send from - `elements`: A string of HTML elements. - `opts`: An options map Options keys: - [[id]] - [[retry-duration]] - [[selector]] - [[patch-mode]] - [[use-view-transition]] Return value: - `false` if the connection is closed - `true` otherwise
(patch-elements-seq! sse-gen elements)(patch-elements-seq! sse-gen elements opts)Same as patch-elements! except that it takes a seq of elements.
Same as [[patch-elements!]] except that it takes a seq of elements.
patch-elements! & patch-elements-seq! option, string:
The mode to use when merging elements into the DOM. If not provided the Datastar client side will default to morph.
The set of valid values is:
[[patch-elements!]] & [[patch-elements-seq!]] option, string: The mode to use when merging elements into the DOM. If not provided the Datastar client side will default to morph. The set of valid values is: - [[pm-outer]] default - [[pm-inner]] - [[pm-remove]] - [[pm-prepend]] - [[pm-append]] - [[pm-before]] - [[pm-after]] - [[pm-replace]]
(patch-signals! sse-gen signals-content)(patch-signals! sse-gen signals-content opts)Send signals to the browser using RFC 7386 JSON Merge Patch semantics.
Args:
sse-gen: the sse generator to send fromsignals-content: a JavaScript object or JSON string that will be sent to
the browser to update signals. The data must evaluate to a
valid JavaScript Object. null values for keys in this JSON object mean
that the signal at these keys are to be removed.opts: An options mapOptions keys:
Return value:
false if the connection is closedtrue otherwise
Send signals to the browser using
[RFC 7386 JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386)
semantics.
Args:
- `sse-gen`: the sse generator to send from
- `signals-content`: a JavaScript object or JSON string that will be sent to
the browser to update signals. The data must evaluate to a
valid JavaScript Object. `null` values for keys in this JSON object mean
that the signal at these keys are to be removed.
- `opts`: An options map
Options keys:
- [[id]]
- [[retry-duration]]
- [[only-if-missing]]
Return value:
- `false` if the connection is closed
- `true` otherwise
patch mode: inserts the element after the existing element.
patch mode: inserts the element after the existing element.
patch mode: appends the element to the existing element.
patch mode: appends the element to the existing element.
patch mode: inserts the element before the existing element.
patch mode: inserts the element before the existing element.
patch mode: replaces the inner HTML of the existing element.
patch mode: replaces the inner HTML of the existing element.
patch mode: replaces the outer HTML of the existing element.
patch mode: replaces the outer HTML of the existing element.
patch mode: prepends the element to the existing element.
patch mode: prepends the element to the existing element.
patch mode: remove the existing element from the dom.
patch mode: remove the existing element from the dom.
patch mode: Do not morph, simply replace the whole element and reset any related state.
patch mode: Do not morph, simply replace the whole element and reset any related state.
(redirect! sse-gen url)(redirect! sse-gen url opts)Redirect a page using a script.
Same behavior as execute-script!.
Redirect a page using a script. Same behavior as [[execute-script!]].
(remove-element! sse-gen selector)(remove-element! sse-gen selector opts)Remove element(s) from the dom. It is a convenience function using
patch-elements! with the patch-mode options set to pm-remove
and a selector set to selector.
Args:
sse-gen: the sse generator to send fromselector: string, CSS selector that represents the elements to be
removed from the DOM.opts: options mapOptions keys:
Return value:
false if the connection is closedtrue otherwiseRemove element(s) from the dom. It is a convenience function using [[patch-elements!]] with the [[patch-mode]] options set to [[pm-remove]] and a [[selector]] set to `selector`. Args: - `sse-gen`: the sse generator to send from - `selector`: string, CSS selector that represents the elements to be removed from the DOM. - `opts`: options map Options keys: - [[id]] - [[retry-duration]] - [[use-view-transition]] Return value: - `false` if the connection is closed - `true` otherwise
SSE option used in all event functions, number:
Each event may include a retryDuration value. If one is not provided the SDK must default to 1000 milliseconds. This is part of the SSE spec and is used to tell the browser how long to wait before reconnecting if the connection is lost. For more details see https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry
SSE option used in all event functions, number: Each event may include a retryDuration value. If one is not provided the SDK must default to 1000 milliseconds. This is part of the SSE spec and is used to tell the browser how long to wait before reconnecting if the connection is lost. For more details see https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry
patch-elements! & patch-elements-seq! option, string:
The CSS selector to use to insert the elements. If not provided or empty, Datastar will default to using the id attribute of the element.
[[patch-elements!]] & [[patch-elements-seq!]] option, string: The CSS selector to use to insert the elements. If not provided or empty, Datastar will default to using the id attribute of the element.
(sse-delete url)(sse-delete url opts-string)Helper making a @delete(...) action.
Helper making a @delete(...) action.
(sse-get url)(sse-get url opts-string)Helper making a @get(...) action.
Helper making a @get(...) action.
(sse-patch url)(sse-patch url opts-string)Helper making a @patch(...) action.
Helper making a @patch(...) action.
(sse-post url)(sse-post url opts-string)Helper making a @post(...) action.
Helper making a @post(...) action.
(sse-put url)(sse-put url opts-string)Helper making a @put(...) action.
Helper making a @put(...) action.
patch-elements! / [[remove-element!] option, boolean:
Whether to use view transitions, if not provided the Datastar client side will default to false.
[[patch-elements!]] / [[remove-element!] option, boolean: Whether to use view transitions, if not provided the Datastar client side will default to false.
(with-open-sse sse-gen & body)Macro functioning similarly to [[clojure.core/with-open]]. It evalutes the
body inside a try expression and closes the sse-gen at the end using
[[close-see!]] in a finally clause.
Ex:
(with-open-sse sse-gen
(d*/patch-elements! sse-gen frag1)
(d*/patch-signals! sse-gen signals))
Macro functioning similarly to [[clojure.core/with-open]]. It evalutes the `body` inside a try expression and closes the `sse-gen` at the end using [[close-see!]] in a finally clause. Ex: ``` (with-open-sse sse-gen (d*/patch-elements! sse-gen frag1) (d*/patch-signals! sse-gen signals)) ```
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |