Welcome

Welcome, and thank you for your interest in torque!

🪲 Found a bug? Please direct all issues to the GitHub Issues tracker.

🎁 All feedback is a gift! Please leave comments and questions in the GitHub Discussions space.

Installation

Quick Start

This quick start tutorial will show you how to use torque to build out a dynamically rendered webpage using the net/http package and an html/template from Go's standard library.

See the fully working example code.

The torque workflow starts with a standard html/template. For more information on the syntax, see this useful syntax primer from HashiCorp.

ViewModel

In order to tie your template to your Go code, declare a ViewModel struct that represents the "dot context" of the template. The dot context is the value of the "dot" ({{ . }}) in Go's templating language.

Conceptually ViewModel is a type that represents the shape of the data that is rendered in response to an HTTP request. Think the same data model that can be viewed in different formats such as JSON response body or HTML template data.

In this struct, any exported fields (or methods attached via pointer receiver) will be accessible in your template from the all powerful dot.

TemplateProvider

In order to associate your ViewModel struct to your template your struct type must implement the TemplateProvider interface:

The most straightforward approach is to embed the template into your Go program by using the embed package from the standard library.

Controller

To turn your template into a fully functioning web page, you'll need to build a Controller that will handle incoming HTTP requests and render the template.

The torque Controller API provides a set of interfaces that your Controller struct can implement to handle different types of HTTP requests made by a web browser.

Loader[T]

The Loader interface is the only required interface in the torque framework. Its job is to fetch data during a GET request, and return a ViewModel struct to be later "rendered" into a response.

Loader has a generic constraint T that represents your ViewModel and allows you to return it directly from Load:

By implementing Loader[T], you're enabling your Controller to fetch the ViewModel and render it in response to an HTTP GET request from the browser.

It is best practice to enforce Go's static type system by asserting the interfaces you'd like to implement at compile time:

Constructing a Handler

To serve your new page over HTTP, create a new http.Handler instance with the New function by passing a reference to your Controller struct.

Finally, visit http://localhost:9001 in your browser to see the rendered page.

Congratulations! You've just built a server rendered webpage using torque.

Next Steps

Hopefully that's enough to get you started! There's plenty more to learn about torque, though. Here's a few next steps to consider:

📎 Bookmark the Controller API Reference and keep it on hand as you build out your applications.

🛠️ Check out the examples workspace to see some fully functioning applications built with torque! Including this docsite.

🎁 Please leave comments and questions in the GitHub Discussions space!

Thanks again for giving torque a try!