Helpers

This document only applies when using https://github.com/gobuffalo/buffalo/render.
Please see github.com/gobuffalo/plush for more details on the underlying templating package.

Builtin Helpers

Listed below are a few of the helpers that ship with Plush. Please see the Plush documentation for more information on its helpers.

  • json - converts the interface to a JSON object
  • jsEscape - escapes the interface to be JavaScript safe
  • htmlEscape - escapes the interface to be HTML safe
  • upcase - converts the string to upper case
  • downcase - converts the string to lower case
  • contentFor - stores a block of HTML to be used later
  • contentOf - retrieves a block of HTML previously stored with contentFor
  • markdown - converts the string from Markdown into HTML
  • len - returns the length of the interface
  • debug - returns the %+v of the interface wrapped in %lt;pre%gt; tags.
  • inspect - returns the %+v of the interface
  • range - interate between, and including two numbers
  • between - iterate between, but not including, two numbers
  • until - iterate until a number is reached
  • groupBy - splits a slice or array into n groups
  • env - returns the ENV variable for the specified key
  • truncate - truncates a string to a specified length
  • raw - converts a string to template.HTML
  • form - 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

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

Path Helpers

Buffalo will generate path helpers for all of the routes you add to the App. The easiest way to see what all of the generated path helpers are and what they point to is to run buffalo routes. This will print out a list that looks something like this:

$ buffalo routes
METHOD | PATH                         | ALIASES | NAME              | HANDLER
------ | ----                         | ------- | ----              | -------
GET    | /                            |         | rootPath          | github.com/gobuffalo/coke/actions.HomeHandler
GET    | /about                       |         | aboutPath         | github.com/gobuffalo/coke/actions.AboutHandler
GET    | /drinks                      |         | drinksPath        | github.com/gobuffalo/coke/actions.DrinksResource.List
POST   | /drinks                      |         | drinksPath        | github.com/gobuffalo/coke/actions.DrinksResource.Create
GET    | /drinks/new                  |         | newDrinksPath     | github.com/gobuffalo/coke/actions.DrinksResource.New
GET    | /drinks/{drink_id}           |         | drinkPath         | github.com/gobuffalo/coke/actions.DrinksResource.Show
PUT    | /drinks/{drink_id}           |         | drinkPath         | github.com/gobuffalo/coke/actions.DrinksResource.Update
DELETE | /drinks/{drink_id}           |         | drinkPath         | github.com/gobuffalo/coke/actions.DrinksResource.Destroy
GET    | /drinks/{drink_id}/edit      |         | editDrinkPath     | github.com/gobuffalo/coke/actions.DrinksResource.Edit
GET    | /api/v1/users                |         | apiV1UsersPath    | github.com/gobuffalo/coke/actions.UsersResource.List
POST   | /api/v1/users                |         | apiV1UsersPath    | github.com/gobuffalo/coke/actions.UsersResource.Create
GET    | /api/v1/users/new            |         | newApiV1UsersPath | github.com/gobuffalo/coke/actions.UsersResource.New
GET    | /api/v1/users/{user_id}      |         | apiV1UserPath     | github.com/gobuffalo/coke/actions.UsersResource.Show
PUT    | /api/v1/users/{user_id}      |         | apiV1UserPath     | github.com/gobuffalo/coke/actions.UsersResource.Update
DELETE | /api/v1/users/{user_id}      |         | apiV1UserPath     | github.com/gobuffalo/coke/actions.UsersResource.Destroy
GET    | /api/v1/users/{user_id}/edit |         | editApiV1UserPath | github.com/gobuffalo/coke/actions.UsersResource.Edit

Going down this list we start with the path *NAME*d rootPath which represents PATH / or the root route of the server and as a bonus with all of these we can even see exactly which HANDLER code is being run for this METHOD+PATH combination.

Next we have a standard app.GET("/about", AboutHandler) which generates to aboutPath.

Then we use a resource app.Resource("/drinks", DrinksResource{}) which generates a path for each of our standard actions, and for each of those a helper to be used in templates. Those that take a parameter can be used like this <%= drinkPath({drink_id: drink.ID}) %>. All helpers take a map[string]interface{} that is used to fill-in parameters.

Finally, when we use a group we can see that this changes the generated helpers. Here is the routing for those last paths:

api := app.Group("/api/v1")
api.Resource("/users", UsersResource{})

Note that the helpers are generated to match the generated paths. It is possible to override the path names in the App.Routes, but it is highly advised that you find a different way to your goal than this. Slack is always open to these conversations.

Content Helpers

Plush ships with two complementary helpers that let you create dynamic HTML snippets and re-use them later in the template.

The contentFor and contentOf Helpers

The contentFor helper takes a block of HTML and holds on to it using the given name. This block can then be used elsewhere in a template file, even when the content defined in a contentFor block is in a yielded-to template and is expanded into a contentOf block in a yield-calling template. The default templates/application.html calls yield like this.

Take the following example: suppose we have a templates/application.html that fully specifies everything in <head> and the outermost contents of <body>. This template yields to other subtemplates, like templates/users/show.html, to fill <body>. However, if we want to add or override something in the <head> from a subtemplate, we'll need to use contentFor. In this example, we'll add a way for subtemplates to add an extra chunk of CSS to the <head> of application.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>My Site</title>
    <%= stylesheetTag("application.css") %>
    <%= contentOf("extraStyle") %>
  </head>
  <body>
    <div class="container">
      <%= partial("flash.html") %>
      <%= yield %>
    </div>
  </body>
</html>

As it turns out, our users/index.html template could use a little page-wide styling instead of adding a bunch of style attributes to different elements, so it defines a block of CSS that doesn't show up anywhere inside the template:

<div class="page-header">
  <h1>Users</h1>
</div>
<table class="table table-striped">
  <thead>
    <th>Username</th> <th>Password</th> <th>Email</th> <th>Admin?</th> <th> </th>
  </thead>
  <tbody>
    <%= for (user) in users { %>
      <!-- … -->
    <% } %>
  </tbody>
</table>

<% contentFor("extraStyle") { %>
  <style>
    .online {
      color: limegreen;
      background: black;
    }

    .offline {
      color: lightgray;
      background: darkgray;
    }
  </style>
<% } %>

The styling for the online and offline classes then appears at the end of <head> in /users. In other pages, nothing is added.

Of course, if you'd rather do extensive processing on what goes into a chunk that goes on a webpage, you may want to do your processing in Go code instead of in templates. In that case, call, say, c.Set("moonPhase", mp) where c is a buffalo.Context in a function in an action like in actions/users.go, and mp is some string or object. Then, in your templates, refer to <%= moonPhase %> to display your expertly-calculated phase of the moon.