Plush is the templating system that Go both needs and deserves. Powerful, flexible, and extendable, Plush is there to make writing your templates that much easier.
$ go get -u github.com/gobuffalo/plush
Plush allows for the embedding of dynamic code inside of your templates. Take the following example:
<!-- input -->
<p><%= "plush is great" %></p>
<!-- output -->
<p>plush is great</p>By using the <%= %> tags we tell Plush to dynamically render the inner content, in this case the string plush is great, into the template between the <p></p> tags.
If we were to change the example to use <% %> tags instead the inner content will be evaluated and executed, but not injected into the template:
<!-- input -->
<p><% "plush is great" %></p>
<!-- output -->
<p></p>By using the <% %> tags we can create variables (and functions!) inside of templates to use later:
<!-- does not print output -->
<%
let h = {name: "mark"}
let greet = fn(n) {
return "hi " + n
}
%>
<!-- prints output -->
<h1><%= greet(h["name"]) %></h1>html := `<html>
<%= if (names && len(names) > 0) { %>
<ul>
<%= for (n) in names { %>
<li><%= capitalize(n) %></li>
<% } %>
</ul>
<% } else { %>
<h1>Sorry, no names. :(</h1>
<% } %>
</html>`
ctx := plush.NewContext()
ctx.Set("names", []string{"john", "paul", "george", "ringo"})
s, err := plush.Render(html, ctx)
if err != nil {
log.Fatal(err)
}
fmt.Print(s)
// output: <html>
// <ul>
// <li>John</li>
// <li>Paul</li>
// <li>George</li>
// <li>Ringo</li>
// </ul>
// </html>You can add comments like this:
<%# This is a comment %>The basic syntax of if/else statements is as follows:
<%
if (true) {
# do something
} else {
# do something else
}
%>When using if/else statements to control output, remember to use the <%= %> tag to output the result of the statement:
<%= if (true) { %>
<!-- some html here -->
<% } else { %>
<!-- some other html here -->
<% } %>Complex if statements can be built in Plush using "common" operators:
==- checks equality of two expressions!=- checks that the two expressions are not equal~=- checks a string against a regular expression (foo ~= "^fo")<- checks the left expression is less than the right expression<=- checks the left expression is less than or equal to the right expression>- checks the left expression is greater than the right expression>=- checks the left expression is greater than or equal to the right expression&&- requires both the left and right expression to be true||- requires either the left or right expression to be true
<%= if ((1 < 2) && (someFunc() == "hi")) { %>
<!-- some html here -->
<% } else { %>
<!-- some other html here -->
<% } %>Maps in Plush will get translated to the Go type map[string]interface{} when used. Creating, and using maps in Plush is not too different than in JSON:
<% let h = {key: "value", "a number": 1, bool: true} %>Would become the following in Go:
map[string]interface{}{
"key": "value",
"a number": 1,
"bool": true,
}Accessing maps is just like access a JSON object:
<%= h["key"] %>Using maps as options to functions in Plush is incredibly powerful. See the sections on Functions and Helpers to see more examples.
Arrays in Plush will get translated to the Go type []interface{} when used.
<% let a = [1, 2, "three", "four", h] %>[]interface{}{ 1, 2, "three", "four", h }There are three different types that can be looped over: maps, arrays/slices, and iterators. The format for them all looks the same:
<%= for (key, value) in expression { %>
<%= key %> <%= value %>
<% } %>The values inside the () part of the statement are the names you wish to give to the key (or index) and the value of the expression. The expression can be an array, map, or iterator type.
<%= for (i, x) in someArray { %>
<%= i %> <%= x %>
<% } %><%= for (val) in someArray { %>
<%= val %>
<% } %><%= for (k, v) in someMap { %>
<%= k %> <%= v %>
<% } %><%= for (v) in someMap { %>
<%= v %>
<% } %>type ranger struct {
pos int
end int
}
func (r *ranger) Next() interface{} {
if r.pos < r.end {
r.pos++
return r.pos
}
return nil
}
func betweenHelper(a, b int) Iterator {
return &ranger{pos: a, end: b - 1}
}html := `<%= for (v) in between(3,6) { return v } %>`
ctx := plush.NewContext()
ctx.Set("between", betweenHelper)
s, err := plush.Render(html, ctx)
if err != nil {
log.Fatal(err)
}
fmt.Print(s)
// output: 45json- converts the interface to a JSON objectjsEscape- escapes the interface to be JavaScript safehtmlEscape- escapes the interface to be HTML safeupcase- converts the string to upper casedowncase- converts the string to lower casecontentFor- stores a block of HTML to be used latercontentOf- retrieves a block of HTML previously stored withcontentFormarkdown- converts the string from Markdown into HTMLlen- returns the length of the interfacedebug- returns the%+vof the interface wrapped in<pre>tags.inspect- returns the%+vof the interfacerange- interate between, and including two numbersbetween- iterate between, but not including, two numbersuntil- iterate until a number is reachedgroupBy- splits a slice or array intongroupsenv- returns the ENV variable for the specified keytruncate- truncates a string to a specified lengthform- support for the github.com/gobuffalo/tags/form package (Bootstrap version)form_for- support for the github.com/gobuffalo/tags/form package (Bootstrap version) to build a form for a model
Use the contentFor and contentOf helpers to dry up your templates with reusable components.
For example, we can define a snippet that generates a fancy title using contentFor:
<% contentFor("fancy-title") { %>
<h1 class='fancy'><%= title %></h1>
<% } %>
The fancy-title name is how we will invoke this with contentOf elsewhere
in our template:
<%= contentOf("fancy-title", {"title":"Welcome to Plush"}) %>
- The second map argument is optional, for static content just use
<%= contentOf("fancy-title") %>
Rendering this would generate this output:
<h1 class='fancy'>Welcome to Plush</h1>
As you can see, the <%= title %> has been replaced with the Welcome to Plush string.
truncate takes two optional parameters:
size- the maximum length of the returned stringtrail- the string to append at the end of a truncated string, defaults to...
<p><%= truncate("a long string", {"size": 10, "trail": "[more]"})%></p>asciffycamelizecamelize_down_firstcapitalizedasherizehumanizeordinalizeparameterizepluralizepluralize_with_sizesingularizetableizetypeifyunderscore
html := `<p><%= one() %></p>
<p><%= greet("mark")%></p>
<%= can("update") { %>
<p>i can update</p>
<% } %>
<%= can("destroy") { %>
<p>i can destroy</p>
<% } %>
`
ctx := NewContext()
// one() #=> 1
ctx.Set("one", func() int {
return 1
})
// greet("mark") #=> "Hi mark"
ctx.Set("greet", func(s string) string {
return fmt.Sprintf("Hi %s", s)
})
// can("update") #=> returns the block associated with it
// can("adsf") #=> ""
ctx.Set("can", func(s string, help HelperContext) (template.HTML, error) {
if s == "update" {
h, err := help.Block()
return template.HTML(h), err
}
return "", nil
})
s, err := Render(html, ctx)
if err != nil {
log.Fatal(err)
}
fmt.Print(s)
// output: <p>1</p>
// <p>Hi mark</p>
// <p>i can update</p>This package absolutely 100% could not have been written without the help of Thorsten Ball's incredible book, Writing an Interpeter in Go.
Not only did the book make understanding the process of writing lexers, parsers, and asts, but it also provided the basis for the syntax of Plush itself.
If you have yet to read Thorsten's book, I can't recommend it enough. Please go and buy it!