Frontend
Custom Helpers#
This document only applies when using https://github.com/gobuffalo/buffalo/tree/main/render.
Please see github.com/gobuffalo/plush for more details on the underlying templating package.
No templating package would be complete without allowing for you to build your own, custom, helper functions.
Registering Helpers#
Helper functions can be registered in two different places, depending on how they are to be used.
Global Helpers#
Most helpers will be global helpers, meaning that they should be included in every template. The types of
helpers can can be set in actions/render.go
:
func init() {
r = render.New(render.Options{
// ...
Helpers: render.Helpers{
"myHelper": func() string {
return "hello"
},
},
// ...
})
}
Per Request Helpers#
Other helpers, that are specific to a certain request can be added to the buffalo.Context
for that request.
func HomeHandler(c buffalo.Context) error {
// ...
c.Set("myHelper", func() string {
return "hello"
})
// ...
}
Return Values#
Plush allows you to return any values you would like from a helper function. This guide will focus on helpers that are designed to generate “output”.
When returning multiple values from a function, the first value will be the one used for rendering in the template.
If the last return value is an error
, Plush will handle that error.
string
#
Return just a string
. The string
will be HTML escaped, and deemed “not”-safe.
func() string {
return ""
}
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("")
}
Input Values#
Custom helper functions can take any type, and any number of arguments. You can even use variadic functions. There is an optional last argument, plush.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…
Simple Helpers#
r := render.New(render.Options{
// ...
Helpers: render.Helpers{
"greet": func(name string) string {
return fmt.Sprintf("Hi %s!", name)
},
},
// ...
})
The greet
function is now available to all templates that use that render.Engine
.
// actions/greet.go
func Greeter(c buffalo.Context) error {
c.Set("name", "Mark")
return c.Render(200, r.String("<h1><%= greet(name) %></h1>"))
}
// output
<h1>Hi Mark!</h1>
Block Helpers#
Like the if
or for
statements, 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 plush.HelperContext
as the last argument to your helper function. This will give you access to the block associated with that call.
// actions/render.go
r := render.New(render.Options{
// ...
Helpers: render.Helpers{
"upblock": upblock,
},
// ...
})
Getting Values From the Context#
// actions/render.go
r := render.New(render.Options{
// ...
Helpers: render.Helpers{
"is_logged_in": isLoggedIn,
},
// ...
})