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
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.
// 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
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
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"))
}
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!