temple

Humble/Temple

Version 0.1.3

A library and a command line tool for sanely managing go templates, with the ability to share them between client and server. The library and code generated by the cli are both compatible with gopherjs, so you can compile to javascript and run in the browser. Temple works great as a stand-alone package or in combination with other packages in the Humble Framework.

This README is specific to the library, which offers helper functions and methods for managing templates and rendering them in the DOM. The README for the command line tool can be found at github.com/go-humble/temple.

What Does the Library Do?

The temple library can be used on its own or in conjunction with code generated by the command line tool. It offers some utility functions for organizing templates into distinct categories: regular templates, partials, and layouts. It also lets you load templates from files or load inline templates from the DOM, and provides helper methods for rendering to the DOM.

Temple uses the builtin html/template package. If you are not already familiar with go's builtin templates, it is highly recommended that you read the documentation for them before continuing.

Browser Support

Temple is regularly tested with IE9+ and the latest versions of Chrome, Safari, and Firefox.

Javascript code generated with gopherjs uses typed arrays, so in order to work with IE9, you will need a polyfill for typed arrays.

Installation

Install the temple library with the following.

go get github.com/go-humble/temple/temple`

You may also need to install gopherjs. The latest version is recommended. Install gopherjs with:

go get -u github.com/gopherjs/gopherjs

Quickstart Guide

Loading Templates

All templates, partials, and layouts must belong to a group. To create a new group, use the NewGroup function:

g := NewGroup()

From a String

To add template to the group, you can use the AddTemplate method. It takes two arguments, the name of the template and the source.

if err := g.AddTemplate("home", "<h2>Home</h2>"); err != nil {
	// Handle err
}

From a File

To add a template file, you can use the AddTemplateFile method, which takes the name of the template and the path to the file as an argument.

if err := g.AddTemplateFile("home", "templates/home.tmpl"); err != nil {
	// Handle err
}

From a Directory

You can also add multiple files in a directory at once with the AddTemplateFiles method. When you use this method, the templates created from the files will automatically get a name based on the filename and location relative to the given directory. So for example, if you had a template file located at templates/people/show.tmpl and passed templates as the dir argument, the name assigned to the template would be "people/show".

if err := g.AddTemplateFiles("templates"); err != nil {
	// Handle err
}

From the DOM

Finally, if you compile to javascript with gopherjs, you can load inline templates from the DOM with the AddInlineTemplate method.

if err := g.AddInlineTemplate(document.QuerySelector("script[type='text/template']#home")); err != nil {
	// Handle err
}

The method expects a dom.Element from the gopherjs dom bindings as an argument. Typically this would be a script tag that looks something like:

<script type="text/template" id="home">
	<h2>Home</h2>
</script>

The AddInlineTemplate method will use the id property of the element as the template name, and the innerHTML of the given element as the template source.

You can also load multiple inline templates (as well as partials and layouts) at once with the AddAllInline method, which scans the DOM for script tags with a type attribute of "text/template".

if err := g.AddAllInline(); err != nil {
	// Handle err
}

It uses the id property as the template name, and the special data-kind attribute to distinguish between regular templates, partials, and layouts.

Getting Templates

Once a template has been added to a group, you can get it with the GetTemplate method:

homeTmpl, err := g.GetTemplate("home")
if err != nil {
	// Handle error
}

This returns a pointer to a temple.Template, which is merely a wrapper around the template.Template type from the builtin html/template package. temple.Template has all the same methods as a builtin template, and also introduces an ExecuteEl method for rendering the template to the DOM.

In some cases, you just want to fail fast if a template is not found. You can use the MustGetTemplate method, which will panic instead of returning an error. This is analogous to the Temlate.Must method in the text/template and html/template packages in the standard library, and is useful for variable declarations.

var (
	homeTmpl = g.MustGetTemplate("home")
	indexTmpl = g.MustGetTemplate("index")
	todoTmpl = g.MustGetTemplate("todo")
)

Rendering Templates

To an io.Writer

To render a template to an io.Writer, you can just use the Execute method. Since http.ResponseWriter implements io.Writer it is common to render templates this way on the server:

func HomeHandler(res http.ResponseWriter, req *http.Request) {
	homeTmpl, err := g.GetTemplate("home")
	if err != nil {
		// Handle error
	}
	if err := homeTmpl.Execute(res, nil); err != nil {
		// Handle error
	}
}

The second argument to Execute is the data that will be passed into the template.

To an Element in the DOM

You can also render a template to an element in the DOM with the ExecuteEl method. This is the most common way to render templates for code which has been compiled to javascript with gopherjs and is running in the browser.

homeTmpl, err := g.GetTemplate("home")
if err != nil {
	// Handle error
}
if err := homeTmpl.ExecuteEl(document.QuerySelector("body"), nil); err != nil {
	// Handle err
}

Partials and Layouts

Temple uses two optional groups called "partials" and "layouts" to help organize templates. To add partials or layouts, use the same methods for adding templates, but replace the word Template with Partial or Layout (e.g. AddLayout, AddInlinePartials, AddLayoutFile).

Before continuing, it is recommended that you read the documentation for the text/template and html/template packages. In addition, this article about template inheritence in go will help explain some of the concepts that temple uses.

Partials

Partials are templates which typically represent only part of a full page. For example, you might have a partial for rendering a single model or a partial for the head section of your html. Partials are associated with (i.e., added to the parse tree of) all other partials, in addition to layouts and regular templates. That means you can render a partial inside of a regular template or layout with the template action. PartialsPrefix is added to the template name of all partials, which by default is simply "partials/".

So for example, you could have partials located in the my-partials directory and add them to a group with g.AddPartialFiles("my-partials"). Let's say you have the following partial file located at my-partials/head.tmpl:

<head>
	<title>Example Humble Application</title>
	<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css" rel="stylesheet">
</head>

Let's also say that you have regular template files located in the my-templates directory, which you have added to the same group with g.AddTemplateFiles("my-templates"). And the following regular template located at my-templates/index.tmpl:

<!doctype html>
<html>
	{{ template "partials/head" }}
	<body>
	</body>
</html>

Then, if you rendered the template with the following code:

indexTmpl, err := g.GetTemplate("index")
if err != nil {
	// Handle error
}
if err := indexTmpl.Execute(os.Stdout, nil); err != nil {
	// Handle err
}

You would see the following output:

<!doctype html>
<html>
	<head>
		<title>Example Humble Application</title>
		<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css" rel="stylesheet">
	</head>
	<body>
	</body>
</html>

Check out the partials in go-humble/examples/people for a more in-depth example.

Layouts

Layouts are templates which define the structure for a page and require another template to fill in the details. Typically, layouts will use one or more template actions to render partials or regular templates inside of some structure. Layouts are associated with (i.e., added to the parse tree of) all regular templates and have access to partials. That means you can render layouts inside of a regular template, typically after declaring some sub-template that the layout expects to be defined. LayoutsPrefix is added to the template name of all layouts, which by default is simply "layouts/".

So for example, you could have layouts located in the my-layouts directory, and add them to a group with g.AddLayoutFiles("my-layouts"). Let's say you have the following layout file located at my-layouts/app.tmpl:

<!doctype html>
<html>
	<head>
		<title>Example Humble Application</title>
	</head>
	<body>
		{{ template "content" . }}
	</body>
</html>

Let's also say that you have regular template files located in the my-templates directory, which you have added to the same group with g.AddTemplateFiles("my-templates"). And the following regular template located at my-templates/hello.tmpl:

{{ define "content" }}
	Hello, {{ . }}!
{{ end }}
{{ template "layouts/app" . }}

Notice that we used the . in both the {{ template "content" . }} and the {{ template "layouts/app" . }} expressions to pass in the template data from the regular template to the layout. If you rendered the template with the following code:

helloTmpl, err := g.GetTemplate("hello")
if err != nil {
	// Handle error
}
if err := helloTmpl.Execute(os.Stdout, "World"); err != nil {
	// Handle err
}

You would see output that looked like this:

<!doctype html>
<html>
	<head>
		<title>Example Humble Application</title>
	</head>
	<body>
		Hello, World!
	</body>
</html>

Check out the layouts in go-humble/examples/people for a more in-depth example.

Testing

Temple uses regular go testing, so you can run the all the tests with go test ..

Contributing

See CONTRIBUTING.md

License

Temple is licensed under the MIT License. See the LICENSE file for more information.