logo Buffalo slack logo
Rendering
Frontend

Rendering

The https://github.com/gobuffalo/buffalo/render [godoc] package implements that interface, and has a collection of useful render types already defined. It is recommended that you use this package, but feel free and write your own renderers!

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.

Render Auto

Since 0.11.0

In many cases, you’ll have to provide the same contents in different formats: JSON, XML, HTML… Buffalo provides an easy way to do that using a single statement.

func Beatles(c buffalo.Context) error {
  members := models.Members{}
  // ...
  return c.Render(http.StatusOK, r.Auto(c, members))
}

JSON and XML

When rendering JSON, or XML, using the render.JSON or render.XML, you pass the value that you would like to be marshaled and the appropriate marshaler will encode the value you passed and write it to the response with the correct content/type.

NOTE: If you already have a string that contains JSON or XML, do NOT use these methods as they will attempt to marshal the string into JSON or XML causing strange responses. What you could do instead is write a custom render function as explained in the Custom Rendering section.
// models/user.go

type User struct {
	FirstName string
	LastName  string
	Gender    string
}
func MyHandler(c buffalo.Context) error {
  user := models.User{
		FirstName: "John",
		LastName:  "Smith",
		Gender:    "Male",
	}

  return c.Render(http.StatusOK, r.JSON(user))
}
// output
{
  "FirstName": "John",
  "LastName": "Smith",
  "Gender": "Male"
}
func MyHandler(c buffalo.Context) error {
  user := models.User{
		FirstName: "John",
		LastName:  "Smith",
		Gender:    "Male",
	}

  return c.Render(http.StatusOK, r.XML(user))
}
<!-- output -->
<User>
  <FirstName>John</FirstName>
  <LastName>Smith</LastName>
  <Gender>Male</Gender>
</User>

Markdown

Files passed into the render.HTML or render.Template methods, that have an extension of .plush.md, will be converted from Markdown (using GitHub flavored Markdown) to HTML before being run through the templating engine. This makes for incredibly easy templating for simpler pages.

<!-- beatles.plush.md -->

# The Beatles

<%= for (name) in names { %>
* <%= name %>
<% } %>
// actions/beatles.go

func Beatles(c buffalo.Context) error {
  c.Set("names", []string{"John", "Paul", "George", "Ringo"})

  return c.Render(http.StatusOK, r.HTML("beatles.plush.md"))
}
<!-- output -->
<h1>The Beatles</h1>

<ul>
  <li><p>John</p></li>
  <li><p>Paul</p></li>
  <li><p>George</p></li>
  <li><p>Ringo</p></li>
</ul>

JavaScript

Since 0.10.0

The render package has a new implementation of render.Renderer, render.JavaScript.

This means inside of an action you can do the following:

func HomeHandler(c buffalo.Context) error {
  return c.Render(http.StatusOK, r.JavaScript("index.js"))
}

The render.Options type now has a new attribute, JavaScriptLayout. This new option is similar to the HTMLLayout option in that it will wrap *.js files inside of another *.js.

The new JavaScript renderer also has it’s own implementation of the partial function. This new implementation behaves almost the same as the original implementation, but is smart enough to know that if you are rendering an *.html file inside of a *.js file that it will need to be escaped properly, and so it does it for you.

$("#new-goal-form").replaceWith("<%= partial("goals/new.html") %>");

Automatic Extensions

Since 0.10.2

You can use HTML, Javascript and Markdown renderers without specifying the file extension:

// actions/beatles.go
func Beatles(c buffalo.Context) error {
  c.Set("names", []string{"John", "Paul", "George", "Ringo"})
  // Render beatles.html
  return c.Render(http.StatusOK, r.HTML("beatles"))
}
This works with partials too.

Download files

The r.Download method allows you to download files in your application easily.

func DownloadHandler(c buffalo.Context) error {
	// ...
	f, err := os.Open("your/path/file_name.extension")
	if err != nil {
		return err
	}

	return c.Render(http.StatusOK, r.Download(c, "file_name.extension", f))
}

Custom Rendering

For another type of rendering, the r.Func method allows you to pass in a content type and a function to render your data to the provided io.Writer, which is commonly, the HTTP response, in particular, a *buffalo.Response.

func MyHandler(c buffalo.Context) error {
  return c.Render(http.StatusOK, r.Func("application/csv", csvWriter))
}

func csvWriter(w io.Writer, d render.Data) error {
  cw := csv.NewWriter(w)
  if err := cw.Write([]string{"a", "b", "c"}); err != nil {
    return errors.WithStack(err)
  }
  cw.Flush()
  return nil
}

For smaller, or one off situations, using an anonymous function can be even easier. In this example you can see how to use an anonymous function to render a string that already contains JSON.

var myJSONString string
return c.Render(http.StatusOK, r.Func("application/json", func(w io.Writer, d render.Data) error {
  _, err := w.Write([]byte(myJSONString))
  return err
}))

Renderer Interface

In order for a renderer to be able to be used with Context#Render it must implement the following interface:

// Renderer interface that must be satisified to be used with
// buffalo.Context.Render
type Renderer interface {
  ContentType() string
  Render(io.Writer, Data) error
}

// Data type to be provided to the Render function on the
// Renderer interface.

type Data map[string]interface{}

The https://github.com/gobuffalo/buffalo/render [godoc] package implements that interface, and has a collection of useful render types already defined. It is recommended that you use this package, but feel free and write your own renderers!