Skip to content

Documentation

Jump to bottom
András Belicza edited this page Aug 2, 2018 · 11 revisions

Table of Contents

Foreword

The sources of Gowut are well documented. Be sure to check them out and use it while writing code using Gowut.

The godoc of Gowut is also available online: http://godoc.org/github.com/icza/gowut/gwu

For an overview, read the Gowut Wiki home.

Introduction

Gowut (Go Web UI Toolkit) is a full-featured, easy to use, platform independent Web UI Toolkit written in pure Go, no platform dependent native code is linked or called.

The usage of the Gowut is similar to Google's GWT and the Java Swing toolkit. If you are familiar with those, you will get started very easily. The main difference compared to GWT is that this solution does not compile into JavaScript but remains and runs as Go code (on the server side). Remaining on the server side means you don't have to hassle with asynchronous event handlers like in GWT, you can write real synchronous event handlers (like in Java Swing).

You can use this toolkit and build user interfaces with writing Go code only: you can assemble the client interface in Go, and write event handlers in Go. You may optionally spice it and make it more customized with some HTML and CSS (also added from Go code), but that is not required.

The UI can be simply assembled hierarchically from containers and components. Components can generate events which are dispatched to event handlers - also written in pure Go. If there is no component for an HTML tag you wish to use, you can use the HTML component to wrap your custom HTML code. Components also allow you to specify custom HTML attributes that will be added for their (wrapper) HTML tags.

Creating user interfaces using Gowut does not require you to think like that the clients will view it and interact with it through a browser. The "browser" layer is hidden by Gowut. While styling the components is done through CSS (either by calling the style builder's methods or passing direct CSS codes), think of it like a way similar to formatting HTML tags with CSS.

The state of the components are stored on server side, in the memory. This means that if a browser is closed and reopened, or you navigate away and back, the same state will be rendered again. AJAX technology is used to automatically synchronize component's state from browser to server, and to dispatch events.

AJAX technology is used also to refresh some parts (components) that change (during event handling) without having to reload the whole page to see the changes.

To quickly test it and see it in action, run the "Showcase of Features" application by typing:

go run $GOPATH/src/github.com/icza/gowut/_examples/showcase/showcase.go

Check out the live demo https://gowut-demo.herokuapp.com/show

Features of Gowut

  • A component library to assemble your user interfaces with
  • A GUI server which serves browser clients
  • Session management
  • Automatic event handling and dispatching
  • (CSS) Style builder to easily manipulate the style of components

Server, Events and Sessions

Gowut contains a GUI server which is responsible to serve GUI clients which are standard browsers. The user interface can be viewed from any browsers (including smart phones) which makes this a cross platform solution. Starting the GUI server with a non-local address gives you the possibility to view the GUI from a remote computer. The server can be configured to run in normal mode (HTTP) or in secure mode (HTTPS).

The GUI server also has Session management. By default windows added to the server are public windows, and shared between all users (clients). This means if a user changes the content (e.g. enters a text into a text box), that text will be visible to all other users. This is suitable for most desktop applications.

Sessions can be created during event handling (by calling the Event.NewSession() method), and windows added to the session will only be visible to the client associated with the session. If other users request the same window, a new instance of the window is to be created and added to their sessions.

Event handling is possible via event handlers. An event handler is an implementation of the EventHandler interface. Event handlers have to be attached to the components which will be the source of the event. Event handlers are registered to event types or kinds (EventType) such as click event (ETypeClick), value change event (ETypeChange), key up event (ETypeKeyUp) etc.

The HandleEvent() method of an event handler gets an Event value which has multiple purposes and functions:

  1. The event contains the parameters of the event (such as the event type, the event source component, mouse position in case of a mouse event etc.).

  2. The Event is an accessor to the Session associated with the client the event is originating from. Through the event an event handler may access the current Session, create a new Session or may remove it (invalidate it).

  3. The event is also used to define actions to be executed (automatically by Gowut) after the event handling (post-event actions). For example if the event handler changes a component, the handler has to mark it dirty causing it to be re-rendered in the client browser, or an event handler can change the focused component, or reload another window.

Creating a session from an event handler during event dispatching requires a public window and an event source component (e.g. a Button). There is another handy way to create sessions. Sessions can also be created automatically by requesting pre-registered paths, paths of not-yet existing windows. When such a window is requested and no private session associated with the client exists, a new session will be created. A registered SessionHandler can be used then to create the window prior to it being served.

Here's an example how to auto-create session for Login window:

// A SessionHandler implementation:
type sessHandler struct {}
func (h sessHandler) Created(s gwu.Session) {
    win := gwu.NewWindow("login", "Login Window")
    // ...add content to the login window...
    h.AddWindow(win)
}
func (h sessHandler) Removed(s gwu.Session) {}

// And to auto-create sessions for the login window:
server := gwu.NewServer("guitest","")
server.AddSessCreatorName("login", "Login Window")
server.AddSHandler(sessHandler{})

Despite the use of sessions, if you access the application remotely (e.g. not from localhost), security is only guaranteed if you configure the server to run in secure (HTTPS) mode.

Under the Hood

User interfaces are generated HTML documents which communicate with the server with AJAX calls. The GUI server is based on the web server integrated in Go.

When a Window is requested by its URL, the Window will render a complete HTML document. The Window will recursively include its child components. Components render themselves into HTML codes. When a component generates an event, the page in the browser will make an AJAX call sending the event to the server. The event will be passed to all the appropriate event handlers. Event handlers can mark components dirty, specifying that they may have changed and they must be re-rendered. When all the event handlers are done, the ids of the dirty components are sent back, and the browser will request only to render the dirty components, with AJAX calls, and the results will replace the old component nodes in the HTML DOM.

Since the clients are HTTP browsers, the GWU sessions are implemented and function as HTTP sessions. Cookies are used to maintain the browser sessions.

Styling

Styling the components is done through CSS. You can do this from Go code by calling the style builder's methods, or you can create external CSS files.

The Comp interface contains a Style() method which returns the style builder of the component. The builder can be used to set/manipulate the style class names of the component (e.g. SetClass(), AddClass(), RemoveClass() methods).

The builder also has get and set methods for the common CSS attributes, and the gwu package contains many CSS constants for CSS attribute values. Many styling can be achieved using the builder's built-in methods and constants resulting in the Go code containing no direct CSS at all. You can use the general Get() and Set() methods of the style builder to manipulate any style attributes which it does not have predefined methods for.

Each Gowut component has its own CSS class derived from its name using the "gwu-" prefix, for example the Button component has the default CSS class "gwu-Button". Many components use multiple CSS classes for their internal structure. These classes are listed in the documentation of the components. Gowut has multiple built-in CSS themes. A CSS theme is basically the collection of the style definitions of the style classes used by the components. You can set the default theme with the Server.SetTheme() method. This will be used for all windows. You can set themes individually for windows too, using the Window.SetTheme() method.

You can create your own external CSS files where you can extend/override the definitions of the built-in style classes. For example you can define the "gwu-Button" style class to have red background, and the result will be that all Buttons will have red background without having to change their style individually.

Component Palette

Containers to group and lay out components:

  • Expander - shows and hides a content comp when clicking on the header comp
  • (Link) - allows only one optional child
  • Panel - it has configurable layout
  • Table - it is dynamic and flexible
  • TabPanel - for tabbed displaying components (only 1 is visible at a time)
  • Window - top of component hierarchy, it is an extension of the Panel

Input components to get data from users:

Other components:

Full App Example

Check out the Full App Example.

Limitations

  1. Attaching onmouseover and onmouseout event handlers to a component and changing (re-rendering) the same component causes some trouble (the browsers generate multiple mouseover and mouseout events because the same HTML code is replaced under the mouse cursor).

  2. Attaching onmousedown and onmouseup event handlers to a check box and re-rendering it prevents ETypeChange handlers being called when clicking on it.

Closing

From the MVC point of view looking at a Go application using Gowut, the Go components are the Model, the generated (and manipulated) HTML document in the browser is the View and the Controller is integrated in both. Gowut is ideal to create (cross platform) user interfaces for desktop applications written in Go. It is also easy and handy to write the admin and also client interfaces of your Go web application using Gowut.

Happy UI coding in Go :-)

Clone this wiki locally