Introduction

This article focuses on the RUI (Remote User Interface) library, a tool designed for creating single-page applications using Go language. The need for such a library arose due to the lack of UI support in Go language, which was seen as a significant drawback by many developers who came from languages like C or C++. With Go language finding its niche in server application and service development, it still will be nice to have a support for graphical user interface. Therefore, we created RUI to fill this gap and make it easier for developers to create beautiful and functional user interfaces without having to deal with complex JavaScript and CSS code. We hope that library will be of great help to people, so let's dive in and explore what RUI has to offer!

Main concepts

Applications built with the RUI library consist of two primary components: * Server side(business logic) * Thin browser client(displaying and rendering)

On the server-side, we are responsible for creating UI controls and adding resources such as images, videos, localization files, and implementing business logic, processing client sessions, and reacting to events. The thin browser client is provided by the library and is uploaded every time a user requests a page. It establishes a client session using WebSocket technology to synchronize app state. Additionally, RUI can also work with plain HTTP connections but with limited functionality compared to WebSockets.

Features

RUI provides several features that make it an excellent choice for creating user interfaces in Go language. Some of these features include:

• Graphical User Interface controls, such as Button, GridLayout, ListView and others, which can be customized using their properties and themes.
• Events processing, where every change made by the client (such as pressing a button or hovering over a specific area) can be processed on the server-side to update app state.
• Themes support with most controls having default style constants that can be overridden. Additionally, there is an automatic way to apply themes based on client settings such as window orientation and size, light/dark mode, and more.
• Localization, which allows for multiple languages to be supported within the app, automatically applied based on the client's (browser) language settings.
• Drawings, with a Canvas control available for creating custom drawings or using SVG code with an SvgImageView.
• Animations, where almost any property of controls can participate in animations to engage users.
• Resources, which enable the inclusion of UI controls description, media files (such as images, video, audio), and raw data within a single binary file. There is also an option to provide custom folders for hosting separate files and referencing them dynamically by the library.

Setting up environment

To create RUI applications, you will need the Go language compiler and associated tools, which can be installed using the official instructions. Once you have these tools set up, you can begin exploring the features of RUI and creating your own UI applications with ease!

Project layout

Minimal project layout may look like on the image below and usually varying depending on the project needs.

In our example project, we have a "resources" folder that contains only one main view description file under "views" subfolder. However, in more complex applications, this folder may contain additional resources such as text translations, themes, and other media files. The app's entry point and the bootstrap code for RUI are located in the "main.go" file. Additionally, to embed any resource files into the application, a convenient "resources.go" file has been added.

Basic example

Based on a simple project layout we've seen earlier lets figure out how to prepare a resources which will be embedded into our app.

Our mainView.rui file contains a description of the root view for the app, lets use TextView UI control to display a greeting message:

TextView {
    // ID of the control by which we can reference it through source code 
    id = textView,
    text = "Hello world!",
    padding = 50px,
}

File format to describe UI elements is very similar to JSON, but still has some differences. It can even contain comments! To embed this resource we create a resources.go file for convenience which will store all our resources in convenient variable for future reference by the RUI library:

package main

import "embed"

//go:embed resources
var resources embed.FS

Now when we are done with preparations lets see how our main entry point looks like and how to setup the RUI library in our main.go:

package main

// Import RUI library
import (
    "github.com/anoshenko/rui"
)

// Address to listen on
const address = "localhost:8080"

// Implementation of rui.SessionContent interface
type appSession struct {
    rootView rui.View
}

// Implementation of mandatory rui.SessionContent.CreateRootView() function
func (app *appSession) CreateRootView(session rui.Session) rui.View {

    // Create root view of the app from mainView.rui file
    app.rootView = rui.CreateViewFromResources(session, "mainView")

    return app.rootView
}

// Called every time when a new client has been connected
func createSession(session rui.Session) rui.SessionContent {
    return new(appSession)
}

func main() {
    // Include resources with which RUI library may work with
    rui.AddEmbedResources(&resources)

    // Initialize RUI library and wait for incoming connections
    rui.StartApp(address, createSession, rui.AppParams{
        Title: "RUI example",
    })
}

First of all we've to import RUI library module and define an address on which RUI library will listen for incoming connections.

In main() function we inform RUI library about our prepared embedded resources which we can refer during creation of our UI elements. Then invoke rui.StartApp() function to initialize the library and wait for incoming connections. RUI library require a developer to provide a function which will be called every time when a new client will be connected. This function must return an implementation of rui.SessionContent interface which will be used by the library to create a UI for the client. This is done by invoking our implementation of CreateRootView() method. In this method we've to create and return a view either from resources(rui.CreateViewFromResources()) or using other RUI APIs directly.

When we've done with our code we can test it by invoking

% go run .

in our projects directory.

When compile process has been finished and our application started successfully we can navigate to it using our browser by opening http://localhost:8080 page. This is a possible output you may have based on your browser settings:

Localization

To support localization within our RUI-based application, we can create separate resource files for each supported language, containing the appropriate translated text values. Here's an example of what this might look like:

Content of en.rui

strings:en {
    "tr-greeting" = "Hello world!",
}

Content of de.rui

strings:de {
    "tr-greeting" = "Hallo Welt!",
}

where "tr-greeting" is the text constant which we can use as a text in our UI controls. RUI library automatically check for such constants and substitute them with a translation.

We'll create a new folder in "resources" called "strings" and put these files inside.

Now lets modify our main view description to use "tr-greeting" constant instead of a text:

TextView {
    id = textView,
    text = "tr-greeting",
    padding = 50px,
}

When done we can re-launch our app, change preferred browser language to lets say German and re-open http://localhost:8080 page, we should have something similar to this:

Events processing

Static content in an application can be quite boring, so why not react to user input? The RUI library provides a mechanism for notifying the app of events that occur during user interaction with UI controls.

Let's modify our example slightly by adding a button that will display or hide our greeting message.

We need to add a new text constants for our button, so internationalization will still work, here is our updated en.rui and de.rui resource files:

strings:en {
    "tr-greeting" = "Hello world!",
    "tr-greet" = "Greet!",
    "tr-ok" = "Ok",
}

strings:de {
    "tr-greeting" = "Hallo Welt!",
    "tr-greet" = "Begrüßen!",
    "tr-ok" = "OK",
}

We've added "tr-greet" and "tr-ok" text constants translations. Now let's update our mainView.rui file by adding a GridLayout container that can group our child controls in a visually appealing manner:

GridLayout {
    // Let control to occupy all available area
    width = 100%,
    height = 100%,
    // Align all content in the cell's center
    cell-horizontal-align = center,
    cell-vertical-align = center,
    // Describe all child controls
    content = [
        TextView {
            id = textView,
            // Cell in which this control will reside
            row = 0,
            column = 0,
            text = "tr-greeting",
            // Hide control by default
            visibility = invisible,
        },
        Button {
            id = button,
            row = 1,
            column = 0,
            // Specify what will be in the button
            content = "tr-greet",
        },
    ]
}

Yeah, it looks more complex at a glance but what we have done here was just wrapping our TextView and Button in a GridLayout container.

By default, the text view is hidden and we will un-hide it later in our code by reacting to the button click event. To process click events from the button, we need to set up an event handler in our code. Let's modify our main.go file to do this:

func (app *appSession) CreateRootView(session rui.Session) rui.View {
    app.rootView = rui.CreateViewFromResources(session, "mainView")

    // Get Button view by ID
    button := rui.ButtonByID(app.rootView, "button")

    // Set listener for Button click event
    button.Set(rui.ClickEvent, app.buttonClickedEvent)

    return app.rootView
}

When we create our UI layout from a resource file, we can obtain a reference to our button using its ID and set up a listener function that will be called when the user clicks the button. Now let's actually add this listener to our code:

// Fired when our button has been clicked
func (app *appSession) buttonClickedEvent(view rui.View) {

    // Get TextView view by its ID
    textView := rui.TextViewByID(app.rootView, "textView")

    // Toggle visibility of greeting message and button text
    if rui.GetVisibility(textView, "") == rui.Invisible {
        textView.Set(rui.Visibility, rui.Visible)
        view.Set(rui.Content, "tr-ok")
    } else {
        textView.Set(rui.Visibility, rui.Invisible)
        view.Set(rui.Content, "tr-greet")
    }
}

The listener function gets called with a view parameter, which in our case is a Button. We can manipulate the properties of this button as desired. Here, we obtain a reference to the TextView using its ID and check its visibility property. Remember that we initially set it to invisible in our mainView.rui file. If the text view is invisible, we update its visibility property to make it visible and change the content on the button. Otherwise, we hide the text view and revert the button's text.

Re-compiling the app and running it should produce a final result that looks something like this, assuming you are still using the German language setting on your browser:

After pressing the button:

Themes customization

To make apps more visually appealing and engaging for the end user, we often customize the look and feel of the controls. In RUI library, this can be done by modifying the theme parameters described in the "themes" folder under the "resources" directory. We will create a new file called "default.rui" in our "themes" folder to change a few parameters, here is its content:

theme {
    colors = _{
        ruiTextColor = #FF888888,
        ruiButtonTextColor = #FF888888,
    },
    colors:dark = _{
        ruiTextColor = #FFDEDEDE,
        ruiButtonTextColor = #FFFFFFFF,
    },
    constants = _{
        ruiButtonRadius = 14px,
        ruiButtonColor = #FFE0E0E0,
    },
}

We overwrote some colors and constants for RUI controls. Specifically we set text color to a different value for all controls which display text, for example TextView and text which appear in the Button, also we've modified our button's corners radius and button color itself.

RUI library will automatically load that file and replace all default content with values we've provided. By default one theme file provides settings for light and dark mode of the client's system.

And finally here is the result:

Using light system mode

Using dark system mode

There are more options for theme customization like overriding styles of controls, changing their shapes and providing a new custom styles.

Conclusion

RUI library provides a powerful yet easy way to create single page applications with rich list of UI controls. It hides complexity of JavaScript and CSS technologies which some developers may find challenging to work with. With its support for events processing, localization, custom themes and more, it's an ideal choice for Go lang developers who want to quickly build their own apps.

Links

• RUI library official page.
• Source code on Github.

© Alxanosoft inc.