README

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.

Trim Space

The <% %> blocks can be optionally adorned with a - on one or both sides to trigger trimming of whitespace on that side. For example <%-= r.Name %> will trim whitespace before the print block, but not after it.

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.

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AttrNames

func AttrNames(attrs map[string]interface{}) []string

    AttrNames returns a sorted list of names for an attribute set.

    Types

    type Attr

    type Attr struct {
    	Name    string
    	NamePos Pos
    
    	Value    string
    	ValuePos Pos
    }

      Attr represents a key/value passthrough pair on a component.

      type AttrEndBlock

      type AttrEndBlock struct {
      	Pos     Pos
      	Package string
      	Name    string
      }

        AttrEndBlock represents the closing block of an ego component attribute.

        func (*AttrEndBlock) Namespace

        func (blk *AttrEndBlock) Namespace() string

          Namespace returns the block package, if defined. Otherwise returns "ego".

          type AttrStartBlock

          type AttrStartBlock struct {
          	Pos     Pos
          	Package string
          	Name    string
          	Yield   []Block
          }

            AttrStartBlock represents the opening block of an ego component attribute.

            func (*AttrStartBlock) Namespace

            func (blk *AttrStartBlock) Namespace() string

              Namespace returns the block package, if defined. Otherwise returns "ego".

              type Block

              type Block interface {
              	// contains filtered or unexported methods
              }

                Block represents an element of the template.

                type CodeBlock

                type CodeBlock struct {
                	Pos       Pos
                	Content   string
                	TrimLeft  bool
                	TrimRight bool
                }

                  CodeBlock represents a Go code block that is printed as-is to the template.

                  type ComponentEndBlock

                  type ComponentEndBlock struct {
                  	Pos     Pos
                  	Package string
                  	Name    string
                  }

                    ComponentEndBlock represents the closing block of an ego component.

                    func (*ComponentEndBlock) Namespace

                    func (blk *ComponentEndBlock) Namespace() string

                      Namespace returns the block package, if defined. Otherwise returns "ego".

                      type ComponentStartBlock

                      type ComponentStartBlock struct {
                      	Pos        Pos
                      	Package    string
                      	Name       string
                      	Closed     bool
                      	Fields     []*Field
                      	Attrs      []*Attr
                      	AttrBlocks []*AttrStartBlock
                      	Yield      []Block
                      }

                        ComponentStartBlock represents the opening block of an ego component.

                        func (*ComponentStartBlock) Namespace

                        func (blk *ComponentStartBlock) Namespace() string

                          Namespace returns the block package, if defined. Otherwise returns "ego".

                          type Field

                          type Field struct {
                          	Name    string
                          	NamePos Pos
                          
                          	Value    string
                          	ValuePos Pos
                          }

                            Field represents a key/value pair on a component.

                            type Pos

                            type Pos struct {
                            	Path   string
                            	LineNo int
                            }

                              Pos represents a position in a given file.

                              func Position

                              func Position(blk Block) Pos

                                Position returns the position of the block.

                                type PrintBlock

                                type PrintBlock struct {
                                	Pos       Pos
                                	Content   string
                                	TrimLeft  bool
                                	TrimRight bool
                                }

                                  PrintBlock represents a block that will HTML escape the contents before outputting

                                  type RawPrintBlock

                                  type RawPrintBlock struct {
                                  	Pos       Pos
                                  	Content   string
                                  	TrimLeft  bool
                                  	TrimRight bool
                                  }

                                    RawPrintBlock represents a block of the template that is printed out to the writer.

                                    type Scanner

                                    type Scanner struct {
                                    	// contains filtered or unexported fields
                                    }

                                      Scanner is a tokenizer for ego templates.

                                      func NewScanner

                                      func NewScanner(r io.Reader, path string) *Scanner

                                        NewScanner initializes a new scanner with a given reader.

                                        func (*Scanner) Scan

                                        func (s *Scanner) Scan() (Block, error)

                                          Scan returns the next block from the reader.

                                          type SyntaxError

                                          type SyntaxError struct {
                                          	Message string
                                          	Pos     Pos
                                          }

                                          func NewSyntaxError

                                          func NewSyntaxError(pos Pos, format string, args ...interface{}) *SyntaxError

                                          func (*SyntaxError) Error

                                          func (e *SyntaxError) Error() string

                                          type Template

                                          type Template struct {
                                          	Path   string
                                          	Blocks []Block
                                          }

                                            Template represents an entire Ego template. A template consists of zero or more blocks. Blocks can be either a TextBlock, a PrintBlock, a RawPrintBlock, or a CodeBlock.

                                            func Parse

                                            func Parse(r io.Reader, path string) (*Template, error)

                                              Parse parses an Ego template from a reader. The path specifies the path name used in the compiled template's pragmas.

                                              func ParseFile

                                              func ParseFile(path string) (*Template, error)

                                                ParseFile parses an Ego template from a file.

                                                func (*Template) WriteTo

                                                func (t *Template) WriteTo(w io.Writer) (n int64, err error)

                                                  WriteTo writes the template to a writer.

                                                  type TextBlock

                                                  type TextBlock struct {
                                                  	Pos     Pos
                                                  	Content string
                                                  }

                                                    TextBlock represents a UTF-8 encoded block of text that is written to the writer as-is.

                                                    Directories

                                                    Path Synopsis
                                                    cmd
                                                    ego