# Resources

Avo effortlessly empowers you to build a full admin dashboard for your Ruby on Rails application. One of the most powerful features is how easy you can administer your database records. Avo does this using Resources. Each resource maps out one of your models.

# Defining Resources

bin/rails generate avo:resource post

This command will generate a resource file under your app/avo/resources directory. The app/avo directory will hold all of your Avo configuration files.

Inside the creates resource file will look like so:

class PostResource < Avo::BaseResource
  self.title = :id
  self.includes = []

  field :id, as: :id
  # add fields here

From this config, Avo will infer that the resource's model will be the Post model.

You can add more fields to this resource below the id field.


class PostResource < Avo::BaseResource
  self.title = :id
  self.includes = []

  field :id, as: :id
  field :name, as: :text, required: true
  field :body, as: :trix, placeholder: "Add the post body here", always_show: false
  field :cover_photo, as: :file, is_image: true, link_to_resource: true
  field :is_featured, as: :boolean

  field :is_published, as: :boolean do |model|

  field :user, as: :belongs_to, placeholder: "—"

# Setting the title of the resource

Initially, the title attribute is set to :id, so the model's id attribute will be used to display the resource in search results and belongs select fields. You usually change it to something more representative, like the model's title, name or label attributes.

class PostResource < Avo::BaseResource
  self.title = :name # it will now reference @project.name to show you the title

# Using a computed title

You can use a computed title property for your resources if the field that is the title is not that unique.


# app/avo/resources/comment_resource.rb
class CommentResource < Avo::BaseResource
  self.title = :tiny_name

  # field go here

# app/models/comment.rb
class Comment < ApplicationRecord
  def tiny_name
    ActionView::Base.full_sanitizer.sanitize(body).truncate 30

# Eager loading

If you regularly need access to a resource's associations, you can tell Avo to eager load those associations on the Index view using includes. This will help you avoid those nasty n+1 performance issues.

class PostResource < Avo::BaseResource
  self.includes = [:user, :tags]

# Views

Each generated resource will have four views Index view where you see all your resources listed, Show view where you get to see one resource in more detail, Edit view where you can edit one resource and Create view where you can create a new resource.

# Grid view

On Index view, the most common view type is :table. You might have some data that you want to display in a grid view. You change that by setting default_view_type to :grid and add the grid block.

Avo grid view
class PostResource < Avo::BaseResource
  self.default_view_type = :grid

See how you can customize the grid item in the additional grid view documentation.

# Custom model class

You might have a model that belongs to a namespace or that has a different name than than the resource. For those occasions you can use the @model option to tell Avo which model to reference.


class DelayedJobResource < Avo::BaseResource
  self.model_class = ::Delayed::Job

  field :id, as: :id
  # ... other fields go here

# Devise password optional

If you use devise and you update your user models (usually User) without passing a password you will get a validation error. You can use devise_password_optional to stop receiving that error. It will strip out (opens new window) the password key from params.

class UserResource < Avo::BaseResource
  self.devise_password_optional = true

# Unscoped queries on Index

You might have a default_scope on your model and you don't want it to be applied to your resource when rendered on the Index view.


class Project < ApplicationRecord
  default_scope { order(name: :asc) }

You can unscope the query using the unscoped_queries_on_index (defaults to false) class variable on that resource.


class ProjectResource < Avo::BaseResource
  self.title = :name
  self.unscoped_queries_on_index = true

  # fields go here

# Extend the Avo::ResourcesController

You may need to execute additional actions on the ResourcesController before loading the Avo pages. You can do that by creating an Avo::BaseResourcesController and extend your resource controller from it.

# app/controllers/avo/base_resources_controller.rb
class Avo::BaseResourcesController < Avo::ResourcesController
  include AuthenticationController::Authentication

  before_action :is_logged_in?

# app/controllers/avo/posts_controller.rb
class Avo::PostsController < Avo::BaseResourcesController

You can't use Avo::BaseController and Avo::ResourcesController as your base controller. They are defined inside Avo.

# Filters

It's a very common scenario to add filters to your resources to make it easier to find your records. Check out the additional Filters documentation to see how easy it is to set up custom filters with Avo.

Avo filters

# Actions

Most of the time, you will want to trigger some events against your records or run more heavy updates. Avo makes this so easy with Actions.

Avo actions

Check out the additional Actions documentation.

Check out the additional Search documentation.