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 command line tool, which reads .tmpl files in your project and generates go source code. The command line tool uses the library (mainly the Build function). The README for the library can be found at github.com/go-humble/temple/temple.
The command line tool first reads the contents of all the .tmpl files in the specified src directory
(and it's sub-directories). Then it generates go code at the specified dest file which compiles the
templates. The generated code uses strings which contain the content of source files as arguments to
template.Parse
.
This is useful for a few reasons. If you're building and deploying binary executables, it means you no longer have to ship a templates folder with your binary distribution. It also makes it possible for you to use templates in code that has been compiled to javascript with gopherjs and is running in a browser. Since code generated by temple works exactly the same on the server and client, it also enables you to share templates between them. Check out go-humble/examples/people for an example of how shared templates can work.
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.
Install the temple command line tool with the following.
go get -u github.com/go-humble/temple
You may also need to install gopherjs. The latest version is recommended. Install gopherjs with:
go get -u github.com/gopherjs/gopherjs
The temple command line tool has one main subcommand called build
. Typical usage will look
something like this:
temple build templates templates/templates.go
The first argument, in this case templates
, is a directory which contains your .tmpl files.
The second argument, in this case templates/templates.go
is the name of a file where generated
code will be written. If the file does not exist, temple will create it for you, and any previous
content will be overwritten.
You can run temple help
to learn more about the possible commands and temple help build
to
learn more about the build command specifically.
The code generated by the temple command line tool will look something like this:
package templates
// This package has been automatically generated with temple.
// Do not edit manually!
import (
"github.com/go-humble/temple/temple"
)
var (
GetTemplate func(name string) (*temple.Template, error)
GetPartial func(name string) (*temple.Partial, error)
GetLayout func(name string) (*temple.Layout, error)
MustGetTemplate func(name string) *temple.Template
MustGetPartial func(name string) *temple.Partial
MustGetLayout func(name string) *temple.Layout
)
func init() {
var err error
g := temple.NewGroup()
if err = g.AddPartial("head", `...`); err != nil {
panic(err)
}
if err = g.AddLayout("app", `...`); err != nil {
panic(err)
}
if err = g.AddTemplate("people/index", `...`); err != nil {
panic(err)
}
GetTemplate = g.GetTemplate
GetPartial = g.GetPartial
GetLayout = g.GetLayout
MustGetTemplate = g.MustGetTemplate
MustGetPartial = g.MustGetPartial
MustGetLayout = g.MustGetLayout
}
The code creates a single template Group
and adds the templates, partials, and layouts (if applicable) to the group. Then it exposes the methods of
the group for getting templates, partials, and layouts as exported global functions.
The temple.Template,
temple.Partial, and
temple.Layout types all inherit from
the builtin
Template type from the html/template package. That
means you can render them like regular templates with the
Execute
method. Temple also provides an
additional method for rendering templates in the dom called
ExecuteEl
.
In go, every template needs to have a name. temple assigns a name to each template based on its
filename and location relative to the src directory. So for example, if you had a template file
located at templates/people/show.tmpl
and templates
was your src directory, the name assigned
to the template would be "people/show"
.
Temple uses two optional groups called "partials" and "layouts" to help organize template files.
You can specify a directory that contains partials with the --partials
flag, and a directory
that contains layouts with the --layouts
flag. Any .tmpl files found in these directories will
be treated specially, and they should not overlap with each other or the src directory with all
your regular templates ("regular templates" is the name we'll use to refer to .tmpl files in the
src directory that are neither partials or layouts). This organization feature is completely optional,
so if you don't want to use it, you omit the --partials
and --layouts
flags and manage your
templates any way you want.
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 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. The name of the partial templates is based on its filename and location relative to the
partials directory. PartialsPrefix
is added
to the template name of all partials, which by default is simply "partials/"
.
So if your partials directory is my-partials
, and you have the following partial template file located
at my-partials/head.tmpl
:
You could render it inside of another template like so:
Check out the partials in go-humble/examples/people for a more in-depth example.
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. The name of the layout
templates is based on its filename and location relative to the layouts directory.
LayoutsPrefix
is added to the template
name of all layouts, which by default is simply "layouts/"
.
For example, if your layouts directory is my-layouts
, and you have the following layout template file
located at my-layouts/app.tmpl
:
You could then render a template inside of the layout by first defining the "content" sub-template and then rendering the layout:
If you rendered the template (not the layout), the output would look like this:
<!doctype html>
<html>
<head>
<title>Example Humble Application</title>
</head>
<body>
Hello, Content!
</body>
</html>
Check out the layouts in go-humble/examples/people for a more in-depth example.
Temple uses regular go testing, so you can run the all the tests with go test ./...
.
See CONTRIBUTING.md
Temple is licensed under the MIT License. See the LICENSE file for more information.