Textwire

Appearance

Usage with Templates ​

Simple Usage ​

Import github.com/textwire/textwire/v3 and call textwire.NewTemplate(nil) to create a template instance. Pass nil for defaults, or a *config.Config to customize. See configuration options.

Choose one of these initialization patterns:

  1. Global — tpl is a package variable accessible from any handler
  2. Local — tpl is created in main() and injected into handlers
go
import (
    "net/http"
    "github.com/textwire/textwire/v3"
)

var tpl *textwire.Template

func main() {
    tpl, _ = textwire.NewTemplate(nil)
    http.HandleFunc("/", homeHandler)
    http.ListenAndServe(":8080", nil)
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    tpl.Response(w, "views/home", nil)
}
go
import (
	"net/http"
	"github.com/textwire/textwire/v3"
)

func main() {
	tpl, _ := textwire.NewTemplate(nil)
	http.HandleFunc("/", homeHandler(tpl))
	http.ListenAndServe(":8080", nil)
}

func homeHandler(tpl *textwire.Template) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		tpl.Response(w, "views/home", nil)
	}
}

Both patterns work—use global for simplicity, local for testability. Call NewTemplate only once at startup; it parses all templates into memory.

Writing Responses to the Client ​

Choose how to output your rendered template:

go
func homeHandler(w http.ResponseWriter, r *http.Request) {
    err := tpl.Response(w, "views/home", map[string]any{
        "title": "Home page",
    })
    if err != nil {
        log.Printf("Template error: %v", err)
    }
}
go
func generateEmail() (string, error) {
    out, failure := tpl.String("emails/welcome", map[string]any{
        "name": user.Name,
    })
    if failure != nil {
        return "", failure.Error()
    }
    return out, nil
}
  • Response() — Writes directly to HTTP response. Returns standard error.
  • String() — Returns rendered string and *fail.Error with detailed info (line, filepath, message). Call failure.Error() to convert to standard error.

Live Reload

If your template files are not showing up after you've created them and you are using live-reloading libraries like Fresh or Air, restart them. Also, don't forget to add .tw files to trigger live-reloading.

Layouts ​

Defining a layout in Textwire is straightforward. Create a layout file anywhere within your templates directory. Many developers organize layouts in a templates/layouts/ directory to manage different layouts such as main.tw, admin.tw, and user.tw.

Reserving Space in Layouts ​

The @reserve directive reserves placeholders for dynamic content that can be inserted later. For example, you can reserve a space for the page title and then populate it from other templates such as about-me.tw or contact-us.tw. Here is an example layout file:

textwire
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>@reserve("title")</title>
</head>
<body>
    @reserve("content")
</body>
</html>

This layout reserves spaces for the page title and content. These placeholders can be populated with data from templates that extend this layout. The next section explains how to insert content into reserved spaces.

Inserting Content into Reserved Spaces ​

The @insert directive inserts content into reserved placeholders. It can be used in two ways: with or without a body. In the following example, we insert content for "title" without a body and for "content" with a body.

Here is an example templates/views/home.tw template:

textwire
@use("layouts/main")

@insert("title", "Home page")

@insert("content")
    <h1>Hello, World!</h1>
    <p>This is a home page.</p>
@end
  • First, we specify which layout to use by providing the layout path
  • Then we insert the title into the layout with the value "Home page"
  • Finally, we insert the main content into the layout with the HTML body.

You can read more about @use, @insert and @reserve directives on the statements page if you need more information about the syntax.

Configuration ​

The NewTemplate function accepts a *config.Config parameter with several properties to customize template behavior. Common use cases include overriding the default file format or specifying the template directory. Here is an example of configuration:

go
import (
    "fmt"
    "net/http"

    "github.com/textwire/textwire/v3"
    "github.com/textwire/textwire/v3/config"
)

var tpl *textwire.Template

func main() {
    var err error

    tpl, err = textwire.NewTemplate(&config.Config{
        TemplateDir: "src/templates",
    })

    if err != nil {
        fmt.Println(err)
    }

    http.HandleFunc("/", homeHandler)

    http.ListenAndServe(":8080", nil)
}

For detailed information about available configuration options, visit the configurations page.