goui

README

goui

goui is a library for attaching a HTML/JS UI to a native go application. goui uses the operating system's default web browser to display the HTML/JS UI and uses Go to implement the application logic.

A goui app behaves like a native app, except that is opens a new browser tab instead of opening a new main window upon launch. This approach is more resource friendly compared to electron and friends, because it does not launch a separate browser and goui apps are small, because they do not need to ship a browser engine.

goui offers multiple mechanisms to communicate between the Go part and the browser part of the application. It is possible to call Go functions from the browser and to call Javascript functions from Go. Furthermore, Go can send events to the browser. Finally, goui can sync a data structure with the browser. Any changes applied to the Go data structure are automatically synced with the browser, where the same data is available as JSON. On the browser side, a UI framework such as Vue can be used to render a UI based on this JSON data.

Technical Details and Security

The Go part of the application communicates with the browser via a web socket on the loopback device. The initial URL contains a random token. The first request to the Go side exchanges this token with a cookie. All further communication between Go and browser are then authorized using this cookie.

Lifecycle

When the browser window or tab is closed, the Go application terminates. When the Go application is terminated first, the HTML/JS UI becomes disabled.

Documentation

Index

• func GenerateJSCode(obj interface{}) string
• func LaunchBrowser(url string) *exec.Cmd
• func MarshalDiff(v interface{}) ([]byte, error)
• type Dispatcher
  • func NewDispatcher(obj interface{}) *Dispatcher
  • func (d *Dispatcher) Dispatch(inv *invocation) ([]byte, error)
• type Field
• type Model
  • func (m *Model) ModelChildDirty()
  • func (m *Model) ModelDirty()
  • func (m *Model) ModelID() int
  • func (m *Model) ModelState() ModelState
  • func (m *Model) ModelSwapIndex(index int) int
  • func (m *Model) ModelSynced()
  • func (m *Model) ModelTestSync(parent ModelIface, field *Field) ModelState
• type ModelIface
• type ModelState
• type Window
  • func NewWindow(initialPath string, remote interface{}, model ModelIface) *Window
  • func (s *Window) Call(fname string, args ...interface{}) error
  • func (s *Window) Handle(pattern string, handler http.Handler)
  • func (s *Window) SendEvent(name string, event interface{}) error
  • func (s *Window) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Window) Start() error
  • func (s *Window) SyncModel() error
  • func (s *Window) Wait()

Functions

func GenerateJSCode

func GenerateJSCode(obj interface{}) string

GenerateJSCode creates a client-side javascript proxy for the object.

func LaunchBrowser

func LaunchBrowser(url string) *exec.Cmd

LaunchBrowser opens the URL in the default browser.

func MarshalDiff

func MarshalDiff(v interface{}) ([]byte, error)

MarshalDiff marshals

Types

type Dispatcher

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

Dispatcher can invoke functions on an object. A function call is passed in as a JSON message, the function is called and the result is returned as a JSON message.

func NewDispatcher

func NewDispatcher(obj interface{}) *Dispatcher

NewDispatcher creates a new dispatcher for the object

func (*Dispatcher) Dispatch

func (d *Dispatcher) Dispatch(inv *invocation) ([]byte, error)

Dispatch decodes the JSON msg and invokes a function on the object. It returns a JSON encoded return message.

type Field

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

A Field represents a single field found in a struct.

type Model

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

Model implements synchronization between the GO Model and the JavaScript Model in the browser. To use Model, build a model like this:

type MyModel struct {
    Model
    Value int
    OtherValue string
}

It is possible to build a hierarchy of models. A model can contain another child model or point to a child model. The graphs of models must form a tree at all times.

type RootModel struct {
    Model
    M1 *MyModel
    M2 MyModel
}

func (*Model) ModelChildDirty

func (m *Model) ModelChildDirty()

ModelChildDirty marks that a child model requires synchronization.

func (*Model) ModelDirty

func (m *Model) ModelDirty()

ModelDirty marks the object as requiring synchronization. The parent Models are automatically marked with ModelChildDirty.

func (*Model) ModelID

func (m *Model) ModelID() int

ModelID returns a unique id for the model

func (*Model) ModelState

func (m *Model) ModelState() ModelState

ModelState returns the synchronization state of the Model object.

func (*Model) ModelSwapIndex

func (m *Model) ModelSwapIndex(index int) int

ModelSwapIndex returns the current index of the model object inside its containing array. This index is replace with the new index passed as parameter to this function.

func (*Model) ModelSynced

func (m *Model) ModelSynced()

ModelSynced marks the object as being successfully synched. This does not affect parent or child models.

func (*Model) ModelTestSync

func (m *Model) ModelTestSync(parent ModelIface, field *Field) ModelState

ModelTestSync returns the resulting synchronization state of the Model object. If a model object is moved to another parent of another field of the same parent, then the model object will be resynchronized.

type ModelIface

type ModelIface interface {
	ModelDirty()
	ModelChildDirty()
	ModelSynced()
	ModelState() ModelState
	ModelTestSync(parent ModelIface, field *Field) ModelState
	ModelSwapIndex(index int) int
	ModelID() int
}

ModelIface is implemented by Model.

type ModelState

type ModelState int

ModelState describes the synchronization state of a Model object

const (
	// ModelNew means that the Model object has not yet been synched
	ModelNew ModelState = 0
	// ModelDirty means that fields of the Model object have been modified
	// and need synchronization.
	// In addition, some child Models may be dirty as well.
	ModelDirty ModelState = 1
	// ModelChildDirty means that a child (or indirect child) Model is dirty.
	ModelChildDirty ModelState = 2
	// ModelSynced means that the Model and all of its children is synched.
	ModelSynced ModelState = 3
)

type Window

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

Window opens a new browser window and handles the http communication between the Go process and the browser window.

func NewWindow

func NewWindow(initialPath string, remote interface{}, model ModelIface) *Window

NewWindow creates a new HTTP server. Call Start() to run the server on a system-chosen port via the loopback-device and to launch the UI in the browser. The browser will open the `initialPath`, e.g. "/". The functions of the `remote` interface can be called from JavaScript. The `model` is synced to the browser, i.e. all changes made in GO are synced to the browser.

func (*Window) Call

func (s *Window) Call(fname string, args ...interface{}) error

Call invokes a function in the browser. Call is async, i.e. it does not wait for the browser to complete the function call and the result is not transmitted back to the server.

func (*Window) Handle

func (s *Window) Handle(pattern string, handler http.Handler)

func (*Window) SendEvent

func (s *Window) SendEvent(name string, event interface{}) error

SendEvent sends an event to the browser

func (*Window) ServeHTTP

func (s *Window) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles incoming HTTP requests, checks authentication via the auth cookie and checks for CSRF attacks via Referer and Origin header fields. Do not call this function from the application code.

func (*Window) Start

func (s *Window) Start() error

Start starts the web server and returns after the UI has either been opened or if the UI could not be started.

func (*Window) SyncModel

func (s *Window) SyncModel() error

SyncModel synchronizes the client-side model with all changes applied to the server-side model.

func (*Window) Wait

func (s *Window) Wait()

Wait blocks until the user closed the browser window.