Skip to content

Module 5: WebView

Wx::WEB::WebView embeds a full browser engine in your desktop app — WebKit on macOS and Linux, Edge WebView2 on Windows. Everything that works in a modern browser works in a WebView: CSS, JavaScript, third-party libraries, canvas, SVG, local storage. This module covers how to use it effectively and how to build a clean bidirectional communication channel between Ruby and JavaScript.

What this module covers

Lesson 5.1 — WebView basics introduces the WebView widget, its three content loading approaches (inline HTML, CDN libraries, base64 data URIs), and the WebView event lifecycle. Demonstrates the upgrade from HtmlWindow to WebView in the Module 4 markdown editor.

Lesson 5.2 — The JavaScript bridge covers the three levels of Ruby↔JS communication: navigation interception (simplest, JS→Ruby only), script message handler (bidirectional, WebKit native), and the JsBridge class (full RPC with responses). Three separate working demos, each clearly demonstrating what it can and cannot do. Introduces the critical ready pattern.

Lesson 5.3 — Live data with Chart.js builds a live sensor dashboard feeding simulated data into Chart.js charts via JsBridge. Demonstrates the full multi-file architecture applied to a WebView app, querying data back from JS, and the timer-driven update pattern.

Lesson 5.4 — Leaflet maps embeds an interactive Leaflet map with click-to-place markers and city navigation. Covers CDN vs local file loading for Leaflet assets, map events flowing to Ruby, and Ruby controlling the map via JsBridge.

Lesson 5.5 — Project: Markdown editor with WebView upgrades the Module 4 markdown editor from HtmlWindow to WebView, adding syntax highlighting via highlight.js. The model and editor panel are unchanged — only the preview panel is replaced. The comparison makes explicit what WebView adds over HtmlWindow.

The bridge library

Two files are shared across all Module 5 apps. Copy them into any WebView project:

  • js_bridge.rb — the Ruby side, require_relatived into your frame
  • js_bridge_client.js — the JavaScript side, loaded as a base64 data URI

These files are also used in the Module 6 real-world apps.

The ready pattern

The single most important thing to understand about WebView and JsBridge:

Never rely on JS emitting ready at the end of the page script. By the time evt_webview_loaded fires, the page script has already executed — the message handler was not yet registered. Always have Ruby trigger ready after registering the handler:

1
2
3
4
5

@webview.evt_webview_loaded(@webview.id) do
  next if @webview.current_url == 'about:blank'
  @webview.add_script_message_handler('bridge')
  @bridge.run_script("RubyBridge.emit('ready', {})")  # Ruby triggers this
end

Prerequisites

This module assumes you have completed Modules 3 and 4. Lessons 5.3 and 5.5 require internet access for CDN resources. Lesson 5.5 requires kramdown:

1

gem install kramdown kramdown-parser-gfm

Previous: Module 4 — Rich Output | Next: Lesson 5.1 — WebView basics