R uflet

Widgets

WebView

WebView

Embeds a web page inside the app. On iOS, Android and macOS it is a native webview that can run JavaScript and navigate freely; on the web it falls back to an <iframe>, so it can only show pages that allow framing (most sites that send X-Frame-Options/CSP will appear blank), and the methods/events below are not available there.

Example

web_view(
  url: "https://ruflet.dev",
  method: "get",
  expand: true,
  on_page_ended: ->(event) { @loading = false }
)

Properties

  • url — the page to load.
  • bgcolor — background color shown before the page paints.
  • prevent_links — an array of URL prefixes the webview must not follow; a tap

on a matching link is blocked instead of navigating.

  • enable_javascript — enable/disable JavaScript execution.
  • method — HTTP method used for the initial url request (e.g. "get").
  • expand — fill the available space in a row/column.
  • width / height — fixed size when not expanding.
  • tooltip, visible, opacity, rtl — the usual layout properties.

Events

  • on_page_started — page load has begun (data: the URL).
  • on_page_ended — page load finished (data: the URL).
  • on_web_resource_error — a resource failed to load (data: the description).
  • on_progress — load progress changed (data: 0–100).
  • on_url_change — the current URL changed (data: the new URL).
  • on_scroll — the scroll position changed (data: {x, y}).
  • on_console_message — a JavaScript console.* message (data: {message, severity_level}).
  • on_javascript_alert_dialog — the page called alert() (data: {message, url}).

Methods

Call these on a mounted webview (after page.add). They run on iOS/Android/macOS.

  • reload — reload the current page.
  • go_back / go_forward — move through history.
  • can_go_back { |ok, _err| } / can_go_forward { |ok, _err| } — query history; result delivered to the block.
  • run_javascript(value) — execute JavaScript in the page.
  • load_html(value, base_url:) — load an HTML string.
  • load_request(url, method:) — load a URL with an HTTP method.
  • load_file(path) — load a local HTML file.
  • scroll_to(x, y) / scroll_by(x, y) — scroll to / by an offset.
  • clear_cache / clear_local_storage — clear browser storage.
  • enable_zoom / disable_zoom — toggle pinch-zoom.
  • set_javascript_mode(mode) — set the JavaScript execution mode.
  • get_current_url { |url, _err| } / get_title { ... } / get_user_agent { ... } — read state into the block.

Injecting JavaScript

run_javascript lets the app reach into the page — for example, hide a node so a native control can take its place:

webview = web_view(url: "https://myapp.com", method: "get", expand: true)
page.add(webview)

# later, in a handler:
webview.run_javascript("document.querySelector('.web-banner')?.remove()")

Reading a value back

webview.get_current_url { |url, _err| page.update(label, value: url) }

Building native shells

To wrap a Rails website in a native shell and turn annotated link taps into native navigation, see Native Shell. Ruflet::Rails.native_shell provides the managed navigation stack.

Reference

  • Family: materials
  • Widget type: webview
  • Helper: web_view

Complete API

Helpers

  • web_view(**props)
  • webview(**props)

Accepted properties

  • bgcolor — Background color.
  • data — Arbitrary value you can attach to the control and read back in handlers.
  • enable_javascript — Sets the enable javascript property.
  • expand — Fills the available space along the parent's main axis when true.
  • height — Fixed height in logical pixels.
  • key — Stable identity used to preserve state across rebuilds.
  • method — Sets the method property.
  • opacity — Opacity from 0.0 (transparent) to 1.0 (opaque).
  • prevent_links — Sets the prevent links property.
  • rtl — Renders right-to-left when true.
  • tooltip — Text shown on hover/long-press.
  • url — URL the control loads or links to.
  • visible — Hides the control when false.
  • width — Fixed width in logical pixels.

Events

  • on_page_ended — Fired on page ended.
  • on_page_started — Fired on page started.
  • on_web_resource_error — Fired on web resource error.
  • on_progress — Fired on progress.
  • on_url_change — Fired on url change.
  • on_scroll — Fired when the scroll position changes.
  • on_console_message — Fired on console message.
  • on_javascript_alert_dialog — Fired on javascript alert dialog.

Methods

  • can_go_back(timeout: ..., &on_result)
  • can_go_forward(timeout: ..., &on_result)
  • clear_cache
  • clear_local_storage
  • disable_zoom
  • enable_zoom
  • get_current_url(timeout: ..., &on_result)
  • get_title(timeout: ..., &on_result)
  • get_user_agent(timeout: ..., &on_result)
  • go_back
  • go_forward
  • load_file(path)
  • load_html(value, base_url: ...)
  • load_request(url, method: ...)
  • reload
  • run_javascript(value)
  • scroll_by(x, y)
  • scroll_to(x, y)
  • set_javascript_mode(mode)

Wire reference

  • Family: materials
  • Widget type: WebView
Previous View Next WindowDragArea