wasm

README

NOTE: This is a work in progress and neither the doc nor the package is ready for rock and roll.

WebGear WASM provides packages to simplify using WASM in Go utilizing by boostrapping all files needed for WASM, utilizing the Webear html package and providing UI DOM manipulation without having to get into syscall/JS.

Why Use This?

• You dislike Javascript
• You like the other WebGear packages
• You don't want to figure out how to bootstap WASM

Production Ready?

Nope.

Look, WASM is still somewhat experimental in Go. WASM itself is designed for C++ and doesn't have GC hooks. So binaries are bigger than they should be. Yeah, there is tinyGo, but that starts getting way harder.

Here's the thing: is your app a large codebase that is revenue generating at scale? If so, go back to JS.

If not (99% of everyone out there), you can try something different.

Concepts

How WASM bootstrapping works

Conceptually, WASM is like Javascript. With JS you push code from the server to the browswer and the browser runs the code.

The big differences are that with WASM, you push Javascript and HTML to the browser that then fetches your WASM from the server and then runs it.

The Javascript for bootstrapping is provided by the Go team. But you have to serve it and setup the WASM download.

Luckily for you we automate that whole thing so you don't have to worry about it.

WASM code is compiled for a different environment

When you write your WASM code, you will be compiling for a new target. You can't run tests like normal because you can't run WASM in your environment. Basically any package that uses syscall/js cannot be tested in your normal environment.

When you want to see changes, you have to recompile the WASM and re-run your server

You can't just "go run main.go". Your server is serving a WASM file, that WASM file is its own compiled binary.

As you will see below, this just means there are two compilations that must happen.

Documentation

Overview

Package wasm provides the application entrance for WASM applications and the API for making UI changes. In this context, WASM applications are built off the webgear frameworks and update via this package's UI object.

This package is used in two different places

Inside your Wasm app where you will use the Wasm type to create your client.
Inside your web server that is serving the Wasm app where you will use the Handler() func to generate a handler that loads your app.

WASM apps are binaries that are pre-compiled but loaded via JS served from a web browser. Normally it requires an HTML page and JS bootstrapping. We provide the http.Handler that can mount this app and all the bootstrapping JS code.

This package along with the webgear/html and webgear/component remove the need to use HTML or JS within your application.

The app handles all the client display and should fetch content from the server in which to display. This should be done via REST or other HTTP based calls.

Index

• func AttachHandler(event html.EventType, release bool, fn html.WasmFunc, args interface{}, ...) html.Element
• func AttachListener(event html.ListenerType, release bool, fn html.WasmFunc, args interface{}, ...) html.Element
• func GetDocUpdater() *html.DocUpdater
• type Wasm
  • func New() *Wasm
  • func (w *Wasm) Ready()
  • func (w *Wasm) Run(ctx context.Context)
  • func (w *Wasm) SetDoc(doc *html.Doc)

Functions

func AttachHandler

func AttachHandler(event html.EventType, release bool, fn html.WasmFunc, args interface{}, element html.Element) html.Element

AttachHandler attaches a Func to an html.Element for a specific event like a mouse click (PLEASE READ THE REST BEFORE USE). If release is set, the function will release its memory after being called. This should be used when something like a button will not be used again in this evocation. Attach spins out a new goroutine for you to prevent blocking calls from pausing the event loop. Note that this may have negative consequences on performance, but that pause is such a hastle to track down for every new dev that I don't care about that. This func() attaches based on the element's .GlobalAttrs.ID. If that is not set, this is going to panic. As this is an event handler, it replaces any existing handlers. Use even listeners to assign multiple actions.

func AttachListener

func AttachListener(event html.ListenerType, release bool, fn html.WasmFunc, args interface{}, element html.Element) html.Element

AttachListener attaches a Func to an html.Element for a specific event like a mouse click (PLEASE READ THE REST BEFORE USE). If release is set, the function will release its memory after being called. This should be used when something like a button will not be used again in this evocation. Attach spins out a new goroutine for you to prevent blocking calls from pausing the event loop. Note that this may have negative consequences on performance, but that pause is such a hastle to track down for every new dev that I don't care about that. This func() attaches based on the element's .GlobalAttrs.ID. If that is not set, this is going to panic.

func GetDocUpdater

func GetDocUpdater() *html.DocUpdater

GetDocUpdater gets a *DocUpdater for updating the DOM. There is only one of these available for use at any time. Use DocUpdater.Render() to release it. This will block if another call has not released it.

Types

type Wasm

type Wasm struct {
	// contains filtered or unexported fields
}

Wasm represents a self contained WASM application.

func New

func New() *Wasm

New creates a new Wasm instance.

func (*Wasm) Ready

func (w *Wasm) Ready()

Ready will block until Run() has rendered the initial document. Mostly used in tests.

func (*Wasm) Run

func (w *Wasm) Run(ctx context.Context)

Run executes replaces the content of the current document with the *html.Doc passed in New(). This never returns unless the initial doc cannot be rendered, which will cause a panic.

func (*Wasm) SetDoc

func (w *Wasm) SetDoc(doc *html.Doc)

SetDoc sets the initial doc that will be displayed.