liveview

README

Liveview

A Go package for building server-rendered HTML components with client-side interactivity.

These views use my escaper package (github.com/andybalholm/escaper) to render themselves to HTML.

Usage

For a complete example program, see the example directory.

First you need to create a Controller, and configure your HTTP router to route request to it:

var lvc = new(liveview.Controller)
http.Handle("/live-view/", lvc)

Each view needs to be implemented by a type that implements the View interface:

// A View is a component that can render itself to HTML, and respond to Events.
type View interface {
	Render(e *escaper.Escaper)
	HandleEvent(e Event)
}

When you are rendering the initial page, insert a View with the Controller’s Render method. You can have multiple views on one page, if you want. You should also include script tags to load the JavaScript to make the live views work.

lvc.Render(e, new(ClickCounter))
lvc.Render(e, new(CurrentTime))
e.Print(liveview.JSTag)

When a view needs to be refreshed, tell the Controller to update it. It will re-render the view, and send the updated HTML to the client over a websocket.

lvc.Update(v)

To define an event that will be passed to your view’s HandleEvent method, give an HTML element an attribute starting with live- followed by the event name. (The currently supported events are click, change, and input.)

<button live-click="decrement">-</button>

When the user clicks on this button, the View will received a "decrement" Event.

Documentation

Index

• Constants
• type Controller
  • func (c *Controller) QuerySelector(v View, selector string) *ElementRef
  • func (c *Controller) Register(views ...View)
  • func (c *Controller) Render(w io.Writer, v View)
  • func (c *Controller) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (c *Controller) Update(v View) error
• type ElementRef
  • func (e *ElementRef) Do(script ...interface{}) error
  • func (e *ElementRef) SetInnerHTML(content ...interface{}) error
  • func (e *ElementRef) SetTextContent(s string) error
• type Event
• type View

Constants

const JSTag template.HTML = `` /* 149-byte string literal not displayed */

JSTag is the script tags that should be included in pages that use live views.

Types

type Controller

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

A Controller manages a collection of live views and their associated websockets.

func (*Controller) QuerySelector

func (c *Controller) QuerySelector(v View, selector string) *ElementRef

QuerySelector returns a reference to the first element in the view that matches selector. It does not check to make sure that the element actually exists in the client browser.

func (*Controller) Register

func (c *Controller) Register(views ...View)

Register registers Views with c, and prepares to receive websocket connections for them.

func (*Controller) Render

func (c *Controller) Render(w io.Writer, v View)

Render renders v to e, wrapped in a div that makes it a live view. The View is automatically Registered if it was not registered already.

func (*Controller) ServeHTTP

func (c *Controller) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface, to accept incoming websocket connections and serve the necessary JavaScript file. The Controller should be set up to handle the "/live-view/" path.

func (*Controller) Update

func (c *Controller) Update(v View) error

Update re-renders v and sends the updated HTML to the client.

type ElementRef

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

An ElementRef points to an element in a live view, and can be used to perform actions on it remotely.

func (*ElementRef) Do

func (e *ElementRef) Do(script ...interface{}) error

Do executes a snippet of JavaScript on the client. It runs with "this" set to the element referenced by e.

func (*ElementRef) SetInnerHTML

func (e *ElementRef) SetInnerHTML(content ...interface{}) error

SetInnerHTML sets e's innerHTML. The content is processed with an Escaper from github.com/andybalholm/escaper.

func (*ElementRef) SetTextContent

func (e *ElementRef) SetTextContent(s string) error

SetTextContent sets e's textContent to s.

type Event

type Event struct {
	// Event is the name that was assigned to the event in the HTML markup
	// (e.g. in the live-click attribute).
	Event string `json:"event"`

	// If the target of the event is a form control, Value is its current value.
	Value string `json:"value"`

	// If the event is a form submission, FormData is the values from the form.
	FormData url.Values `json:"form_data"`

	ChannelID string `json:"channel"`
}

An Event represents an action by the user, such as clicking a button. There are also special Events named "connect" and "disconnect" that take place when the View's websocked is connected and disconnected.

type View

type View interface {
	Render(w io.Writer)
	HandleEvent(e Event)
}

A View is a component that can render itself to HTML, and respond to Events.