A sweet velvety templating package

Overview

Velvet GoDoc Build Status Code Climate

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

General Usage

If you know handlebars, you basically know how to use Velvet.

Let's assume you have a template (a string of some kind):

<!-- some input -->
<h1>{{ name }}</h1>
<ul>
  {{#each names}}
    <li>{{ @value }}</li>
  {{/each}}
</ul>

Given that string, you can render the template like such:

ctx := velvet.NewContext()
ctx.Set("name", "Mark")
ctx.Set("names", []string{"John", "Paul", "George", "Ringo"})
s, err := velvet.Render(input, ctx)
if err != nil {
  // handle errors
}

Which would result in the following output:

<h1>Mark</h1>
<ul>
  <li>John</li>
  <li>Paul</li>
  <li>George</li>
  <li>Ringo</li>
</ul>

Helpers

If Statements

What to do? Should you render the content, or not? Using Velvet's built in if, else, and unless helpers, let you figure it out for yourself.

{{#if true }}
  render this
{{/if}}

Else Statements

{{#if false }}
  won't render this
{{ else }}
  render this
{{/if}}

Unless Statements

{{#unless true }}
  won't render this
{{/unless}}

Each Statements

Into everyone's life a little looping must happen. We can't avoid the need to write loops in applications, so Velvet helps you out by coming loaded with an each helper to iterate through arrays, slices, and maps.

Arrays

When looping through arrays or slices, the block being looped through will be access to the "global" context, as well as have four new variables available within that block:

  • @first [bool] - is this the first pass through the iteration?
  • @last [bool] - is this the last pass through the iteration?
  • @index [int] - the counter of where in the loop you are, starting with 0.
  • @value - the current element in the array or slice that is being iterated over.
<ul>
  {{#each names}}
    <li>{{ @index }} - {{ @value }}</li>
  {{/each}}
</ul>

By using "block parameters" you can change the "key" of the element being accessed from @value to a key of your choosing.

<ul>
  {{#each names as |name|}}
    <li>{{ name }}</li>
  {{/each}}
</ul>

To change both the key and the index name you can pass two "block parameters"; the first being the new name for the index and the second being the name for the element.

<ul>
  {{#each names as |index, name|}}
    <li>{{ index }} - {{ name }}</li>
  {{/each}}
</ul>

Maps

Looping through maps using the each helper is also supported, and follows very similar guidelines to looping through arrays.

  • @first [bool] - is this the first pass through the iteration?
  • @last [bool] - is this the last pass through the iteration?
  • @key - the key of the pair being accessed.
  • @value - the value of the pair being accessed.
<ul>
  {{#each users}}
    <li>{{ @key }} - {{ @value }}</li>
  {{/each}}
</ul>

By using "block parameters" you can change the "key" of the element being accessed from @value to a key of your choosing.

<ul>
  {{#each users as |user|}}
    <li>{{ @key }} - {{ user }}</li>
  {{/each}}
</ul>

To change both the key and the value name you can pass two "block parameters"; the first being the new name for the key and the second being the name for the value.

<ul>
  {{#each users as |key, user|}}
    <li>{{ key }} - {{ user }}</li>
  {{/each}}
</ul>

Other Builtin Helpers

  • json - returns a JSON marshaled string of the value passed to it.
  • js_escape - safely escapes a string to be used in a JavaScript bit of code.
  • html_escape - safely escapes a string to be used in an HTML bit of code.
  • upcase - upper cases the entire string passed to it.
  • downcase - lower cases the entire string passed to it.
  • markdown - converts markdown to HTML.
  • len - returns the length of an array or slice

Velvet also imports all of the helpers found https://github.com/markbates/inflect/blob/master/helpers.go

Custom Helpers

No templating package would be complete without allowing for you to build your own, custom, helper functions.

Return Values

The first thing to understand about building custom helper functions is their are a few "valid" return values:

string

Return just a string. The string will be HTML escaped, and deemed "not"-safe.

func() string {
  return ""
}

string, error

Return a string and an error. The string will be HTML escaped, and deemed "not"-safe.

func() (string, error) {
  return "", nil
}

template.HTML

https://golang.org/pkg/html/template/#HTML

Return a template.HTML string. The template.HTML will not be HTML escaped, and will be deemed safe.

func() template.HTML {
  return template.HTML("")
}

template.HTML, error

Return a template.HTML string and an error. The template.HTML will not be HTML escaped, and will be deemed safe.

func() ( template.HTML, error ) {
  return template.HTML(""), error
}

Input Values

Custom helper functions can take any type, and any number of arguments. There is an option last argument, velvet.HelperContext, that can be received. It's quite useful, and I would recommend taking it, as it provides you access to things like the context of the call, the block associated with the helper, etc...

Registering Helpers

Custom helpers can be registered in one of two different places; globally and per template.

Global Helpers

err := velvet.Helpers.Add("greet", func(name string) string {
  return fmt.Sprintf("Hi %s!", name)
})
if err != nil {
  // handle errors
}

The greet function is now available to all templates that use Velvet.

s, err := velvet.Render(`<h1>{{greet "mark"}}</h1>`, velvet.NewContext())
if err != nil {
  // handle errors
}
fmt.Print(s) // <h1>Hi mark!</h1>

Per Template Helpers

t, err := velvet.Parse(`<h1>{{greet "mark"}}</h1>`)
if err != nil {
  // handle errors
}
t.Helpers.Add("greet", func(name string) string {
  return fmt.Sprintf("Hi %s!", name)
})
if err != nil {
  // handle errors
}

The greet function is now only available to the template it was added to.

s, err := t.Exec(velvet.NewContext())
if err != nil {
  // handle errors
}
fmt.Print(s) // <h1>Hi mark!</h1>

Block Helpers

Like the if and each helpers, block helpers take a "block" of text that can be evaluated and potentially rendered, manipulated, or whatever you would like. To write a block helper, you have to take the velvet.HelperContext as the last argument to your helper function. This will give you access to the block associated with that call.

Example

velvet.Helpers.Add("upblock", func(help velvet.HelperContext) (template.HTML, error) {
  s, err := help.Block()
  if err != nil {
    return "", err
  }
  return strings.ToUpper(s), nil
})

s, err := velvet.Render(`{{#upblock}}hi{{/upblock}}`, velvet.NewContext())
if err != nil {
  // handle errors
}
fmt.Print(s) // HI
Issues
  • Comment

    Comment

    I don't see it documented anyplace, but is it possible add comments to the template? For example: {{#comment This text will not be rendered, or shown in the html }}

    opened by goldbattle 3
  • Any thought to support dot accessors for fields?

    Any thought to support dot accessors for fields?

    It's be nice to iterate over a list of maps or something and access values like {{ @value.display_name }}, especially if there is potentially several bits of data I want to attach to the values and use elsewhere in the template.

    I tried this:

    Players in room:
    {{#each players}}{{ @value.display_name }}
    {{/each}}
    

    (I'm using this for text, not HTML so it gets weird).

    The data passed to the template was:

    var data = map[string]interface{}{
            "players": []map[string]interface{}{
                    {"display_name": "PlayerOne"},
                    {"display_name": "PlayerTwo"},
            },
    }
    opened by bbuck 0
  • Be able to change the interpolation delimiters

    Be able to change the interpolation delimiters

    This is so that Velvet can play nice with Handlebars in the case of a SPA frontend being used with Buffalo.

    Original issue here: https://github.com/gobuffalo/buffalo/issues/127

    opened by howdoicomputer 0
Owner
Buffalo - The Go Web Eco-System
Buffalo - The Go Web Eco-System
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 896 Aug 13, 2022
An ERB-style templating language for Go.

Ego 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

Ben Johnson 529 Aug 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
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 131 Aug 3, 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 3 Jul 24, 2022
Package damsel provides html outlining via css-selectors and common template functionality.

Damsel Markup language featuring html outlining via css-selectors, extensible via pkg html/template and others. Library This package expects to exist

Daniel Skinner 25 Jan 24, 2022
Wrapper package for Go's template/html to allow for easy file-based template inheritance.

Extemplate Extemplate is a small wrapper package around html/template to allow for easy file-based template inheritance. File: templates/parent.tmpl <

Danny van Kooten 50 Jul 31, 2022
Jazigo is a tool written in Go for retrieving configuration for multiple devices, similar to rancid, fetchconfig, oxidized, Sweet.

Table of Contents About Jazigo Supported Platforms Features Requirements Quick Start - Short version Quick Start - Detailed version Global Settings Im

null 181 Jul 5, 2022
pongo2 is a Django-syntax like templating-language

Django-syntax like template-engine for Go

Florian Schlachter 2.3k Aug 9, 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 896 Aug 13, 2022
An ERB-style templating language for Go.

Ego 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

Ben Johnson 529 Aug 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
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 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 131 Aug 3, 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 246 Aug 12, 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 3 Jul 24, 2022
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
A Go (golang) package that enhances the standard database/sql package by providing powerful data retrieval methods as well as DB-agnostic query building capabilities.

ozzo-dbx Summary Description Requirements Installation Supported Databases Getting Started Connecting to Database Executing Queries Binding Parameters

Ozzo Framework 565 Jul 28, 2022
Go Package Manager (gopm) is a package manager and build tool for Go.

?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? In favor of Go Modules Proxy since Go 1.11, this pr

Go Package Manager 2.5k Aug 8, 2022
Package set is a small wrapper around the official reflect package that facilitates loose type conversion and assignment into native Go types.

Package set is a small wrapper around the official reflect package that facilitates loose type conversion and assignment into native Go types. Read th

null 37 Jun 15, 2022
Go package providing simple database and server interfaces for the CSV files produced by the sfomuseum/go-libraryofcongress package

go-libraryofcongress-database Go package providing simple database and server interfaces for the CSV files produced by the sfomuseum/go-libraryofcongr

San Francisco International Airport Museum 1 Oct 29, 2021
A package for running subprocesses in Go, similar to Python's subprocesses package.

A package for running subprocesses in Go, similar to Python's subprocesses package.

Esteban Garcia 5 Jul 28, 2022
Utility to restrict which package is allowed to import another package.

go-import-rules Utility to restrict which package is allowed to import another package. This tool will read import-rules.yaml or import-rules.yml in t

PAYFAZZ 0 Jan 7, 2022
A package for running subprocesses in Go, similar to Python's subprocesses package.

Subprocesses Spawn subprocesses in Go. Sanitized mode package main import ( "log" "github.com/estebangarcia21/subprocess" ) func main() { s := s

Esteban Garcia 5 Jul 28, 2022
An errors package optimized for the pkg/errors package

errors An errors package optimized for the pkg/errors package Use Download and install go get github.com/dobyte/errors API // New Wrapping for errors.

Fuxiao 3 Mar 2, 2022
Wmi - One hot Go WMI package. Package wmi provides an interface to WMI. (Windows Management Instrumentation)

wmi Package wmi provides an interface to WMI. (Windows Management Instrumentation) Install go get -v github.com/moonchant12/wmi Import import "github.

MoonChant 2 Apr 22, 2022
Elastos.ELA.Rosetta.API - How to write a Rosetta server and use either the Client package or Fetcher package to communicate

Examples This folder demonstrates how to write a Rosetta server and how to use e

Elastos Foundation 3 Jan 17, 2022