gobuffalo/plushPublic

NotificationsYou must be signed in to change notification settings
Fork58
Star983

The powerful template system that Go needs

License

MIT license

983 stars 58 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 436 Commits
.github/workflows		.github/workflows
ast		ast
helpers		helpers
lexer		lexer
parser		parser
templatecache/inmemory		templatecache/inmemory
token		token
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
comments_test.go		comments_test.go
compiler.go		compiler.go
context.go		context.go
context_test.go		context_test.go
error_test.go		error_test.go
escape_test.go		escape_test.go
example_test.go		example_test.go
for_test.go		for_test.go
functions_test.go		functions_test.go
generate_cache_key.go		generate_cache_key.go
generate_cache_key_test.go		generate_cache_key_test.go
go.mod		go.mod
go.sum		go.sum
hashes_test.go		hashes_test.go
helper_context.go		helper_context.go
helpers.go		helpers.go
helpers_test.go		helpers_test.go
if_test.go		if_test.go
intern.go		intern.go
intern_test.go		intern_test.go
iterators.go		iterators.go
iterators_test.go		iterators_test.go
line_number_test.go		line_number_test.go
math_test.go		math_test.go
numbers_test.go		numbers_test.go
objects.go		objects.go
partial_helper.go		partial_helper.go
partial_helper_test.go		partial_helper_test.go
plush.go		plush.go
plush_test.go		plush_test.go
punch_hole.go		punch_hole.go
punch_hole_test.go		punch_hole_test.go
quotes_test.go		quotes_test.go
return_exit_test.go		return_exit_test.go
script_test.go		script_test.go
struct_test.go		struct_test.go
symbol_table.go		symbol_table.go
symbol_table_test.go		symbol_table_test.go
template.go		template.go
template_cache.go		template_cache.go
template_test.go		template_test.go
time_test.go		time_test.go
user_function.go		user_function.go
variables_test.go		variables_test.go
variadic_test.go		variadic_test.go

Repository files navigation

Plush

Plush is the templating system thatGo both needsand deserves. Powerful, flexible, and extendable, Plush is there to make writing your templates that much easier.

Introduction Video

Installation

$ go get -u github.com/gobuffalo/plush

Usage

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>

Controlling Output

By using the<%= %> tags we tell Plush to dynamically render the inner content, in this case the stringplush 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 --><%leth={name:"mark"}letgreet=fn(n){return"hi " +n}%><!-- prints output --><h1><%=greet(h["name"])%></h1>

Full Example:

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)iferr!=nil {log.Fatal(err)}fmt.Print(s)// output: <html>// <ul>// <li>John</li>// <li>Paul</li>// <li>George</li>// <li>Ringo</li>// </ul>// </html>

Comments

You can add comments like this:

<%# This is a comment%>

You can also add line comments within a code section

<%# this is a commentnot_a_comment()%>

If/Else Statements

The basic syntax ofif/else if/else statements is as follows:

<%if (true) {  # do something} else if (false) {  # do something} else {  # do something else}%>

When usingif/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 --><%}%>

Operators

Complexif 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 leftand right expression to be true
|| - requires either the leftor right expression to be true

Grouped Expressions

<%= if ((1 < 2) && (someFunc() == "hi")) {%><!-- some html here --><%}else{%><!-- some other html here --><%}%>

Maps

Maps in Plush will get translated to the Go typemap[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

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 }

Arrays in plush can be appended using the following format:

<% let a = [1, 2, "three", "four", h]%><% a = a + "hello world"%>

If the array passed to plush is not of type[]interface{} and an attempt is made to append a value with a data type that does not match the underlying array type, an error will be returned.

For Loops

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%><% }%>

You can alsocontinue to the next iteration of the loop:

for (i,v) in [1, 2, 3,4,5,6,7,8,9,10] {  if (i> 0) {    continue  }  return v}

You can terminate the for loop withbreak:

for (i,v) in [1, 2, 3,4,5,6,7,8,9,10] {  if (i> 5) {    break  }  return v}

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. Theexpression can be an array, map, or iterator type.

Arrays

Using Index and Value

<%= for (i, x) in someArray {%><%= i%><%= x%><% }%>

Using Just the Value

<%= for (val) in someArray {%><%= val%><% }%>

Maps

Using Index and Value

<%= for (k, v) in someMap {%><%= k%><%= v%><% }%>

Using Just the Value

<%= for (v) in someMap {%><%= v%><% }%>

Iterators

typerangerstruct {posintendint}func (r*ranger)Next()interface{} {ifr.pos<r.end {r.pos++returnr.pos}returnnil}funcbetweenHelper(a,bint)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)iferr!=nil {log.Fatal(err)}fmt.Print(s)// output: 45

Default helpers

Plush ships with a comprehensive list of helpers to make your life easier. For more info check the helpers package.

Custom Helpers

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() #=> 1ctx.Set("one",func()int {return1})// greet("mark") #=> "Hi mark"ctx.Set("greet",func(sstring)string {returnfmt.Sprintf("Hi %s",s)})// can("update") #=> returns the block associated with it// can("adsf") #=> ""ctx.Set("can",func(sstring,helpHelperContext) (template.HTML,error) {ifs=="update" {h,err:=help.Block()returntemplate.HTML(h),err  }return"",nil})s,err:=Render(html,ctx)iferr!=nil {log.Fatal(err)}fmt.Print(s)// output: <p>1</p>// <p>Hi mark</p>// <p>i can update</p>

Special Thanks

This package absolutely 100% could not have been written without the help of Thorsten Ball's incredible book,Writing an Interpreter 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!