lorca

README

Lorca

A small library to build modern HTML5 desktop apps in Go. It uses Chrome browser as a UI layer. Unlike Electron it doesn't bundle Chrome into the app package, but rather reuses the one that is already installed. Lorca establishes a connection to the browser window and allows calling Go code from the UI and manipulating UI from Go in a seamless manner.

Features

• Pure Go library (no cgo) with a very simple API
• Small application size (normally 5-10MB)
• Best of both worlds - the whole power of HTML/CSS to make your UI look good, combined with Go performance and ease of development
• Expose Go functions/methods and call them from JavaScript
• Call arbitrary JavaScript code from Go
• Asynchronous flow between UI and main app in both languages (async/await and Goroutines)
• Supports loading web UI from the local web server or via data URL
• Supports embedding all assets into a single binary
• Supports testing your app with the UI in the headless mode
• Supports multiple app windows
• Supports packaging and branding (e.g. custom app icons). Packaging for all three OS can be done on a single machine using GOOS and GOARCH variables.

Also, limitations by design:

• Requires Chrome/Chromium >= 70 to be installed.
• No control over the Chrome window yet (e.g. you can't remove border, make it transparent, control position or size).
• No window menu (tray menus and native OS dialogs are still possible via 3rd-party libraries)

Example

ui, _ := lorca.New("", "", 480, 320)
defer ui.Close()

// Bind Go function to be available in JS. Go function may be long-running and
// blocking - in JS it's represented with a Promise.
ui.Bind("add", func(a, b int) int { return a + b })

// Call JS function from Go. Functions may be asynchronous, i.e. return promises
n := ui.Eval(`Math.random()`).Float()
fmt.Println(n)

// Call JS that calls Go and so on and so on...
m := ui.Eval(`add(2, 3)`).Int()
fmt.Println(m)

// Wait for the browser window to be closed
<-ui.Done()

Also, see examples for more details about binding functions, embedding assets and packaging binaries.

How it works

Under the hood Lorca uses Chrome DevTools Protocol to instrument on a Chrome instance. First Lorca tries to locate your installed Chrome, starts a remote debugging instance binding to an ephemeral port and reads from stderr for the actual WebSocket endpoint. Then Lorca opens a new client connection to the WebSocket server, and instruments Chrome by sending JSON messages of Chrome DevTools Protocol methods via WebSocket. JavaScript functions are evaluated in Chrome, while Go functions actually run in Go runtime and returned values are sent to Chrome.

What's in a name?

There is kind of a legend, that before his execution Garcia Lorca have seen a sunrise over the heads of the soldiers and he said "And yet, the sun rises...". Probably it was the beginning of a poem. (J. Brodsky)

Lorca is an anagram of Carlo, a project with a similar goal for Node.js.

License

Code is distributed under MIT license, feel free to use it in your proprietary projects as well.

Documentation

Index

• Constants
• func Embed(packageName, file string, dirs ...string) error
• func LocateChrome() string
• func PDF(url, script string, width, height int) ([]byte, error)
• func PNG(url, script string, x, y, width, height int, bg uint32, scale float32) ([]byte, error)
• func PromptDownload()
• type Bounds
• type Chrome
  • func NewChromeWithArgs(chromeBinary string, args ...string) (*Chrome, error)
  • func (c *Chrome) AddScriptToEvaluateOnNewDocument(script string) error
  • func (c *Chrome) Back() error
  • func (c *Chrome) Bind(name string, f bindingFunc) error
  • func (c *Chrome) Bounds() (Bounds, error)
  • func (c *Chrome) DisableContextMenu() error
  • func (c *Chrome) DisableDefaultShortcuts() error
  • func (c *Chrome) Eval(expr string) (json.RawMessage, error)
  • func (c *Chrome) Forward() error
  • func (c *Chrome) GetNavigationHistory() (*NavigationHistory, error)
  • func (c *Chrome) Kill() error
  • func (c *Chrome) Load(url string) error
  • func (c *Chrome) PDF(width, height int) ([]byte, error)
  • func (c *Chrome) PNG(x, y, width, height int, bg uint32, scale float32) ([]byte, error)
  • func (c *Chrome) Reload(disableCache bool) error
  • func (c *Chrome) Send(method string, params h) (json.RawMessage, error)
  • func (c *Chrome) SetBounds(b Bounds) error
• type NavigationHistory
• type NavigationHistoryEntry
• type UI
  • func New(chromeExe, url, userDataDir string, width, height int, customArgs ...string) (*UI, error)
  • func (u *UI) Bind(name string, f interface{}) error
  • func (u *UI) Close() error
  • func (u *UI) Done() <-chan struct{}
  • func (u *UI) Eval(js string) Value
• type Value
• type WindowState

Constants

const (
	// PageA4Width is a width of an A4 page in pixels at 96dpi
	PageA4Width = 816
	// PageA4Height is a height of an A4 page in pixels at 96dpi
	PageA4Height = 1056
)

const DisableContextMenuScript = `
	document.addEventListener('contextmenu', event => event.preventDefault());
`

DisableContextMenuScript is a browser-side script that disables Chrome's right-click context menu

const DisableShortcutsScript = `` /* 1674-byte string literal not displayed */

DisableShortcutsScript disables default shortcuts

Functions

func Embed

func Embed(packageName, file string, dirs ...string) error

Embed is a helper function that embeds assets from the given directories into a Go source file. It is designed to be called from some generator script, see example project to find out how it can be used.

func LocateChrome

func LocateChrome() string

LocateChrome returns a path to the Chrome binary, or an empty string if Chrome installation is not found.

func PDF

func PDF(url, script string, width, height int) ([]byte, error)

PDF converts a given URL (may be a local file) to a PDF file. Script is evaluated before the page is printed to PDF, you may modify the contents of the page there of wait until the page is fully rendered. Width and height are page bounds in pixels. PDF by default uses 96dpi density. For A4 page you may use PageA4Width and PageA4Height constants.

func PNG

func PNG(url, script string, x, y, width, height int, bg uint32, scale float32) ([]byte, error)

PNG converts a given URL (may be a local file) to a PNG image. Script is evaluated before the "screenshot" is taken, so you can modify the contents of a URL there. Image bounds are provides in pixels. Background is in ARGB format, the default value of zero keeps the background transparent. Scale allows zooming the page in and out.

This function is most convenient to convert SVG to PNG of different sizes, for example when preparing Lorca app icons.

func PromptDownload

func PromptDownload()

PromptDownload asks user if he wants to download and install Chrome, and opens a download web page if the user agrees.

Types

type Bounds

type Bounds struct {
	Left        int         `json:"left"`
	Top         int         `json:"top"`
	Width       int         `json:"width"`
	Height      int         `json:"height"`
	WindowState WindowState `json:"windowState"`
}

Bounds defines settable window properties.

type Chrome

type Chrome struct {
	sync.Mutex
	Cmd *exec.Cmd
	// contains filtered or unexported fields
}

Chrome represents a chrome process

func NewChromeWithArgs

func NewChromeWithArgs(chromeBinary string, args ...string) (*Chrome, error)

NewChromeWithArgs starts chrome process with arguments

func (*Chrome) AddScriptToEvaluateOnNewDocument

func (c *Chrome) AddScriptToEvaluateOnNewDocument(script string) error

AddScriptToEvaluateOnNewDocument adds JavaScript code to be evaluated when new document is evaluted

func (*Chrome) Back

func (c *Chrome) Back() error

Back navigates to previous page in browser history

func (*Chrome) Bind

func (c *Chrome) Bind(name string, f bindingFunc) error

Bind creates a browser-side binding with name to a function

func (*Chrome) Bounds

func (c *Chrome) Bounds() (Bounds, error)

Bounds returns the size, position and a state of a browser window

func (*Chrome) DisableContextMenu

func (c *Chrome) DisableContextMenu() error

DisableContextMenu disables Chrome's default context menu on right mouse click

func (*Chrome) DisableDefaultShortcuts

func (c *Chrome) DisableDefaultShortcuts() error

DisableDefaultShortcuts disables default shortucts like Ctr-N to open a new tab

func (*Chrome) Eval

func (c *Chrome) Eval(expr string) (json.RawMessage, error)

Eval evaluates JavaScript expression in the browser and returns response

func (*Chrome) Forward

func (c *Chrome) Forward() error

Forward navigates to next page in browser history

func (*Chrome) GetNavigationHistory

func (c *Chrome) GetNavigationHistory() (*NavigationHistory, error)

GetNavigationHistory returns browser navigation history

func (*Chrome) Kill

func (c *Chrome) Kill() error

Kill kills the chrome process

func (*Chrome) Load

func (c *Chrome) Load(url string) error

Load navigates to a given URL

func (*Chrome) PDF

func (c *Chrome) PDF(width, height int) ([]byte, error)

PDF generates a PDF of a given size and returns the PDF content as []byte

func (*Chrome) PNG

func (c *Chrome) PNG(x, y, width, height int, bg uint32, scale float32) ([]byte, error)

PNG generates

func (*Chrome) Reload

func (c *Chrome) Reload(disableCache bool) error

Reload reloads current page https://pptr.dev/#?product=Puppeteer&show=api-pagereloadoptions

func (*Chrome) Send

func (c *Chrome) Send(method string, params h) (json.RawMessage, error)

Send sends a method with a parameters to the browser, waits for response and returns response as json

func (*Chrome) SetBounds

func (c *Chrome) SetBounds(b Bounds) error

SetBounds sets the size, position and state of a browser window

type NavigationHistory

type NavigationHistory struct {
	CurrentIndex int                       `json:"currentIndex"`
	Entries      []*NavigationHistoryEntry `json:"entries"`
}

NavigationHistory represents browser navigation history

type NavigationHistoryEntry

type NavigationHistoryEntry struct {
	ID             int64  `json:"id"`
	URL            string `json:"url"`
	UserTypedURL   string `json:"userTypedURL"`
	Title          string `json:"title"`
	TransitionType string `json:"transitionType"`
}

NavigationHistoryEntry represents a single entry in navigation history

type UI

type UI struct {
	*Chrome
	// contains filtered or unexported fields
}

func New

func New(chromeExe, url, userDataDir string, width, height int, customArgs ...string) (*UI, error)

New returns a new HTML5 UI for the given URL, user profile directory, window size and other options passed to the browser engine. If URL is an empty string - a blank page is displayed. If user profile directory is an empty string - a temporary directory is created and it will be removed on ui.Close(). You might want to use "--headless" custom CLI argument to test your UI code.

func (*UI) Bind

func (u *UI) Bind(name string, f interface{}) error

func (*UI) Close

func (u *UI) Close() error

func (*UI) Done

func (u *UI) Done() <-chan struct{}

func (*UI) Eval

func (u *UI) Eval(js string) Value

type Value

type Value interface {
	Err() error
	To(interface{}) error
	Float() float32
	Int() int
	String() string
	Bool() bool
	Object() map[string]Value
	Array() []Value
}

Value is a generic type of a JSON value (primitive, object, array) and optionally an error value.

type WindowState

type WindowState string

WindowState defines the state of the Chrome window, possible values are "normal", "maximized", "minimized" and "fullscreen".

const (
	// WindowStateNormal defines a normal state of the browser window
	WindowStateNormal WindowState = "normal"
	// WindowStateMaximized defines a maximized state of the browser window
	WindowStateMaximized WindowState = "maximized"
	// WindowStateMinimized defines a minimized state of the browser window
	WindowStateMinimized WindowState = "minimized"
	// WindowStateFullscreen defines a fullscreen state of the browser window
	WindowStateFullscreen WindowState = "fullscreen"
)