logo Buffalo slack logo
Custom Helpers
Frontend

Custom Helpers#

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
helper
actions/upper.go
templates/up.html
Output
// actions/render.go
r := render.New(render.Options{
  // ...
  Helpers: render.Helpers{
    "upblock": upblock,
  },
  // ...
})

Getting Values From the Context#

actions/render.go
helper
action
template
Output
// actions/render.go
r := render.New(render.Options{
  // ...
  Helpers: render.Helpers{
    "is_logged_in": isLoggedIn,
  },
  // ...
})