Resources

Often web applications need to build very similar "CRUD" end-points. To help reduce the amount of thought and complexity involved in this, Buffalo supports the concept of a "Resource".

The github.com/gobuffalo/buffalo#Resource interface allows Buffalo to map common routes and respond to common requests.

since v0.14.1

type Resource interface {
  List(Context) error
  Show(Context) error
  Create(Context) error
  Update(Context) error
  Destroy(Context) error
}

The github.com/gobuffalo/buffalo#Resource interface was made smaller in release v0.14.1.

since v0.5.0

type Resource interface {
  List(Context) error
  Show(Context) error
  New(Context) error
  Create(Context) error
  Edit(Context) error
  Update(Context) error
  Destroy(Context) error
}

Using Resources

After implementing the necessary methods on the github.com/gobuffalo/buffalo#Resource interface, the resource can then be mapped to the application using the github.com/gobuffalo/buffalo#App.Resource method.

type UsersResource struct{ }

func (u UsersResource) List(c buffalo.Context) error {
  // do work
}

func (u UsersResource) Show(c buffalo.Context) error {
  // do work
}

func (u UsersResource) Create(c buffalo.Context) error {
  // do work
}

func (u UsersResource) Update(c buffalo.Context) error {
  // do work
}

func (u UsersResource) Destroy(c buffalo.Context) error {
  // do work
}

a.Resource("/users", UsersResource{})

The above code example would be the equivalent of the following:

ur := UsersResource{}
a.GET("/users", ur.List)
a.GET("/users/{user_id}", ur.Show)
a.POST("/users", ur.Create)
a.PUT("/users/{user_id}", ur.Update)
a.DELETE("/users/{user_id}", ur.Destroy)

It will produce a routing table ($ buffalo routes) that looks similar to:

METHOD | PATH                   | NAME         | HANDLER
------ | ----                   | ----         | -------
GET    | /users/                | usersPath    | coke/actions.UsersResource.List
POST   | /users/                | usersPath    | coke/actions.UsersResource.Create
GET    | /users/{user_id}/      | userPath     | coke/actions.UsersResource.Show
PUT    | /users/{user_id}/      | userPath     | coke/actions.UsersResource.Update
DELETE | /users/{user_id}/      | userPath     | coke/actions.UsersResource.Destroy

Optional Resource Methods

since v0.14.1

In v0.14.1 the github.com/gobuffalo/buffalo#Resource was made smaller with the following methods now being optional:

New(Context) error
Edit(Context) error

When implemented the New and Edit methods will add the following to the routing table:

METHOD | PATH                   | ALIASES | NAME         | HANDLER
------ | ----                   | ------- | ----         | -------
GET    | /users/new/            |         | newUsersPath | coke/actions.UsersResource.New
GET    | /users/{user_id}/edit/ |         | editUserPath | coke/actions.UsersResource.Edit

Generating Resources

The buffalo generate resource command will generate the necessary models, migrations, Go code, and HTML to CRUD the resource.

When running the generator in an API application Buffalo will generate code to meet the github.com/gobuffalo/buffalo#Resource interface.

type Resource interface {
  List(Context) error
  Show(Context) error
  Create(Context) error
  Update(Context) error
  Destroy(Context) error
}

When running the generator in a Web application Buffalo will generate code to the meet the github.com/gobuffalo/buffalo#Resource interface, as well as the optional New and Edit methods.

type Resource interface {
  List(Context) error
  Show(Context) error
  New(Context) error
  Create(Context) error
  Edit(Context) error
  Update(Context) error
  Destroy(Context) error
}

Example Resource Generation

In this example Buffalo will generate the code needed to CRUD a resource named widget (Go: Widget) that has the following attributes:

  • title - Model Attribute: Title; Go Type: string; DB Type: varchar; Form Type: text
  • description - Model Attribute: Description; Go Type nulls.String; DB Type: varchar (nullable); Form Type: textarea
$ buffalo generate resource widget title description:nulls.Text

./actions

    // actions/app.go
    package actions
    
    import (
        "github.com/gobuffalo/buffalo"
        "github.com/gobuffalo/envy"
        forcessl "github.com/gobuffalo/mw-forcessl"
        paramlogger "github.com/gobuffalo/mw-paramlogger"
        "github.com/unrolled/secure"
    
        "github.com/gobuffalo/buffalo-pop/pop/popmw"
        csrf "github.com/gobuffalo/mw-csrf"
        i18n "github.com/gobuffalo/mw-i18n"
        "github.com/gobuffalo/packr"
        "github.com/markbates/coke/models"
    )
    
    // ENV is used to help switch settings based on where the
    // application is being run. Default is "development".
    var ENV = envy.Get("GO_ENV", "development")
    var app *buffalo.App
    var T *i18n.Translator
    
    // App is where all routes and middleware for buffalo
    // should be defined. This is the nerve center of your
    // application.
    //
    // Routing, middleware, groups, etc... are declared TOP -> DOWN.
    // This means if you add a middleware to `app` *after* declaring a
    // group, that group will NOT have that new middleware. The same
    // is true of resource declarations as well.
    //
    // It also means that routes are checked in the order they are declared.
    // `ServeFiles` is a CATCH-ALL route, so it should always be
    // placed last in the route declarations, as it will prevent routes
    // declared after it to never be called.
    func App() *buffalo.App {
        if app == nil {
            app = buffalo.New(buffalo.Options{
                Env:         ENV,
                SessionName: "_coke_session",
            })
    
            // Automatically redirect to SSL
            app.Use(forceSSL())
    
            // Log request parameters (filters apply).
            app.Use(paramlogger.ParameterLogger)
    
            // Protect against CSRF attacks. https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
            // Remove to disable this.
            app.Use(csrf.New)
    
            // Wraps each request in a transaction.
            //  c.Value("tx").(*pop.Connection)
            // Remove to disable this.
            app.Use(popmw.Transaction(models.DB))
    
            // Setup and use translations:
            app.Use(translations())
    
            app.GET("/", HomeHandler)
    
            app.Resource("/widgets", WidgetsResource{})
            app.ServeFiles("/", assetsBox) // serve files from the public directory
        }
    
        return app
    }
    
    // translations will load locale files, set up the translator `actions.T`,
    // and will return a middleware to use to load the correct locale for each
    // request.
    // for more information: https://gobuffalo.io/en/docs/localization
    func translations() buffalo.MiddlewareFunc {
        var err error
        if T, err = i18n.New(packr.NewBox("../locales"), "en-US"); err != nil {
            app.Stop(err)
        }
        return T.Middleware()
    }
    
    // forceSSL will return a middleware that will redirect an incoming request
    // if it is not HTTPS. "http://example.com" => "https://example.com".
    // This middleware does **not** enable SSL. for your application. To do that
    // we recommend using a proxy: https://gobuffalo.io/en/docs/proxy
    // for more information: https://github.com/unrolled/secure/
    func forceSSL() buffalo.MiddlewareFunc {
        return forcessl.Middleware(secure.Options{
            SSLRedirect:     ENV == "production",
            SSLProxyHeaders: map[string]string{"X-Forwarded-Proto": "https"},
        })
    }
    
    
    // actions/widgets.go
    package actions
    
    import (
        "github.com/gobuffalo/buffalo"
        "github.com/gobuffalo/pop"
        "github.com/markbates/coke/models"
        "github.com/pkg/errors"
    )
    
    // This file is generated by Buffalo. It offers a basic structure for
    // adding, editing and deleting a page. If your model is more
    // complex or you need more than the basic implementation you need to
    // edit this file.
    
    // Following naming logic is implemented in Buffalo:
    // Model: Singular (Widget)
    // DB Table: Plural (widgets)
    // Resource: Plural (Widgets)
    // Path: Plural (/widgets)
    // View Template Folder: Plural (/templates/widgets/)
    
    // WidgetsResource is the resource for the Widget model
    type WidgetsResource struct {
        buffalo.Resource
    }
    
    // List gets all Widgets. This function is mapped to the path
    // GET /widgets
    func (v WidgetsResource) List(c buffalo.Context) error {
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        widgets := &models.Widgets{}
    
        // Paginate results. Params "page" and "per_page" control pagination.
        // Default values are "page=1" and "per_page=20".
        q := tx.PaginateFromParams(c.Params())
    
        // Retrieve all Widgets from the DB
        if err := q.All(widgets); err != nil {
            return errors.WithStack(err)
        }
    
        // Add the paginator to the context so it can be used in the template.
        c.Set("pagination", q.Paginator)
    
        return c.Render(200, r.Auto(c, widgets))
    }
    
    // Show gets the data for one Widget. This function is mapped to
    // the path GET /widgets/{widget_id}
    func (v WidgetsResource) Show(c buffalo.Context) error {
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        // Allocate an empty Widget
        widget := &models.Widget{}
    
        // To find the Widget the parameter widget_id is used.
        if err := tx.Find(widget, c.Param("widget_id")); err != nil {
            return c.Error(404, err)
        }
    
        return c.Render(200, r.Auto(c, widget))
    }
    
    // New renders the form for creating a new Widget.
    // This function is mapped to the path GET /widgets/new
    func (v WidgetsResource) New(c buffalo.Context) error {
        return c.Render(200, r.Auto(c, &models.Widget{}))
    }
    
    // Create adds a Widget to the DB. This function is mapped to the
    // path POST /widgets
    func (v WidgetsResource) Create(c buffalo.Context) error {
        // Allocate an empty Widget
        widget := &models.Widget{}
    
        // Bind widget to the html form elements
        if err := c.Bind(widget); err != nil {
            return errors.WithStack(err)
        }
    
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        // Validate the data from the html form
        verrs, err := tx.ValidateAndCreate(widget)
        if err != nil {
            return errors.WithStack(err)
        }
    
        if verrs.HasAny() {
            // Make the errors available inside the html template
            c.Set("errors", verrs)
    
            // Render again the new.html template that the user can
            // correct the input.
            return c.Render(422, r.Auto(c, widget))
        }
    
        // If there are no errors set a success message
        c.Flash().Add("success", "Widget was created successfully")
    
        // and redirect to the widgets index page
        return c.Render(201, r.Auto(c, widget))
    }
    
    // Edit renders a edit form for a Widget. This function is
    // mapped to the path GET /widgets/{widget_id}/edit
    func (v WidgetsResource) Edit(c buffalo.Context) error {
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        // Allocate an empty Widget
        widget := &models.Widget{}
    
        if err := tx.Find(widget, c.Param("widget_id")); err != nil {
            return c.Error(404, err)
        }
    
        return c.Render(200, r.Auto(c, widget))
    }
    
    // Update changes a Widget in the DB. This function is mapped to
    // the path PUT /widgets/{widget_id}
    func (v WidgetsResource) Update(c buffalo.Context) error {
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        // Allocate an empty Widget
        widget := &models.Widget{}
    
        if err := tx.Find(widget, c.Param("widget_id")); err != nil {
            return c.Error(404, err)
        }
    
        // Bind Widget to the html form elements
        if err := c.Bind(widget); err != nil {
            return errors.WithStack(err)
        }
    
        verrs, err := tx.ValidateAndUpdate(widget)
        if err != nil {
            return errors.WithStack(err)
        }
    
        if verrs.HasAny() {
            // Make the errors available inside the html template
            c.Set("errors", verrs)
    
            // Render again the edit.html template that the user can
            // correct the input.
            return c.Render(422, r.Auto(c, widget))
        }
    
        // If there are no errors set a success message
        c.Flash().Add("success", "Widget was updated successfully")
    
        // and redirect to the widgets index page
        return c.Render(200, r.Auto(c, widget))
    }
    
    // Destroy deletes a Widget from the DB. This function is mapped
    // to the path DELETE /widgets/{widget_id}
    func (v WidgetsResource) Destroy(c buffalo.Context) error {
        // Get the DB connection from the context
        tx, ok := c.Value("tx").(*pop.Connection)
        if !ok {
            return errors.WithStack(errors.New("no transaction found"))
        }
    
        // Allocate an empty Widget
        widget := &models.Widget{}
    
        // To find the Widget the parameter widget_id is used.
        if err := tx.Find(widget, c.Param("widget_id")); err != nil {
            return c.Error(404, err)
        }
    
        if err := tx.Destroy(widget); err != nil {
            return errors.WithStack(err)
        }
    
        // If there are no errors set a flash message
        c.Flash().Add("success", "Widget was destroyed successfully")
    
        // Redirect to the widgets index page
        return c.Render(200, r.Auto(c, widget))
    }
    
    
    // actions/widgets_test.go
    package actions
    
    func (as *ActionSuite) Test_WidgetsResource_List() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_Show() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_New() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_Create() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_Edit() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_Update() {
        as.Fail("Not Implemented!")
    }
    
    func (as *ActionSuite) Test_WidgetsResource_Destroy() {
        as.Fail("Not Implemented!")
    }
    
    

    ./locales

      // locales/widgets.en-us.yaml
      - id: "widget.created.success"
        translation: "Widget was successfully created."
      - id: "widget.updated.success"
        translation: "Widget was successfully updated."
      - id: "widget.destroyed.success"
        translation: "Widget was successfully destroyed."
      
      

      ./migrations

        // migrations/20181005153028_create_widgets.down.fizz
        drop_table("widgets")
        
        // migrations/20181005153028_create_widgets.up.fizz
        create_table("widgets") {
            t.Column("id", "uuid", {"primary": true})
            t.Column("title", "string", {})
            t.Column("description", "text", {"null": true})
        }
        

        ./models

          // models/models.go
          package models
          
          import (
              "log"
          
              "github.com/gobuffalo/envy"
              "github.com/gobuffalo/pop"
          )
          
          // DB is a connection to your database to be used
          // throughout your application.
          var DB *pop.Connection
          
          func init() {
              var err error
              env := envy.Get("GO_ENV", "development")
              DB, err = pop.Connect(env)
              if err != nil {
                  log.Fatal(err)
              }
              pop.Debug = env == "development"
          }
          
          
          // models/models_test.go
          package models_test
          
          import (
              "testing"
          
              "github.com/gobuffalo/packr"
              "github.com/gobuffalo/suite"
          )
          
          type ModelSuite struct {
              *suite.Model
          }
          
          func Test_ModelSuite(t *testing.T) {
              model, err := suite.NewModelWithFixtures(packr.NewBox("../fixtures"))
              if err != nil {
                  t.Fatal(err)
              }
          
              as := &ModelSuite{
                  Model: model,
              }
              suite.Run(t, as)
          }
          
          
          // models/widget.go
          package models
          
          import (
              "encoding/json"
              "time"
          
              "github.com/gobuffalo/pop"
              "github.com/gobuffalo/pop/nulls"
              "github.com/gobuffalo/uuid"
              "github.com/gobuffalo/validate"
              "github.com/gobuffalo/validate/validators"
          )
          
          type Widget struct {
              ID          uuid.UUID    `json:"id" db:"id"`
              CreatedAt   time.Time    `json:"created_at" db:"created_at"`
              UpdatedAt   time.Time    `json:"updated_at" db:"updated_at"`
              Title       string       `json:"title" db:"title"`
              Description nulls.String `json:"description" db:"description"`
          }
          
          // String is not required by pop and may be deleted
          func (w Widget) String() string {
              jw, _ := json.Marshal(w)
              return string(jw)
          }
          
          // Widgets is not required by pop and may be deleted
          type Widgets []Widget
          
          // String is not required by pop and may be deleted
          func (w Widgets) String() string {
              jw, _ := json.Marshal(w)
              return string(jw)
          }
          
          // Validate gets run every time you call a "pop.Validate*" (pop.ValidateAndSave, pop.ValidateAndCreate, pop.ValidateAndUpdate) method.
          // This method is not required and may be deleted.
          func (w *Widget) Validate(tx *pop.Connection) (*validate.Errors, error) {
              return validate.Validate(
                  &validators.StringIsPresent{Field: w.Title, Name: "Title"},
              ), nil
          }
          
          // ValidateCreate gets run every time you call "pop.ValidateAndCreate" method.
          // This method is not required and may be deleted.
          func (w *Widget) ValidateCreate(tx *pop.Connection) (*validate.Errors, error) {
              return validate.NewErrors(), nil
          }
          
          // ValidateUpdate gets run every time you call "pop.ValidateAndUpdate" method.
          // This method is not required and may be deleted.
          func (w *Widget) ValidateUpdate(tx *pop.Connection) (*validate.Errors, error) {
              return validate.NewErrors(), nil
          }
          
          
          // models/widget_test.go
          package models
          
          import "testing"
          
          func Test_Widget(t *testing.T) {
              t.Fatal("This test needs to be implemented!")
          }
          
          

          ./templates

            // templates/widgets/_form.html
            <%= f.InputTag("Title") %>
            <%= f.TextAreaTag("Description", {rows: 10}) %>
            Save
            
            
            // templates/widgets/edit.html
            
            
            

            <%= form_for(widget, {action: widgetPath({ widget_id: widget.ID }), method: "PUT"}) { %> <%= partial("widgets/form.html") %>

            // templates/widgets/index.html
            
            
            
            
                <%= for (widget) in widgets { %>
                  
                <% } %>
              
            Title  
            <%= widget.Title %>
            <%= paginator(pagination) %>

            Destroying Resources

            You can remove files generated by this generator by running:

            $ buffalo destroy resource users
            

            This command will ask you which files you want to remove, you can either answer each of the questions with y/n or you can pass the -y flag to the command like:

            $ buffalo destroy resource users -y
            

            Or in short form:

            $ buffalo d r users -y
            

            Nesting resources

            To simplify creating resource hierarchies, Buffalo supports nesting resources.

            type UsersResource struct {
              buffalo.Resource
            }
            
            type ImagesResource struct {
              buffalo.Resource
            }
            
            u := a.Resource("/users", UsersResource{})
            u.Resource("/images", ImagesResource{})
            

            This results in the following routes:

            $ buffalo routes
            METHOD | PATH                                    | ALIASES | NAME              | HANDLER
            ------ | ----                                    | ------- | ----              | -------
            GET    | /                                       |         | rootPath          | github.com/gobuffalo/coke/actions.HomeHandler
            GET    | /users                                  |         | usersPath         | github.com/gobuffalo/coke/actions.UsersResource.List
            POST   | /users                                  |         | usersPath         | github.com/gobuffalo/coke/actions.UsersResource.Create
            GET    | /users/new                              |         | newUsersPath      | github.com/gobuffalo/coke/actions.UsersResource.New
            GET    | /users/{user_id}                        |         | userPath          | github.com/gobuffalo/coke/actions.UsersResource.Show
            PUT    | /users/{user_id}                        |         | userPath          | github.com/gobuffalo/coke/actions.UsersResource.Update
            DELETE | /users/{user_id}                        |         | userPath          | github.com/gobuffalo/coke/actions.UsersResource.Destroy
            GET    | /users/{user_id}/edit                   |         | editUserPath      | github.com/gobuffalo/coke/actions.UsersResource.Edit
            GET    | /users/{user_id}/images                 |         | userImagesPath    | github.com/gobuffalo/coke/actions.ImagesResource.List
            POST   | /users/{user_id}/images                 |         | userImagesPath    | github.com/gobuffalo/coke/actions.ImagesResource.Create
            GET    | /users/{user_id}/images/new             |         | newUserImagesPath | github.com/gobuffalo/coke/actions.ImagesResource.New
            GET    | /users/{user_id}/images/{image_id}      |         | userImagePath     | github.com/gobuffalo/coke/actions.ImagesResource.Show
            PUT    | /users/{user_id}/images/{image_id}      |         | userImagePath     | github.com/gobuffalo/coke/actions.ImagesResource.Update
            DELETE | /users/{user_id}/images/{image_id}      |         | userImagePath     | github.com/gobuffalo/coke/actions.ImagesResource.Destroy
            GET    | /users/{user_id}/images/{image_id}/edit |         | editUserImagePath | github.com/gobuffalo/coke/actions.ImagesResource.Edit
            

            buffalo.BaseResource

            When a resource is generated it has buffalo.BaseResource embedded into it.

            type Widget struct {
              buffalo.BaseResource
            }
            

            The buffalo.BaseResource has basic implementations for all of the methods required by buffalo.Resource. These methods all 404.

            // Edit default implementation. Returns a 404
            func (v BaseResource) Edit(c Context) error {
              return c.Error(404, errors.New("resource not implemented"))
            }
            

            Video Presentation