Datastar.Script (DatastarEx v0.1.0)

View Source

Functions for executing JavaScript and managing browser state.

This module provides utilities for:

  • Executing arbitrary JavaScript code
  • Console logging
  • Browser navigation and URL manipulation
  • Custom event dispatching
  • Resource prefetching

Examples

# Execute JavaScript
sse |> Datastar.Script.execute("alert('Hello!')")

# Console logging
sse |> Datastar.Script.console_log("Debug message")

# Redirect
sse |> Datastar.Script.redirect("/dashboard")

# Dispatch custom event
sse |> Datastar.Script.dispatch_custom_event("my-event", %{detail: "data"})

Summary

Functions

console_error(sse, message, opts \\ [])

Logs an error to the browser console.

console_log(sse, message, opts \\ [])

Logs a message to the browser console.

dispatch_custom_event(sse, event_name, detail \\ %{}, opts \\ [])

Dispatches a custom DOM event.

execute(sse, script, opts \\ [])

Executes JavaScript code in the browser.

executef(sse, format, args, opts \\ [])

Executes JavaScript with string interpolation.

prefetch(sse, urls, opts \\ [])

Prefetches URLs using the Speculation Rules API.

redirect(sse, url, opts \\ [])

Redirects the browser to a new URL.

redirectf(sse, format, args, opts \\ [])

Redirects with string interpolation.

replace_url(sse, url, opts \\ [])

Replaces the current URL without navigation using history.replaceState.

replace_url_querystring(sse, querystring, opts \\ [])

Updates the URL query string without navigation.

Functions

console_error(sse, message, opts \\ [])

@spec console_error(Datastar.SSE.t(), String.t(), keyword()) :: Datastar.SSE.t()

Logs an error to the browser console.

Example

sse |> console_error("Something went wrong!")

console_log(sse, message, opts \\ [])

@spec console_log(Datastar.SSE.t(), String.t(), keyword()) :: Datastar.SSE.t()

Logs a message to the browser console.

Example

sse
|> console_log("User logged in")
|> console_log("Count: %{count}", count: 42)

dispatch_custom_event(sse, event_name, detail \\ %{}, opts \\ [])

@spec dispatch_custom_event(Datastar.SSE.t(), String.t(), map(), keyword()) ::
  Datastar.SSE.t()

Dispatches a custom DOM event.

Example

sse
|> dispatch_custom_event("user-updated", %{id: 123, name: "Alice"})
|> dispatch_custom_event("notification", %{message: "Saved!"}, selector: "#app")

execute(sse, script, opts \\ [])

@spec execute(Datastar.SSE.t(), String.t(), keyword()) :: Datastar.SSE.t()

Executes JavaScript code in the browser.

The script is wrapped in a <script> element and executed immediately.

Options

  • :auto_remove - Remove script element after execution (default: true)
  • :attributes - Map of additional attributes for the script element
  • :event_id - Event ID for client tracking
  • :retry - Retry duration in milliseconds

Example

sse
|> execute("console.log('Hello from server!')")
|> execute("document.title = 'Updated'", auto_remove: false)

executef(sse, format, args, opts \\ [])

@spec executef(Datastar.SSE.t(), String.t(), list(), keyword()) :: Datastar.SSE.t()

Executes JavaScript with string interpolation.

Example

sse |> executef("alert('%s')", ["Hello, World!"])

prefetch(sse, urls, opts \\ [])

@spec prefetch(Datastar.SSE.t(), [String.t()], keyword()) :: Datastar.SSE.t()

Prefetches URLs using the Speculation Rules API.

Example

sse |> prefetch(["/dashboard", "/profile"])

redirect(sse, url, opts \\ [])

@spec redirect(Datastar.SSE.t(), String.t(), keyword()) :: Datastar.SSE.t()

Redirects the browser to a new URL.

Uses setTimeout to ensure proper event processing before navigation.

Example

sse
|> redirect("/dashboard")
|> redirect("https://example.com")

redirectf(sse, format, args, opts \\ [])

@spec redirectf(Datastar.SSE.t(), String.t(), list(), keyword()) :: Datastar.SSE.t()

Redirects with string interpolation.

Example

sse |> redirectf("/users/%s/profile", [user_id])

replace_url(sse, url, opts \\ [])

@spec replace_url(Datastar.SSE.t(), String.t(), keyword()) :: Datastar.SSE.t()

Replaces the current URL without navigation using history.replaceState.

Example

sse |> replace_url("/new-path")

replace_url_querystring(sse, querystring, opts \\ [])

@spec replace_url_querystring(Datastar.SSE.t(), String.t(), keyword()) ::
  Datastar.SSE.t()

Updates the URL query string without navigation.

Example

sse |> replace_url_querystring("?page=2&sort=name")