index

Hero is a handy, fast and powerful go template engine, which pre-compiles the html templtes to go code. It has been used in production environment in bthub.io.

GoDoc Go Report Card

Features

  • Easy to use.
  • Powerful. template Extend and Include supported.
  • High performance.
  • Auto compiling when files change.

Install

go get -u github.com/shiyanhui/hero

Usage

hero [options]

options:
	- source:  the html template file or dir.
	- dest:    generated golang files dir, it will be the same with source if not set.
	- pkgname: the generated template package name, default is `template`.
	- watch:   whether automic compile when the source files change.

example:
	hero -source="./"
	hero -source="$GOPATH/src/app/template" -watch

Quick Start

Assume that we are going to render a user list userlist.html. index.html is the layout, and user.html is an item in the list.

And assumes that they are all under $GOPATH/src/app/template

index.html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
    </head>

    <body>
        <%@ body { %>
        <% } %>
    </body>
</html>

users.html

<%: func UserList(userList []string) []byte %>

<%~ "index.html" %>

<%@ body { %>
    <% for _, user := range userList { %>
        <ul>
            <%+ "user.html" %>
        </ul>
    <% } %>
<% } %>

user.html

<li>
    <%= user %>
</li>

Then we compile the templates to go code.

hero -source="$GOPATH/src/app/template"

We will get three new .go files under $GOPATH/src/app/template, i.e. index.html.go, user.html.go and userlist.html.go.

Then we write a http server in $GOPATH/src/app/main.go.

main.go

package main

import (
	"app/template"
	"net/http"
)

func main() {
	http.HandleFunc("/users", func(w http.ResponseWriter, req *http.Request) {
		var userList = []string {
          	"Alice",
			"Bob",
			"Tom",
		}
		w.Write(template.UserList(userList))
	})

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

At last, start the server and visit http://localhost:8080/users in your browser, we will get what we want!

Template syntax

There are only nine necessary kinds of statements, which are:

  • Function Definition <%: func define %>

    • Function definition statement defines the function which represents a html file.
    • The function defined should return one and only one parameter []byte.
    • Example:<%: func UserList(userList []string) []byte %> , which we have mentioned in quick start.

  • Extend <%~ "parent template" %>

    • Extend statement states the parent template the current template extends.
    • The parent template should be quoted with "".
    • Example: <%~ "index.html" >, which we have mentioned in quick start, too.

  • Include <%+ "sub template" %>

    • Include statement includes a sub-template to the current template. It works like #include in C++.
    • The sub-template should be quoted with "".
    • Example: <%+ "user.html" >, which we also have mentioned in quick start.

  • Import <%! go code %>

    • Import statement imports the packages used in the defined function, and it also contains everything that is outside of the defined function.

    • Import statement will NOT be inherited by child template.

    • Example:

    <%!
    import (
        "fmt"
        "strings"
    )

    var a int

    const b = "hello, world"

    func Add(a, b int) int {
        return a + b
    }

    type S struct {
        Name string
    }

    func (s S) String() string {
        return s.Name
    }
%>

  • Block <%@ blockName { %> <% } %>

    • Block statement represents a block. Child template overwrites blocks to extend parent template.

    • Example:

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
    </head>

    <body>
        <%@ body { %>
        <% } %>
    </body>
</html>

  • Code <% go code %>

    • Code statement states all code inside the defined function. It’s just go code.

    • Example:

    <% for _, user := userList { %>
    <% if user != "Alice" { %>
        <%= user %>
    <% } %>
<% } %>

<%
    a, b := 1, 2
    c := Add(a, b)
%>

  • Raw Value <%== statement %>

    • Raw Value statement will convert the variable to string.

    • Example:

    <%== a %>
<%== a + b %>
<%== Add(a, b) %>
<%== user.Name %>

  • Escaped Value <%= statement %>

    • Escaped Value statement is similar with Raw Value statement, but after converting, it will escaped it with html.EscapesString.

    • Example:

    <%= a %>
<%= a + b %>
<%= Add(a, b) %>
<%= user.Name %>

  • Note <%# note %>

    • Note statement add notes to the template.
    • It will not be added to the generated go source.
    • Example: <# this is just a note example>.

License

Hero is licensed under the Apache License.