apputil

Documentation

Overview

apputil is a collection of utilities to help build simple apptron programs. For example, they are used by the program created by the built-in apptron build subcommand.

Index

• func AppOptionsFromHTML(fsys fs.FS, filename, metaname string, fallback client.AppOptions) client.AppOptions
• func BackendServer(proxyTo *client.Client, muxExt func(mux *rpc.RespondMux)) http.Handler
• func Run(fsys fs.FS, userMethods interface{})
• func TempCommand(fsys fs.FS, cmdpath string) (string, func())
• func WindowOptionsFromHTML(fsys fs.FS, filename, metaname string, fallback client.WindowOptions) client.WindowOptions

Functions

func AppOptionsFromHTML

func AppOptionsFromHTML(fsys fs.FS, filename, metaname string, fallback client.AppOptions) client.AppOptions

func BackendServer

func BackendServer(proxyTo *client.Client, muxExt func(mux *rpc.RespondMux)) http.Handler

BackendServer returns an http.Handler that responds to builtin endpoints, all hardcoded with /-/ path prefix:

/-/ws: 						the WebSocket endpoint
/-/client.js: 		the JavaScript client module
/-/apptron.js:		the JavaScript loader
/-/chrome:				the builtin chrome pages dir

The WebSocket endpoint establishes a qtalk session that will proxy to the provided apptron Client. The client module served is the embeded JS client from the clientjs/dist "package". The loader is what would be included by an HTML page to create a $host global that points to the apptron client instance created after connecting to the WebSocket endpoint. The $host global also has a ready property which is a Promise resolved when the client is connected and ready to be used.

The optional muxExt callback allows you to handle custom RPC selectors that will be matched against before attempting to pass them to the apptron Client.

If none of the endpoints are matched against, a NotFound error is returned. If serving other endpoints, put this behind a check for the /-/ path prefix.

func Run

func Run(fsys fs.FS, userMethods interface{})

Run takes a filesystem and optional userMethods value to start a simple apptron program that serves the filesystem over HTTP to be used by apptron windows. It launches a main window pointing at index.html from the filesystem, using meta tags via OptionsFromHTML to define options for this main window. It also serves a backend using BackendServer that lets you include /-/apptron.js which creates a "$host" global that exposes the apptron API. This API can be extended by the methods on the userMethods value, made accessible as callables via "$host.rpc.user".

If the apptron binary is included in the filesystem as "./apptron", then it will use TempCommand to write it to disk and the BRIDGECMD environment variable to use it.

This can be used either as-is or as a reference for your own apptron programs, but is mainly used by programs produced by the built-in build subcommand.

func TempCommand

func TempCommand(fsys fs.FS, cmdpath string) (string, func())

TempCommand checks for the base name of cmdpath in PATH and if it doesn't find it, it will write out the file from fsys at cmdpath to a temporary directory as executable, returning the file path to it and a function to remove both.

If the command is found in PATH or any step fails for any reason, TempCommand returns an empty string and a no-op function.

This is intended to be used when embedding the apptron binary in a program, using this to write it out to disk temporarily, the path to which can be used to set the BRIDGECMD env var used by the apptron client Spawn function. It should also be cleaned up when the program finishes.

func WindowOptionsFromHTML

func WindowOptionsFromHTML(fsys fs.FS, filename, metaname string, fallback client.WindowOptions) client.WindowOptions

OptionsFromHTML will use fsys to open filename and parse it as HTML to find a meta element within the head element with metaname for its name attribute and produce a WindowOptions populated with the comma-separated key-values of the meta elements content attribute. If there is no key-value for a field of WindowOptions, or is the HTML, Icon, or Script field, the value from fallback is used.

If a title element is found within the head element, its value will be used. If the meta element comes after the title element and includes a key-value for title, it will be used instead.

All keys in the content attribute are lowercase equivalents of their field name. However, for Position.X and Position.Y, keys x and y are used. Size.Width and Size.Height keys are width and height. Keys for MinSize and MaxSize fields are min-width, min-height, max-width, and max-height, respectively.

String values can optionally be wrapped in single quotes, boolean values must be true or false. Any errors in parsing values will result in using the fallback struct value.