classDocs / WebClient

WebClient

classclientsource

Object → WebClient

A headless HTML panel for running browser JavaScript, WebSockets and other web APIs from Lua without painting a visible UI.

JS↔Lua uses the engine HTML bridge (NewObject / NewObjectCallback / OnCallback) via :bind. Page-driven Lua (SetAllowLua / RUNLUA:) stays off; use :bind instead.

Create with WebClient(), attach handlers, assign url or html (a new client has no document and stays "loading" until then, or until the first :run), then :run JS / :bind Lua bridges. Prefer waiting for "ready" (or using the built-in JS queue) before touching the document on Chromium.

Constructor

WebClient(width: integer?, height: integer?): WebClient

Fields

Name	Type	Description
`url`	`( string \| nil )`	The current document URL; assigning opens it (`http(s)://`, `asset://`, `about:blank`, ...), resets readiness and drops queued JS.
`html`	`( string \| nil )`	The current document HTML; assigning replaces the document, resets readiness and drops queued JS. Reads return the assigned source until the next `"load"`, then a snapshot of the parsed DOM (normalized markup) taken right after every `"load"` fires; `nil` after a `url` assignment until that snapshot arrives.

Methods

`__isvalid`	Returns true while the underlying HTML panel still exists.
`attach`	Attaches a handler for the given event.
`await`	Waits until the given event fires, then resumes with that event's arguments.
`bind`	Exposes a Lua function to JavaScript as object.method( ... ).
`clear`	Removes every handler for event, or every handler of every event when omitted.
`close`	Destroys the panel and fires "destroy".
`destroy`	Alias of WebClient:close.
`detach`	Detaches a previously attached handler from the given event.
`getStatus`	Returns the current lifecycle status as a string.
`isClosed`	Returns true after :close / panel removal.
`isLoading`	Returns true while a document is loading.
`isReady`	Returns true when the document is ready for immediate :run calls.
`once`	Attaches a one-shot handler for the given event.
`refresh`	Reloads the current document.
`run`	Executes JavaScript in the panel.
`stop`	Stops the current navigation / load, if any.
`unbind`	Removes a function exposed with :bind.

#WebClient:__isvalid

clientnodiscardsource

function WebClient:__isvalid(): boolean

Returns true while the underlying HTML panel still exists.

Returns

Type	Name	Description
`boolean`	`is_valid`

#WebClient:attach

clientsource

function WebClient:attach(event: WebClient.Event, handler: function)

Attaches a handler for the given event.

Parameters

Name	Type	Description
`event`	`WebClient.Event`
`handler`	`function`

Overloads

function WebClient:attach(self: WebClient, event: "ready", handler: WebClient.ReadyHandler)

function WebClient:attach(self: WebClient, event: "load", handler: WebClient.LoadHandler)

function WebClient:attach(self: WebClient, event: "begin", handler: WebClient.BeginHandler)

function WebClient:attach(self: WebClient, event: "console", handler: WebClient.ConsoleHandler)

function WebClient:attach(self: WebClient, event: "title", handler: WebClient.TitleHandler)

function WebClient:attach(self: WebClient, event: "url", handler: WebClient.UrlHandler)

function WebClient:attach(self: WebClient, event: "message", handler: WebClient.MessageHandler)

function WebClient:attach(self: WebClient, event: "destroy", handler: WebClient.DestroyHandler)

#WebClient:await

clientasyncsource

async function WebClient:await(event: WebClient.Event): any

Waits until the given event fires, then resumes with that event's arguments.

"ready" returns immediately on a ready client and "destroy" on a closed one. Awaiting any other event throws if the client is closed, or gets closed while waiting.

Parameters

Name	Type	Description
`event`	`WebClient.Event`

Returns

Type	Name	Description
`any`	`...`

Overloads

function WebClient:await(self: WebClient, event: "ready"): WebClient, string

function WebClient:await(self: WebClient, event: "load"): WebClient, string

function WebClient:await(self: WebClient, event: "begin"): WebClient, string

function WebClient:await(self: WebClient, event: "console"): WebClient, ( string | nil ), ( string | nil ), ( number | nil ), ( string | nil )

function WebClient:await(self: WebClient, event: "title"): WebClient, ( string | nil )

function WebClient:await(self: WebClient, event: "url"): WebClient, string

function WebClient:await(self: WebClient, event: "message"): WebClient, ( string | nil ), ( string | nil )

function WebClient:await(self: WebClient, event: "destroy"): WebClient

#WebClient:bind

clientsource

function WebClient:bind(path: string, callback: fun( ...: any ): any)

Exposes a Lua function to JavaScript as object.method( ... ).

path is exactly one object.method pair of JS identifiers ( [A-Za-z_$][A-Za-z0-9_$]* ), the engine has no nested objects: "a.b.c" would become a global literally named "a.b". The object is a global created on first use and survives navigation.

Arguments arriving from JS are strings / numbers / booleans only; serialize structured data on the JS side (e.g. JSON.stringify) and parse in Lua.

Values returned by callback are forwarded back to JS asynchronously: pass a trailing JS function, e.g. lua.add( 2, 3, function( result ) { ... } ); the direct JS return is undefined. Errors are reported and yield nothing.

lua

web:bind( "lua.add", function( a, b ) return a + b end )

Parameters

Name	Type	Description
`path`	`string`	The JavaScript `"object.method"` path, e.g. `"lua.add"`.
`callback`	`fun( ...: any ): any`	Lua function invoked from JS.

#WebClient:clear

clientsource

function WebClient:clear(event?: WebClient.Event)

Removes every handler for event, or every handler of every event when omitted.

Parameters

Name	Type	Description
`event`optional	`WebClient.Event`

#WebClient:close

clientsource

function WebClient:close()

Destroys the panel and fires "destroy". Further methods throw.

#WebClient:destroy

clientsource

function WebClient:destroy()

Alias of WebClient:close.

#WebClient:detach

clientsource

function WebClient:detach(event: WebClient.Event, handler: function)

Detaches a previously attached handler from the given event.

Parameters

Name	Type	Description
`event`	`WebClient.Event`
`handler`	`function`

Overloads

function WebClient:detach(self: WebClient, event: "ready", handler: WebClient.ReadyHandler)

function WebClient:detach(self: WebClient, event: "load", handler: WebClient.LoadHandler)

function WebClient:detach(self: WebClient, event: "begin", handler: WebClient.BeginHandler)

function WebClient:detach(self: WebClient, event: "console", handler: WebClient.ConsoleHandler)

function WebClient:detach(self: WebClient, event: "title", handler: WebClient.TitleHandler)

function WebClient:detach(self: WebClient, event: "url", handler: WebClient.UrlHandler)

function WebClient:detach(self: WebClient, event: "message", handler: WebClient.MessageHandler)

function WebClient:detach(self: WebClient, event: "destroy", handler: WebClient.DestroyHandler)

#WebClient:getStatus

clientnodiscardsource

function WebClient:getStatus(): WebClient.Status

Returns the current lifecycle status as a string.

Returns

Type	Name	Description
`WebClient.Status`	`status`	`"closed"`, `"loading"` or `"ready"`.

#WebClient:isClosed

clientnodiscardsource

function WebClient:isClosed(): boolean

Returns true after :close / panel removal.

Returns

Type	Name	Description
`boolean`	`is_closed`

#WebClient:isLoading

clientnodiscardsource

function WebClient:isLoading(): boolean

Returns true while a document is loading.

Returns

Type	Name	Description
`boolean`	`is_loading`

#WebClient:isReady

clientnodiscardsource

function WebClient:isReady(): boolean

Returns true when the document is ready for immediate :run calls.

Returns

Type	Name	Description
`boolean`	`is_ready`

#WebClient:once

clientsource

function WebClient:once(event: WebClient.Event, handler: function)

Attaches a one-shot handler for the given event.

Parameters

Name	Type	Description
`event`	`WebClient.Event`
`handler`	`function`

Overloads

function WebClient:once(self: WebClient, event: "ready", handler: WebClient.ReadyHandler)

function WebClient:once(self: WebClient, event: "load", handler: WebClient.LoadHandler)

function WebClient:once(self: WebClient, event: "begin", handler: WebClient.BeginHandler)

function WebClient:once(self: WebClient, event: "console", handler: WebClient.ConsoleHandler)

function WebClient:once(self: WebClient, event: "title", handler: WebClient.TitleHandler)

function WebClient:once(self: WebClient, event: "url", handler: WebClient.UrlHandler)

function WebClient:once(self: WebClient, event: "message", handler: WebClient.MessageHandler)

function WebClient:once(self: WebClient, event: "destroy", handler: WebClient.DestroyHandler)

#WebClient:refresh

clientsource

function WebClient:refresh(ignore_cache?: boolean)

Reloads the current document.

Parameters

Name	Type	Description
`ignore_cache`optional	`boolean`	When `true`, bypasses the HTTP cache. Defaults to `false`.

#WebClient:run

clientsource

function WebClient:run(js: string)

Executes JavaScript in the panel.

If the document is not ready yet, the snippet is queued and flushed on the next "ready" event (required on Chromium, which does not delay RunJavascript). On a client that has no document yet (no url / html assigned), a blank one is started.

Parameters

Name	Type	Description
`js`	`string`	JavaScript source to run.

#WebClient:stop

clientsource

function WebClient:stop()

Stops the current navigation / load, if any.

#WebClient:unbind

clientsource

function WebClient:unbind(path: string): boolean

Removes a function exposed with :bind.

The engine cannot unregister NewObjectCallback functions, so the Lua callback is dropped and the JS function is deleted from window now and again on every "ready" (the engine re-injects it into each new document). The object is deleted too once it has no bound methods.

Parameters

Name	Type	Description
`path`	`string`	The JavaScript `"object.method"` path given to `:bind`.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if `path` was bound.