IslandView

IslandView — template helpers for embedding islands in server-rendered HTML.

Use these functions in controller templates to render island wrappers and include the client runtime scripts.

Dataflow modes: island_server/2 — Server-mode island (read-only, no event listeners) island/2 — Client-mode island (owns its state, handles events) island_ssr/3 — Client-mode with server-rendered inner HTML

Channel sync (Client mode only): island_with_channel/3 — wire up a channel topic; state syncs after each update

Parent-child binding: island_child/4 — child island slotted inside a parent island_child_ssr/5 — child island with server-rendered initial HTML

Dataflow helpers (for template use): island_with_dataflow/3 — island with explicit dataflow string island_ssr_with_dataflow/4 — island with SSR content and explicit dataflow string child_island/4 — child island with SSR content

Hydration strategy variants: island_with_strategy/3 — specify eager/lazy/on-visible/on-idle island_ssr_with_strategy/4

Example (in a controller template):

let counter_html = IslandView.island_ssr("Counter", "{\"count\":0}", Counter.render("{\"count\":0}"))
let scripts      = IslandView.scripts()
"<html><body>" ++ counter_html ++ scripts ++ "</body></html>"

See also: island_socket.march, island_assets.march, islands.march.

Functions

fnchild_islandchild_island(name : String, parent_id : String, state_json : String, inner_html : String) : String#

Render a child island with SSR content and a parent reference.

A convenience wrapper for the common case of a child island with initial
server-rendered HTML and a parent binding. Uses Server dataflow (children
are always Server-dataflow relative to their parent).

Parameters:
  name      — child island module name
  parent_id — parent island instance ID
  state_json — initial state JSON (derived from parent state)
  inner_html — server-rendered inner HTML

fnislandisland(name : String, state_json : String) : String#

Render a Client-mode island placeholder with initial state.

The JS runtime attaches event listeners and routes data-on-* events
to the island's local update function.

fnisland_childisland_child(name : String, parent_id : String, on_event : String, state_json : String) : String#

Render a child island placeholder slotted inside a parent.

The JS runtime uses data-march-parent to walk up the tree when the child
dispatches an event. The parent's handle_child_event is called with the
event name and payload JSON.

Parameters:
  name      — child island module name
  parent_id — parent's data-march-instance-id value
  on_event  — event handler name registered on the parent
  state_json — initial state JSON (derived from parent state)

fnisland_child_ssrisland_child_ssr(name : String, parent_id : String, on_event : String, state_json : String, inner_html : String) : String#

Render a child island with server-rendered initial HTML.

fnisland_serverisland_server(name : String, state_json : String) : String#

Render a Server-mode island placeholder.

The JS runtime will not attach any event listeners to this island.
Use Server mode for display-only islands like live feeds, scoreboards, etc.

fnisland_server_ssrisland_server_ssr(name : String, state_json : String, inner_html : String) : String#

Render a Server-mode island with server-rendered inner HTML.

The inner_html is shown immediately; the JS runtime takes over on hydration
and patches the DOM as the server pushes new state.

fnisland_ssrisland_ssr(name : String, state_json : String, inner_html : String) : String#

Render a Client-mode island with server-rendered initial HTML.

The inner_html is displayed immediately while the WASM module loads.
On hydration the runtime takes over and patches the DOM as state changes.

fnisland_ssr_with_channelisland_ssr_with_channel(name : String, state_json : String, channel_topic : String, inner_html : String) : String#

Render a Client-mode island with SSR content wired to a channel.

fnisland_ssr_with_dataflowisland_ssr_with_dataflow(name : String, state_json : String, dataflow : String, inner_html : String) : String#

Render an island with SSR content and an explicit dataflow string.

dataflow should be "client" or "server".

fnisland_ssr_with_strategyisland_ssr_with_strategy(name : String, state_json : String, strat : String, inner_html : String) : String#

Render a Client-mode island with SSR content and a hydration strategy.

fnisland_with_channelisland_with_channel(name : String, state_json : String, channel_topic : String) : String#

Render a Client-mode island wired to a channel for state sync.

After each local update, the JS runtime pushes the new state JSON to the
channel topic. The channel can push state down at any time (last-write-wins).

Without a channel, use island/2 for purely local state.

Example:
  IslandView.island_with_channel("Counter", state_json, "counter:#{user_id}")

fnisland_with_dataflowisland_with_dataflow(name : String, state_json : String, dataflow : String) : String#

Render an island placeholder with an explicit dataflow string.

dataflow should be "client" or "server".

fnisland_with_strategyisland_with_strategy(name : String, state_json : String, strat : String) : String#

Render a Client-mode island placeholder with a hydration strategy.

strategy is one of: "eager", "lazy", "on-visible", "on-idle".

fnscriptsscripts() : String#

Generate the script tag that loads the island client runtime.

Include this in your layout <head> or before </body>.
Uses the default Bastion assets path.

fnscripts_with_basescripts_with_base(base_url : String) : String#

Generate the island runtime script tag with a custom base URL.

Example:
  IslandView.scripts_with_base("/assets")
  -- produces: <script src="/assets/islands.js"></script>

fnws_scriptsws_scripts() : String#

Generate the WebSocket connection script tag.

This script connects to the island WebSocket endpoint and wires up
the bidirectional message loop. Include after scripts().

fnws_scripts_with_basews_scripts_with_base(base_url : String) : String#

Generate the WebSocket script tag with a custom base URL.