turbostream

Documentation

Overview

Package turbostream provides framing for fragments of HTML to be used with the Turbo Streams client-side library. Read more at https://turbo.hotwire.dev/handbook/streams

Index

• Constants
• func IsSupported(reqHeader http.Header) bool
• func Render(w http.ResponseWriter, actions ...*Action) error
• type Action
  • func NewRemove(id string) *Action
  • func (a *Action) MarshalText() ([]byte, error)
• type ActionType
  • func (t ActionType) IsValid() bool
• type Executer

Examples

• Render

Constants

const ContentType = "text/vnd.turbo-stream.html"

ContentType is the MIME type of a Turbo Stream response.

Functions

func IsSupported

func IsSupported(reqHeader http.Header) bool

IsSupported reports whether the request header indicate that a Turbo Stream response is supported.

func Render

func Render(w http.ResponseWriter, actions ...*Action) error

Render sends Turbo Stream actions in response to a form submission. See https://turbo.hotwire.dev/handbook/streams#streaming-from-http-responses for an overview.

Render does not write any data or set headers if it returns an error.

Example

package main

import (
	"html/template"
	"io"
	"net/http"
	"net/http/httptest"
	"os"

	"zombiezen.com/go/bass/turbostream"
)

func main() {
	// In this example, we write an HTTP response to a response recorder.
	// In a real program, this would be the first argument to an http.Handler.
	w := httptest.NewRecorder()

	// Use html/template to build HTML.
	tmpl := template.Must(template.New("message.html").Parse(
		`<div id="message_{{ .ID }}">` + "\n" +
			"This div will be appended to the element with the DOM ID <q>messages</q>.\n" +
			`</div>`))

	// Call turbostream.Render to send the page modifications.
	err := turbostream.Render(w, &turbostream.Action{
		Type:     turbostream.Append,
		TargetID: "messages",
		Template: tmpl.Lookup("message.html"),
		Data:     struct{ ID int64 }{ID: 1},
	})
	if err != nil {
		// Render does nothing if the actions fail to render.
		// In this example, we serve an HTTP 500.
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// For demonstration, print out the response body to stdout.
	response := w.Result()
	io.Copy(os.Stdout, response.Body)

}

Output:

<turbo-stream action="append" target="messages">
	<template><div id="message_1">
This div will be appended to the element with the DOM ID <q>messages</q>.
</div></template>
</turbo-stream>

Types

type Action

type Action struct {
	Type     ActionType
	TargetID string
	Template Executer
	Data     interface{}
}

Action is a single instruction on how to modify an HTML document.

func NewRemove

func NewRemove(id string) *Action

NewRemove returns a new action with type Remove.

func (*Action) MarshalText

func (a *Action) MarshalText() ([]byte, error)

MarshalText renders the template as HTML. If the Action is nil, then it returns (nil, nil).

type ActionType

type ActionType string

ActionType is the value of the turbo-stream element's action attribute.

const (
	// Append appends the content to the container designated by the target DOM ID.
	Append ActionType = "append"
	// Prepend prepends the content to the container designated by the target DOM ID.
	Prepend ActionType = "prepend"
	// Replace replaces designated by the target DOM ID with the action's content.
	Replace ActionType = "replace"
	// Update replaces the content in the container designated by the target
	// DOM ID with the action's content.
	Update ActionType = "update"
	// Remove removes the element designated by the target DOM ID. The action's
	// Template must be nil.
	Remove ActionType = "remove"
)

Action types defined in https://turbo.hotwire.dev/reference/streams

func (ActionType) IsValid

func (t ActionType) IsValid() bool

IsValid reports whether t is one of the defined action types.

type Executer

type Executer interface {
	Execute(wr io.Writer, data interface{}) error
}

Executer is the interface that wraps the Execute method of templates. Execute applies a parsed template to the specified data object, writing the output to wr.