An ERB-style templating language for Go.

Overview

Ego GoDoc

Ego is an ERb style templating language for Go. It works by transpiling templates into pure Go and including them at compile time. These templates are light wrappers around the Go language itself.

Install

You can find a release build of ego for Linux on the Releases page.

To install ego from source, you can run this command outside of the GOPATH:

$ go get github.com/benbjohnson/ego/...

Usage

Run ego on a directory. Recursively traverse the directory structure and generate Go files for all matching .ego files.

$ ego mypkg

How to Write Templates

An ego template lets you write text that you want to print out but gives you some handy tags to let you inject actual Go code. This means you don't need to learn a new scripting language to write ego templates—you already know Go!

Raw Text

Any text the ego tool encounters that is not wrapped in <% and %> tags is considered raw text. If you have a template like this:

hello!
goodbye!

Then ego will generate a matching .ego.go file:

io.WriteString(w, "hello!\ngoodbye!")

Unfortunately that file won't run because we're missing a package line at the top. We can fix that with code blocks.

Code Blocks

A code block is a section of your template wrapped in <% and %> tags. It is raw Go code that will be inserted into our generate .ego.go file as-is.

For example, given this template:

<%
package myapp

func Render(ctx context.Context, w io.Writer) {
%>
hello!
goodbye!
<% } %>

The ego tool will generate:

package myapp

import (
	"context"
	"io"
)

func Render(ctx context.Context, w io.Writer) {
	io.WriteString(w, "hello!\ngoodbye!")
}

Note the context and io packages are automatically imported to your template. These are the only packages that do this. You'll need to import any other packages you use.

Print Blocks

Our template is getting more useful. We now have actually runnable Go code. However, our templates typically need output text frequently so there are blocks specifically for this task called print blocks. These print blocks wrap a Go expression with <%= and %> tags.

We can expand our previous example and add a type and fields to our code:

<%
package myapp

type NameRenderer struct {
	Name  string
	Greet bool
}

func (r *NameRenderer) Render(ctx context.Context, w io.Writer) {
%>
	<% if r.Greet { %>
		hello, <%= r.Name %>!
	<% } else { %>
		goodbye, <%= r.Name %>!
	<% } %>
<% } %>

We now have a conditional around our Greet field and we are printing the Name field. Our generated code will look like:

package myapp

import (
	"context"
	"io"
)

type NameRenderer struct {
	Name  string
	Greet bool
}

func Render(ctx context.Context, w io.Writer) {
	if r.Greet {
		io.WriteString(w, "hello, ")
		io.WriteString(w, html.EscapeString(fmt.Sprint(r.Name)))
		io.WriteString(w, "!")
	} else {
		io.WriteString(w, "goodbye, ")
		io.WriteString(w, html.EscapeString(fmt.Sprint(r.Name)))
		io.WriteString(w, "!")
	}
}

Printing unescaped HTML

The <%= %> block will print your text as escaped HTML, however, sometimes you need the raw text such as when you're writing JSON. To do this, simply wrap your Go expression with <%== and %> tags.

Components

Simple code and print tags work well for simple templates but it can be difficult to make reusable functionality. You can use the component syntax to print types that implement this Renderer interface:

type Renderer interface {
	Render(context.Context, io.Writer)
}

Component syntax look likes HTML. You specify the type you want to instantiate as the node name and then use attributes to assign values to fields. The body of your component will be assigned as a closure to a field called Yield on your component type.

For example, let's say you want to make a reusable button that outputs Bootstrap 4.0 code: We can write this component as an ego template or in pure Go code. Here we'll write the component in Go:

package myapp

import (
	"context"
	"io"
)

type Button struct {
	Style string
	Yield func()
}

func (r *Button) Render(ctx context.Context, w io.Writer) {
	fmt.Fprintf(w, `<div class="btn btn-%s">`, r.Style)
	if r.Yield {
		r.Yield()
	}
	fmt.Fprintf(w, `</div>`)
}

Now we can use that component from a template in the same package like this:

<%
package myapp

type MyTemplate struct {}

func (r *MyTemplate) Render(ctx context.Context, w io.Writer) {
%>
	<div class="container">
		<ego:Button Style="danger">Don't click me!</ego:Button>
	</div>
<% } %>

Our template automatically convert our component syntax into an instance and invocation of Button:

var EGO Button
EGO.Style = "danger"
EGO.Yield = func() { io.WriteString(w, "Don't click me!") }
EGO.Render(ctx, w)

Field values can be specified as any Go expression. For example, you could specify a function to return a value for Button.Style:

<ego:Button Style=r.ButtonStyle()>Don't click me!</ego:Button>

Named closures

The Yield is a special instance of a closure, however, you can also specify named closures using the :: syntax.

Given a component type:

type MyView struct {
	Header func()
	Yield  func()
}

We can specify the separate closures like this:

<ego:MyView>
	<ego::Header>
		This content will go in the Header closure.
	</ego::Header>

	This content will go in the Yield closure.
</ego:MyView>

Importing components from other packages

You can import components from other packages by using a namespace that matches the package name The ego namespace is reserved to import types in the current package.

For example, you can import components from a library such as bootstrap-ego:

<%
package myapp

import "github.com/benbjohnson/bootstrap-ego"

type MyTemplate struct {}

func (r *MyTemplate) Render(ctx context.Context, w io.Writer) {
%>
	<bootstrap:Container>
		<bootstrap:Row>
			<div class="col-md-3">
				<bootstrap:Button Style="danger" Size="lg">Don't click me!</bootstrap:Button>
			</div>
		</bootstrap:Row>
	</bootstrap:Container>
<% } %>

Caveats

Unlike other runtime-based templating languages, ego does not support ad hoc templates. All templates must be generated before compile time.

Ego does not attempt to provide any security around the templates. Just like regular Go code, the security model is up to you.

Issues
  • Add support for HTML escaped string outputting

    Add support for HTML escaped string outputting

    This adds support for the <%- block which does HTML escaping for you. I chose <%- because that's what lodash uses, and I'd also prefer not to break backwards compat

    @benbjohnson

    Fixes #4

    opened by bouk 6
  • New release?

    New release?

    Would it be possible to tag the current master version as 0.3.0?

    I'm currently working on creating a FreeBSD port for faktory. This uses the current master ego for its webui. To keep things clean, I'm also writing a FreeBSD port for ego. As the templates used by faktory aren't compatible with ego 0.2.0, it'd be great to be able to package a new release of ego.

    opened by fabianfreyer 2
  • (perf) Replace bytes.Buffer with strings.Builder

    (perf) Replace bytes.Buffer with strings.Builder

    Improve performance by using strings.Builder instead of bytes.Buffer where possible.

    https://golang.org/doc/go1.10#strings

    https://golang.org/pkg/strings/#Builder

    opened by trakhimenok 2
  • use WriteString instead of Fprint for

    use WriteString instead of Fprint for "go vet" reasons

    The current implementation fmt.Fprint causes go vet issues ("possible formatting directive in Fprint call") if templates contain % signs (e.g. for css). See https://gist.github.com/tobstarr/fa73f87cb1953ca01e8a for an example.

    Instead one could just use io.WriteString, which is also quite a bit faster (see benchmark in gist).

    opened by tobstarr 2
  • Versioning

    Versioning

    Is there a recommended way to make sure all people working on a project using ego use the same version of ego? Different versions of ego can lead to unnecessary overwrites of the generated ego.go file without changes to the source templates.

    opened by tobstarr 2
  • v0.4.2 removes necessary whitespace

    v0.4.2 removes necessary whitespace

    My HTML pages are breaking because the v0.4.2 release strips the whitespace between these ego tags:

    <header class="row">
      <div class="col-5">
        <h3><%= t(req, "Batch") %> <%= st.Bid %></h3>
      </div>
    </header>
    

    The generated <h3> should contain Batch abc123 but contains Batchabc123. v0.4.1 works fine.

    opened by mperham 1
  • README: go get updates go mod in go1.16

    README: go get updates go mod in go1.16

    From the README executing go get github.com/benbjohnson/ego/... will just update go.mod and go.sum if executed from inside the project directory with go 1.16. I believe this is because GO111MODULE is now set to on by default.

    go install github.com/benbjohnson/[email protected] will work from any directory, but only in go 1.16. The wtf dial project relies on go1.16 which is why I installed ego and used this alternative command.

    opened by peebs 1
  • fix % signs in TextBlock

    fix % signs in TextBlock

    Using Fprint instead of Fprintf allows using of % signs in plain text (e.g. in embedded stylesheets).

    Otherwise plain text Hello % sign would be printed as Hello %!s(MISSING)ign

    opened by tobstarr 1
  • Definition Receivers

    Definition Receivers

    Change the DefinitionBlock to specify the full signature. This will allow for global templates or templates with receivers.

    <%! func MyTmpl(w io.Writer) error %>
    
    <%! func (x *MyType) MyTmpl(w io.Writer) error %>
    
    enhancement 
    opened by benbjohnson 1
  • Add component namespace support.

    Add component namespace support.

    Overview

    This pull request allows components to use an XML namespace to specify the importing package name. The namespace ego is reserved for the local package.

    Usage

    <%
    
    import "path/to/mypkg"
    
    func Render(ctx context.Context, w io.Writer) { %>
    <div>
    	<mypkg:Button Color="blue">Click Me</mypkg:Button>
    </div>
    <% } %>
    
    opened by benbjohnson 0
  • API & CLI improvements.

    API & CLI improvements.

    Overview

    This pull request changes ego by removing header and declaration blocks and simply outputting regular go files. Output also now goes to a single output file for each input file. Previously all files were consolidating to a single output file.

    The previous version of ego is available in the Releases page on GitHub as v0.2.0.

    opened by benbjohnson 0
  • Add support for namespaced elements with nsxml

    Add support for namespaced elements with nsxml

    Add support for XMLNS.

    Scanner now checks the attributes in ComponentStartBlock and if the attribute has xmlns: it adds the namespace to ComponentStartBlock.XMLNS.

    The parser checks if the current ComponentStartBlock.Package is in xmlns and rescans (ignoring the components and attribute blocks) and parses the ComponentStartBlock range. It cannot just convert the range to TextBlock because the attributes can contain PrintBlocks.

    <v:rect xmlns:v="urn:schemas-microsoft-com:vml" href="<%= link %>">
      <ego:Component foo=true />
    </v:rect>
    

    xmlns needs to be passed recursively while parsing because only the root tag has xmlns attribute.

    <v:rect xmlns:v="urn:schemas-microsoft-com:vml">
      <v:stroke linestyle="thinthin">
        <ego:Component foo=true />
      </v:stroke>
    </v:rect>
    

    Closes #36

    opened by bancek 0
  • make ego cli recursively find templates

    make ego cli recursively find templates

    The readme says the ego CLI recursively finds templates and processes them. This isn't true - it only goes 1 level deep. This change makes it recursive just like the readme says.

    opened by daaku 0
  • ego confused by 'bulletproof button'

    ego confused by 'bulletproof button'

    It's a common pattern in email templates to use 'bulletproof buttons' https://www.litmus.com/blog/a-guide-to-bulletproof-buttons-in-email-design/

    but this confuses ego, e.g. this snippet of HTML in an ego template

    <table class="body-action" align="center" width="100%" cellpadding="0" cellspacing="0">
                            <tr>
                            <td align="center">
                                <div>
                                <!--[if mso]><v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="<%=gifturl%>" style="height:45px;v-text-anchor:middle;width:200px;" arcsize="7%" stroke="f" fill="t">
                                <v:fill type="tile" color="#0072ce" />
                                <w:anchorlock/>
                                <center style="color:#ffffff;font-family:sans-serif;font-size:15px;">Get my gift!</center>
                                </v:roundrect><![endif]-->
                                <a href="<%=gifturl%>" class="button button--blue">Get my gift</a>
                                </div>
                            </td>
                            </tr>
                        </table>
    

    causes ego to emit

    //line email_gift_fulfilled_html.ego:33
    	_, _ = io.WriteString(w, html.EscapeString(fmt.Sprint(lib.FormatMoney(enrollment.Plan.GiftValue, 0, 2, false, true))))
    //line email_gift_fulfilled_html.ego:33
    	_, _ = io.WriteString(w, " gift. It's now ready and \n                    you can pick it up here:\n                    </p>\n                    <table class=\"body-action\" align=\"center\" width=\"100%\" cellpadding=\"0\" cellspacing=\"0\">\n                        <tr>\n                        <td align=\"center\">\n                            <div>\n                            <!--[if mso]>")
    //line email_gift_fulfilled_html.ego:40
    	{
    		var EGO v.roundrect
    		EGO.Attrs = map[string]string{
    			"xmlns:v": fmt.Sprint("urn:schemas-microsoft-com:vml"),
    			"xmlns:w": fmt.Sprint("urn:schemas-microsoft-com:office:word"),
    			"href":    fmt.Sprint("<%=gifturl%>"),
    			"style":   fmt.Sprint("height:45px;v-text-anchor:middle;width:200px;"),
    			"arcsize": fmt.Sprint("7%"),
    			"stroke":  fmt.Sprint("f"),
    			"fill":    fmt.Sprint("t"),
    		}
    		EGO.Yield = func() {
    //line email_gift_fulfilled_html.ego:41
    			_, _ = i
    

    which causes a subsequent compilation error

    undefined: v in v.roundrect
    undefined: v in v.fill
    ...etc...
    
    opened by kmanley 1
  • Render time support?

    Render time support?

    Has anyone added or know how to add rendering time output for templates? I have some slow pages and it would be a huge benefit to see something like:

    <!-- foo.ego in 43.1234ms -->
    

    in the page source. It would allow me to narrow down view performance issues to a specific template very quickly.

    opened by mperham 2
  • Only write if template changed

    Only write if template changed

    A small change that compares template mod time with output file mod time and skips writing if no template is newer than the output. Feel free to merge or ignore. Thanks again for ego!

    opened by kmanley 0
Releases(v0.4.3)
Owner
Ben Johnson
Ben Johnson
Amber is an elegant templating engine for Go Programming Language, inspired from HAML and Jade

amber Notice While Amber is perfectly fine and stable to use, I've been working on a direct Pug.js port for Go. It is somewhat hacky at the moment but

Ekin Koc 894 May 29, 2022
A strongly typed HTML templating language that compiles to Go code, and has great developer tooling.

A language, command line tool and set of IDE extensions that makes it easier to write HTML user interfaces and websites using Go.

Adrian Hesketh 122 Jun 12, 2022
Templating system for HTML and other text documents - go implementation

FAQ What is Kasia.go? Kasia.go is a Go implementation of the Kasia templating system. Kasia is primarily designed for HTML, but you can use it for any

Michał Derkacz 74 Mar 15, 2022
A sweet velvety templating package

Velvet Velvet is a templating package for Go. It bears a striking resemblance to "handlebars" based templates, there are a few small changes/tweaks, t

Buffalo - The Go Web Eco-System 73 Apr 14, 2022
Toothpaste is a simple templating engine for Go web applications, inspired by Blade/Twig

A simple HTML templating engine in Go inspired by Twig. Currently supports Variables, Escaping, If statements, Templating and Functional variables.

Mats 2 Dec 29, 2021
The mustache template language in Go

Overview mustache.go is an implementation of the mustache template language in Go. It is better suited for website templates than Go's native pkg/temp

Michael Hoisie 1k Jun 17, 2022
LeetCode in Go with the code style strictly follows the Google Golang Style Guide

LeetCode in Go LeetCode Online Judge is a website containing many algorithm questions. Most of them are real interview questions of Google, Facebook,

null 0 Nov 13, 2021
pongo2 is a Django-syntax like templating-language

Django-syntax like template-engine for Go

Florian Schlachter 2.3k Jun 25, 2022
Amber is an elegant templating engine for Go Programming Language, inspired from HAML and Jade

amber Notice While Amber is perfectly fine and stable to use, I've been working on a direct Pug.js port for Go. It is somewhat hacky at the moment but

Ekin Koc 894 May 29, 2022
A strongly typed HTML templating language that compiles to Go code, and has great developer tooling.

A language, command line tool and set of IDE extensions that makes it easier to write HTML user interfaces and websites using Go.

Adrian Hesketh 122 Jun 12, 2022
Templating system for HTML and other text documents - go implementation

FAQ What is Kasia.go? Kasia.go is a Go implementation of the Kasia templating system. Kasia is primarily designed for HTML, but you can use it for any

Michał Derkacz 74 Mar 15, 2022
A sweet velvety templating package

Velvet Velvet is a templating package for Go. It bears a striking resemblance to "handlebars" based templates, there are a few small changes/tweaks, t

Buffalo - The Go Web Eco-System 73 Apr 14, 2022
Templating system for HTML and other text documents - go implementation

FAQ What is Kasia.go? Kasia.go is a Go implementation of the Kasia templating system. Kasia is primarily designed for HTML, but you can use it for any

Michał Derkacz 74 Mar 15, 2022
Nomad Pack is a templating and packaging tool used with HashiCorp Nomad.

Nomad Pack is a templating and packaging tool used with HashiCorp Nomad.

HashiCorp 230 Jun 25, 2022
A project templating CLI tool.

Clonr Project Templating CLI About Installation Homebrew Go install npm Quick start for developers Configuring a project. Basic Example Example With G

null 2 Jan 29, 2022
Toothpaste is a simple templating engine for Go web applications, inspired by Blade/Twig

A simple HTML templating engine in Go inspired by Twig. Currently supports Variables, Escaping, If statements, Templating and Functional variables.

Mats 2 Dec 29, 2021
Generic templating tool with support of JSON, YAML and TOML data

gotempl Small binary used to generate files from Go Templates and data files. The following formats are supported: JSON YAML TOML Usage usage: gotempl

Link Society 7 Jun 15, 2022
LevelDB style LRU cache for Go, support non GC object.

Go语言QQ群: 102319854, 1055927514 凹语言(凹读音“Wa”)(The Wa Programming Language): https://github.com/wa-lang/wa LRU Cache Install go get github.com/chai2010/c

chai2010 11 Jul 5, 2020
Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.

Description pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags. pflag is compatible with the GNU extensions to

Steve Francia 1.8k Jun 29, 2022
A golang package for parsing ini-style configuration files

Mini Mini is a simple ini configuration file parser. The ini syntax supported includes: The standard name=value Comments on new lines starting with #

Stephen Asbury 30 Apr 2, 2022
Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.

Description pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags. pflag is compatible with the GNU extensions to

Alex Ogier 516 Jun 24, 2022
libketama-style consistent hashing in Go

===================================== ketama.go libketama-style consistent hashing in Go Author: Nolan Caudill ([email protected]) Date: 2011-06

Nolan Caudill 73 Apr 3, 2022
Django style fixtures for Golang's excellent built-in database/sql library.

go-fixtures Django style fixtures for Golang's excellent built-in database/sql library. Currently only YAML fixtures are supported. There are two rese

Richard Knop 27 Mar 8, 2022
Crash your app in style (Golang)

panicparse Parses panic stack traces, densifies and deduplicates goroutines with similar stack traces. Helps debugging crashes and deadlocks in heavil

M-A 3.2k Jun 30, 2022
Bampf is a simple 3D arcade style game. Collect Energy Cores in order to finish a level. Teleport (bampf) to safety or use cloaking abilities to avoid Sentinels.

Bampf Bampf is a simple 3D arcade style game. Collect energy cores in order to finish a level. Teleport (bampf) to safety or use cloaking abilities to

null 39 Apr 7, 2021
package for building REST-style Web Services using Go

go-restful package for building REST-style Web Services using Google Go Code examples using v3 REST asks developers to use HTTP methods explicitly and

Ernest Micklei 4.5k Jun 29, 2022
FactorLog is a logging infrastructure for Go that provides numerous logging functions for whatever your style may be

FactorLog FactorLog is a fast logging infrastructure for Go that provides numerous logging functions for whatever your style may be. It could easily b

Kevin Darlington 54 Oct 12, 2021
Easy AWK-style text processing in Go

awk Description awk is a package for the Go programming language that provides an AWK-style text processing capability. The package facilitates splitt

Scott Pakin 93 May 5, 2022