-- Leo's gemini proxy
-- Connecting to capsule.adrianhesketh.com:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini; charset=utf-8
Hotwire [0] is an approach used to build Web applications without using a lot of front-end JavaScript. Most of the content is served as HTML via server-side rendered templates, which makes it an ideal partner for the templ [1] templating language. In fact, I designed templ with exactly this scenario in mind.
I tried out building a really simple app [2] so I could learn the mechanics.
The project has two web servers in it. One that listens at `http://localhost:8000` in the `cmd` directory and another one that listens at `http://localhost:8001` in the `remote-frame` directory. I'll cover `remote-frame` in another post.
The `main.go` file in the `cmd` directory starts up the main Web server. It configures the `/` route.
func main() {
// Wire up the routes.
http.Handle("/", IndexHandler{})
// Use localhost:8000 rather than :8000 so MacOS doesn't ask if you want to accept incoming connections.
fmt.Println("Listening on http://localhost:8000")
err := http.ListenAndServe("localhost:8000", nil)
if err != nil {
fmt.Println("Error:", err)
}
}
The `IndexHandler{}` serves up traffic when HTTP requests hit `http://localhost:8000/`. It handles `GET` and `POST` requests by inspecting the request parameter (`r`), then calls the `Get` or `Post` method on itself depending on the HTTP request method used.
type IndexHandler struct{}
func (h IndexHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:
h.Get(w, r)
return
case http.MethodPost:
h.Post(w, r)
return
}
http.Error(w, "unhandled verb", http.StatusBadRequest)
}
The `Get` method uses the `todo.DB` "database" code to list out the todos, constructs an instance of `IndexViewData` and passes it to the `Render` method that's also a part of the `IndexHandler`.
`IndexViewData` is a type that defines all of the "data" used by the `Index` "view".
func (h IndexHandler) Get(w http.ResponseWriter, r *http.Request) {
todos, err := todo.DB{}.List()
if err != nil {
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
d := templates.IndexViewData{
Todos: todos,
NewTodo: templates.NewTodoViewData{},
}
h.Render(d, w, r)
}
The `Render` method takes the `IndexViewData`, and passes it to `templ` templates to render HTML to the client:
func (h IndexHandler) Render(d templates.IndexViewData, w http.ResponseWriter, r *http.Request) {
// Create the templates.
body := templates.Index(d)
page := templates.Page("Todos", body)
// Render.
err := page.Render(r.Context(), w)
if err != nil {
log.Println("error", err)
}
}
Let's look at how those templates are constructed.
The `templ` templates are stored in the `templates` directory. Since `templ` files get converted into Go code, they can sit alongside other Go code and use Go types defined in the same package and in imported packages.
There's one main template for this application `todo.templ`, but alongside it is `todo.go` which contains structs that define the structure of data that the templates will render out to HTML.
package templates
import todo "github.com/a-h/go-hotwire-todo"
// The index page.
type IndexViewData struct {
Todos []*todo.Todo
NewTodo NewTodoViewData
}
type NewTodoViewData struct {
Text string `schema:"text"`
// This can be done with a required attribute in HTML, so there may be no need for this, it's just an example.
TextValidation string
}
func (d *NewTodoViewData) Validate() (isValid bool) {
isValid = true
if d.Text == "" {
d.TextValidation = "Text cannot be empty."
isValid = false
}
return
}
The `todo.templ` template renders the content of the app.
Like all `templ` files, `todo.templ` starts with the name of the package, and any imports that are required.
{% package templates %}
{% import todo "github.com/a-h/go-hotwire-todo" %}
The `Page` template defines the overall layout of a page. When `templ generate` is ran, this template gets compiled into a Go file called `todo_templ.go` containing a function called `Page`. The `Page` function takes a `title` parameter that's used as the title for the page, and a `content` parameter which forms the body of the page, and returns a `templ.Component` that can be used to render HTML to any `io.Stream`, e.g. a HTTP response or a string buffer.
One thing to note is that the `content` parameter is a `templ.Component`. This `content` parameter gets rendered inside the HTML `body` tag using the `{%! content %}` syntax.
You might also notice our first glimpse of Hotwire - a script tag that brings in the Turbo library. This app doesn't actually require JavaScript to work, but if JavaScript is enabled, it uses Turbo to avoid carrying out full screen refreshes.
{% templ Page(title string, content templ.Component) %}
<html>
<head>
<title>{%= title %}</title>
<script src="https://unpkg.com/@hotwired/turbo@7.0.0-beta.5/dist/turbo.es5-umd.js"></script>
</head>
<body>
{%! content %}
</body>
</html>
{% endtempl %}
If you refer back to how `GET /` is handled, you'll see that the result of `templates.Index` is passed to the `Page` template as the `body` - i.e. the `Index` template becomes the contents of the `<body>` element.
body := templates.Index(d)
page := templates.Page("Todos", body)
The `Index` template is used as the contents of the `<body>` element, and contains references to other templates, using the `Todos` template to display a list of todo items, and the `NewTodo` template to display a form that can be used to create new `Todo` items.
{% templ Index(d IndexViewData) %}
<h1>{%= "Todos" %}</h1>
{%! Todos(d.Todos) %}
<h1>{%= "Create" %}</h1>
{%! NewTodo(d.NewTodo) %}
{% endtempl %}
The Turbo JavaScript library imported in the `Page` template can rewrite sections of the HTML code without doing a full refresh of the page.
The Turbo library uses the `turbo-frame` elements to know which sections of the screen can be updated, and the `id` attribute of the `turbo-frame` to know which element to update when it receives an `turbo-stream` response from the server (more on that later).
{% templ Todos(todos []*todo.Todo) %}
<turbo-frame id="todos">
{% for _, t := range todos %}
{%! Todo(t) %}
{% endfor %}
</turbo-frame>
{% endtempl %}
{% templ Todo(t *todo.Todo) %}
<div>
<div>{%= t.Item %}</div>
</div>
{% endtempl %}
Finally, the `NewTodo` template renders a HTML form. The `form` is also within a `turbo-frame` which allows the `NewTodo` form to be updated without a full screen refresh using Turbo.
Note how the `name` attribute of the input is set to "text". We'll see how that gets matched up with the `Text` field on the `NewTodoViewData` type when we process the form submission.
Hopefully, you can spot that if the `d.TextValidation` field isn't empty, then a validation message will be shown.
{% templ NewTodo(d NewTodoViewData) %}
<turbo-frame id="new_todo">
<form action="/" method="post">
<div>
<input type="text" name="text" value={%= d.Text %} />
</div>
{% if d.TextValidation != "" %}
<div style="color: red">
{%= d.TextValidation %}
</div>
{% endif %}
<div>
<input type="submit" value="New"/>
</div>
</form>
</turbo-frame>
{% endtempl %}
Altogether, we've got a simple HTML page rendered, and we've got Turbo running on the page.
While it's nice to be able to render GET requests to the server, the `NewTodo` template is rendering a HTML form on the screen. Once we've entered some text and clicked on the "New" button, the app should react to that and create a new "Todo" item.
The Turbo JavaScript library looks for forms that are within a `turbo-frame` and intercepts and rewrites the form posts but we still need to wire up receiving the form data.
This is done in `cmd/main.go` in the `Post` method receiver.
First, the code parses the HTTP form post.
func (h IndexHandler) Post(w http.ResponseWriter, r *http.Request) {
// Parse the form.
err := r.ParseForm()
if err != nil {
http.Error(w, "failed to parse form post", http.StatusBadRequest)
return
}
Next, it constructs a `NewTodoViewData` by decoding the form post from the HTTP request and mapping the form post values into the appropriate fields on the struct (e.g. putting the "text" form value into the `Text` field).
It does this using the Gorilla schema library [3], which is instantiated in the same file.
// Populate the structs.
ntvd := new(templates.NewTodoViewData)
err = decoder.Decode(ntvd, r.PostForm)
if err != nil {
http.Error(w, "failed to decode form post", http.StatusBadRequest)
return
}
With the `NewTodoViewData` populated from the HTTP form post data, validation can take place. If there's no problem, the new todo is created, and the `NewTodoViewData` gets cleared.
// Validate and carry out actions.
isValid := ntvd.Validate()
var newTodo *todo.Todo
if isValid {
// Update the data.
newTodo = &todo.Todo{
ID: uuid.New().String(),
Item: ntvd.Text,
}
todo.DB{}.Upsert(newTodo.ID, newTodo.Item, newTodo.Complete)
// Clear the form.
ntvd = new(templates.NewTodoViewData)
}
One of the nice parts of this design is that it works even if JavaScript is disabled on the client.
Requests that come from the Turbo library include a HTTP `accept` header that can be used to distinguish between the two worlds, so the code just checks if the request came from the Turbo library and if it didn't, renders the whole screen again.
if !IsTurboRequest(r) {
// Get the view ready.
todos, err := todo.DB{}.List()
if err != nil {
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
d := templates.IndexViewData{
Todos: todos,
NewTodo: *ntvd,
}
h.Render(d, w, r)
return
}
If it _is_ a Turbo Frame request, the Handler can return a Turbo Stream [4] of updates instead.
Turbo uses the list of `turbo-stream` elements returned by the handler to update, append or remove sections of the screen. This allows us to skip carrying out a database query and just append the new todo item to the list on screen using the `append` action, and to re-render the form using the `update` action to take into account the validation messages, or to clear the form.
// If it's a Turbo request, we can just update the bits of the screen we need to.
var actions []Action
// Update the todo list.
if newTodo != nil {
actions = append(actions, StreamAction(ActionAppend, "todos", templates.Todo(newTodo)))
}
// Update the form.
actions = append(actions, StreamAction(ActionUpdate, "new_todo", templates.NewTodo(*ntvd)))
// Return the stream of updates.
TurboStream(actions...).ServeHTTP(w, r)
}
Since Turbo streams are a list of `turbo-stream` elements, we need a way to make them, so I created the `Action` template in `templates/turbo.templ`.
{% package templates %}
{% templ Action(action string, target string, template templ.Component) %}
<turbo-stream action={%= action %} target={%= target %}>
<template>
{%! template %}
</template>
</turbo-stream>
{% endtempl %}
I also made some utility functions to make it easy to return `turbo-stream` elements. I left them all in `main.go` as a demo, but as I get confident that I'm going to stick with design, I'm likely to create `templ-hotwire` package.
The utilities start with an enumeration of all the possible Turbo Frame actions that you can do.
type ActionType string const ( ActionAppend ActionType = "append" ActionPrepend = "prepend" ActionReplace = "replace" ActionUpdate = "update" ActionRemove = "remove" )
Then a definition of the data required by the `turbo-stream` element, which includes the action that will be taken ("append" / "prepend" etc.) on the `Target` (based on its HTML ID), and the `Template` content that will be used to do it.
type Action struct {
Type ActionType
Target string
Template templ.Component
}
func StreamAction(at ActionType, target string, template templ.Component) Action {
return Action{Type: at, Target: target, Template: template}
}
There's also a HTTP handler that takes all of the actions and renders them out to the HTTP response, using the appropriate `Content-Type` header.
func TurboStream(actions ...Action) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/vnd.turbo-stream.html")
for _, action := range actions {
action := action
templates.Action(string(action.Type), action.Target, action.Template).Render(r.Context(), w)
}
})
}
And a function that checks that whether the incoming request came from Turbo or not.
func IsTurboRequest(r *http.Request) bool {
return strings.Contains(r.Header.Get("accept"), "text/vnd.turbo-stream.html")
}
With that in place, we've got a database driven application with partial page updates without writing any JavaScript, or relying on a complex front-end framework like React.
It's server-side rendered, which provides good search engine optimisation and fast initial page load, and it even works without JavaScript.
-- Response ended
-- Page fetched on Sat Apr 27 18:17:51 2024
