ToolGUI

This Go package provides a framework for rapidly building interactive data dashboards and web applications. It aims to offer a similar development experience to Streamlit for Python users.

⚠️ Under Development:

The API for this package is still under development, and may be subject to changes in the future.

Demo page: https://toolgui-demo.fly.dev/

screen-shot

Server-Client

Step by step Hello World

Create main.go:

package main

import (
	"github.com/VoileLab/toolgui/toolgui/tgcomp"
	"github.com/VoileLab/toolgui/toolgui/tgexec"
	"github.com/VoileLab/toolgui/toolgui/tgframe"
)

func main() {
	app := tgframe.NewApp()
	app.AddPage("index", "Index", func(p *tgframe.Params) error {
		tgcomp.Text(p.Main, "Hello world")
		return nil
	})

	tgexec.NewWebExecutor(app).StartService(":3001")
}

Create go.mod and download toolgui:

go mod init toolgui-helloworld
go mod tidy

Run helloworld

go run main.go

Explain

Create a ToolGUI App: The App intance include the info that app needs.

app := tgframe.NewApp()

Register a page in App: Tell App instance, we will have a page in the App.
- index is the name.
- Index is the title.

app.AddPage("index", "Index", ...)

The Page Func: Draw a text component in the Main container.

func(p *tgframe.Params) error {
	tgcomp.Text(p.Main, "Hello world")
	return nil
}

WebExecuter: The App only includes the logic of app, but not includes GUI. The we executer provide web server GUI interface for App.

tgexec.NewWebExecutor(app).StartService(":3001")

How it works?

Basic

ui-state-pagefunc

The key concept is that in the Page Function, the UI component interact immediately with the running logic.

For example:

if tgcomp.Button(p.State, p.Main, "Click me") {
    tgcomp.Text(p.Main, "Hi")
}

In the first call (For example: When the web page is entering.), The Click me button will render, but the Hi will not render. Since the button is not clicked in the first round.

When the user clicks the button, the Page Function will be called again. In this round, tgcomp.Button will return true and Hi will render.

How?

Since we delcare a button which its id is Click me, and when the button clicked, we store true with key Click me into p.State.

When entering tccinput.Button, it will check if there is any data store in p.State with key Click me.

Server-Client Architecture

server arch

Server-Client need to handle a more complex part: multiple state for multiple users. Hence we need a state_id for each state.

The server part is responsible for the state pool.

App

The App includes the info of

Navbar: The navbar is the topmost part of the app.
Pages: The App hold a ordered map from page name to page's data.

layout

Here is the navbar of toolgui-demo.

navbar

The left part will be buttons which nav to the pages in App. The right part will be two button:

Rerun: Rerun the Page Func without changing any state.
Dark/Light Mode Switch: Switch the theme of the app.

The button of current page will be highlighted with a specific style.

Page

Parameters

We can config the page's:

Name: Or ID. The name of the page should be unique. In the web GUI provider, the name of a page will be used as the path of the page.
Title: In the web GUI provider, The title of a page will be used as the title of the page and text of button on the navbar.
Emoji: Optional. The emoji will be used as a icon on navbar and browser favicon.

The config type in package is:

type PageConfig struct {
	Name  string `json:"name"`
	Title string `json:"title"`
	Emoji string `json:"emoji"`
}

Page Function

The function signature of Page Function is defined as:

type RunFunc func(p *Params) error

Where Params contains these parameters to operate the page:

type Params struct {
	State   *State
	Main    *Container
	Sidebar *Container
}

Main and Sidebar is the root container component of the main and sidebar part shown in the layout image.

We can show a text in the Main container by:

tgcomp.Text(p.Main, "Hello")

The State in Params provided for

The component that need to pass state. For example: the checked state of checkbox.
The state that user need to store. For example: The todo items in the Todo App.

Example for adding a page

No emoji icon

app.AddPage("index", "Index", Main)

With a emoji icon

app.AddPageByConfig(&tgframe.PageConfig{
	Name:  "page2",
	Title: "Page2",
	Emoji: "🔄",
}, Page2)

State Storage

Faster access: Frequently used data can be retrieved from the cache much faster than recalculating it or fetching it from an external source every time. This improves the application's overall performance.
Reduced resource usage: By avoiding redundant calculations and external data fetching, the app can conserve resources like CPU and network bandwidth.

App Cache

An app-level cache stores data for the entire duration of the application's execution, from launch to termination.

This cache is not provided by ToolGUI and needs to be implemented by the developer.

For example:

type App1 struct {
	sync.Map data
}

func (app *App) QueryData(key string) {
	if v, ok := data.Load(key); ok{
		return v
	}

	// ...
	v, _ := data.LoadOrStore(key, calVal)
	return v
}

func (app *App) Page1(...) {
	tgcomp.text(app.QueryData(...))
}

Additional Considerations:

Cache Invalidation: As the application runs, the underlying data sources might change. It's crucial to have a strategy to invalidate cached data when necessary to ensure consistency. This could involve periodically refreshing the cache or implementing mechanisms to detect changes in the source data.
Memory Usage: App-level caches can consume memory. It's essential to choose appropriate data structures and cache eviction policies to balance performance gains with memory constraints.

State Cache

State-level cache stores data specific to the current view or "page" displayed to the user. This data lost when the user navigates away from the page or refreshes it.

Example of variable

Here we provide a state-level TODO App example. It stores list of todos in the state:

type TODOList struct {
	items []string
}

func (t *TODOList) add(item string) {
	t.items = append(t.items, item)
}

func Main(p *tgframe.Params) error {
	tgcomp.Title(p.Main, "Example for Todo App")

	todoList := p.State.Default("todoList", &TODOList{}).(*TODOList)

	inp := tgcomp.Textbox(p.State, p.Main, "Add todo")
	if tgcomp.Button(p.State, p.Main, "Add") {
		todoList.add(inp)
	}

	for i, todo := range todoList.items {
		tgcomp.TextWithID(p.Main,
			fmt.Sprintf("%d: %s", i, todo),
			fmt.Sprintf("todo_%d", i))
	}

	return nil
}

Example of function

Here we provide a state-level cache for a function.

// getFiles unarchive cbz file and return list of file names,
// since unarchive is time-consuming, we use state-level cache to store the result
func getFiles(p *tgframe.Params, f *tcinput.FileObject) ([]string, error) {
	key := fmt.Sprintf("%s_%s_%x", f.Name, f.Type, md5.Sum(f.Bytes))

	v := p.State.GetFuncCache(key)
	if v != nil {
		slog.Debug("cache found")
		return v.([]string), nil
	}

	buf := bytes.NewReader(f.Bytes)

	cbzFp, err := zip.NewReader(buf, buf.Size())
	if err != nil {
		// don't store nil to cache
		return nil, err
	}

	ret := []string{}
	for _, f := range cbzFp.File {
		ret = append(ret, f.Name)
	}

	// ok, we can store to cache
	p.State.SetFuncCache(key, ret)
	return ret, nil
}

func FuncCachePage(p *tgframe.Params) error {
	cbzfile := tgcomp.Fileupload(p.State, p.Sidebar, "CBZ File", "application/x-cbz")

	if cbzfile == nil {
		return nil
	}

	files, err := getFiles(p, cbzfile)
	if err != nil {
		return err
	}

	for i, f := range files {
		tgcomp.Text(p.Main, fmt.Sprintf("%d: %s", i, f))
	}

	return nil
}

Components

Component Tree / Forest

When every component created, we need to assign where it should generate. The root will be Main Container or Sidebar Container. Hence the relation between components is trees.

For example, if a page function implements as:

tgcomp.Text(p.Main, "Text")
tgcomp.Button(p.State, p.Main, "Button")
box := tgcomp.Box("box")
tgcomp.Text(box, "Text1")
tgcomp.Text(box, "Text2")

Then the Component Tree will be:

component tree example

Content Components

The content components show basic content. It doesn't return any value to user.

import "github.com/VoileLab/toolgui/toolgui/tgcomp"

The demo page can be found here: https://toolgui-demo.fly.dev/content

Title

Title component display a title.

API

func Title(c *tgframe.Container, text string)
func TitleWithID(c *tgframe.Container, text string, id string)

c is Parent container.
text is the title text.
id is a user specific element id.