Resource options ​

Avo effortlessly empowers you to build an entire customer-facing interface for your Ruby on Rails application. One of the most powerful features is how easy you can administer your database records using the CRUD UI.

Overview ​

Similar to how you configure your database layer using the Rails models and their DSL, Avo's CRUD UI is configured using Resource files.

Each Resource maps out one of your models. There can be multiple Resources associated to the same model if you need that.

All resources are located in the app/avo/resources directory.

Resources from model generation ​

bin/rails generate model car make:string mileage:integer

Running this command will generate the standard Rails files (model, controller, etc.) and Car resource and CarsController for Avo.

The auto-generated resource file will look like this:

class Avo::Resources::Car < Avo::BaseResource
  self.title = :id
  self.includes = []
  # self.search_query = -> do
  #   query.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  # end

  def fields
    field :id, as: :id
    field :make, as: :text
    field :mileage, as: :number
  end
end

This behavior can be ommited by using the argument --skip-avo-resource. For example if we want to generate a Car model but no Avo counterpart we should use the following command:

bin/rails generate model car make:string kms:integer --skip-avo-resource

Manually defining resources ​

bin/rails generate avo:resource post

This command will generate the Post resource file in app/avo/resources/post.rb with the following code:

# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
  self.title = :id
  self.includes = []
  # self.search_query = -> do
  #   query.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  # end

  def fields
    field :id, as: :id
  end
end

From this config, Avo will infer a few things like the resource's model will be the Post model and the name of the resource is Post. But all of those inferred things are actually overridable.

Now, let's say we already have a model Post well defined with attributes and associations. In that case, the Avo resource will be generated with the fields attributes and associations.

# == Schema Information
#
# Table name: posts
#
#  id           :bigint           not null, primary key
#  name         :string
#  body         :text
#  is_featured  :boolean
#  published_at :datetime
#  user_id      :bigint
#  created_at   :datetime         not null
#  updated_at   :datetime         not null
#  status       :integer          default("draft")
#
class Post < ApplicationRecord
 enum status: [:draft, :published, :archived]

 validates :name, presence: true

 has_one_attached :cover_photo
 has_one_attached :audio
 has_many_attached :attachments

 belongs_to :user, optional: true
 has_many :comments, as: :commentable
 has_many :reviews, as: :reviewable

 acts_as_taggable_on :tags
end

class Avo::Resources::Post < Avo::BaseResource
  self.title = :id
  self.includes = []
  # self.search_query = -> do
  #   query.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  # end

  def fields
    field :id, as: :id
    field :name, as: :text
    field :body, as: :textarea
    field :is_featured, as: :boolean
    field :published_at, as: :datetime
    field :user_id, as: :number
    field :status, as: :select, enum: ::Post.statuses
    field :cover_photo, as: :file
    field :audio, as: :file
    field :attachments, as: :files
    field :user, as: :belongs_to
    field :comments, as: :has_many
    field :reviews, as: :has_many
    field :tags, as: :tags
  end
end

It's also possible to specify the resource model class. For example, if we want to create a new resource named MiniPost resource using the Post model we can do that using the following command:

bin/rails generate avo:resource mini-post --model-class post

That command will create a new resource with the same attributes as the post resource above with specifying the model_class:

class Avo::Resources::MiniPost < Avo::BaseResource
  self.model_class = ::Post
end

Fields ​

Resource files tell Avo what records should be displayed in the UI, but not what kinds of data they hold. You do that using the fields method.

Read more about the fields here.

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

  def fields
    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
      record.published_at.present?
    end

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

Routing ​

Avo will automatically generate routes based on the resource name when generating a resource.

Avo::Resources::Post         -> /avo/resources/posts
Avo::Resources::PhotoComment -> /avo/resources/photo_comments

If you change the resource name, you should change the generated controller name too.

Use multiple resources for the same model ​

Usually, an Avo Resource maps to one Rails model. So there will be a one-to-one relationship between them. But there will be scenarios where you'd like to create another resource for the same model.

Let's take as an example the User model. You'll have an User resource associated with it.

# app/models/user.rb
class User < ApplicationRecord
end

# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
  self.title = :name

  def fields
    field :id, as: :id, link_to_resource: true
    field :email, as: :gravatar, link_to_resource: true, as_avatar: :circle
    field :first_name, as: :text, required: true, placeholder: "John"
    field :last_name, as: :text, required: true, placeholder: "Doe"
  end
end

So when you click on the Users sidebar menu item, you get to the Index page where all the users will be displayed. The information displayed will be the gravatar image, the first and the last name.

Let's say we have a Team model with many Users. You'll have a Team resource like so:

# app/models/team.rb
class Team < ApplicationRecord
end

# app/avo/resources/team.rb
class Avo::Resources::Team < Avo::BaseResource
  self.title = :name

  def fields
    field :id, as: :id, link_to_resource: true
    field :name, as: :text
    field :users, as: :has_many
  end
end

From that configuration, Avo will figure out that the users field points to the User resource and will use that one to display the users.

But, let's imagine that we don't want to display the gravatar on the has_many association, and we want to show the name on one column and the number of projects the user has on another column. We can create a different resource named TeamUser resource and add those fields.

# app/avo/resources/team_user.rb
class Avo::Resources::TeamUser < Avo::BaseResource
  self.title = :name

  def fields
    field :id, as: :id, link_to_resource: true
    field :name, as: :text
    field :projects_count, as: :number
  end
end

We also need to update the Team resource to use the new TeamUser resource for reference.

# app/avo/resources/team.rb
class Avo::Resources::Team < Avo::BaseResource
  self.title = :name

  def fields
    field :id, as: :id, link_to_resource: true
    field :name, as: :text
    field :users, as: :has_many, use_resource: TeamUserResource
  end
end

But now, if we visit the Users page, we will see the fields for the TeamUser resource instead of User resource, and that's because Avo fetches the resources in an alphabetical order, and TeamUser resource is before User resource. That's definitely not what we want. The same might happen if you reference the User in other associations throughout your resource files.

To mitigate that, we are going to use the model_resource_mapping option to set the "default" resource for a model.

# config/initializers/avo.rb
Avo.configure do |config|
  config.model_resource_mapping = {
    'User': 'UserResource'
  }
end

That will "shortcircuit" the regular alphabetical search and use the User resource every time we don't specify otherwise.

We can still tell Avo which resource to use in other has_many or has_and_belongs_to_many associations with the use_resource option.

Namespaced resources ​

Resources can't be namespaced yet, so they all need to be in the root level of that directory. If you have a model Super::Dooper::Trooper::Model you can use Avo::Resources::SuperDooperTrooperModel with the model_class option.

class Avo::Resources::SuperDooperTrooperModel < Avo::BaseResource
  self.model_class = "Super::Dooper::Trooper::Model"
end

Views ​

Avo generates the admin panel with four main views.

-> Index

-> Show

-> Edit

-> New

-> Preview

Extending Avo::ResourcesController ​

You may need to execute additional actions on the ResourcesController before loading the Avo pages. You can create 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?
end

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

Attach concerns to Avo::BaseController ​

Alternatively you can use this guide to attach methods, actions, and hooks to the main Avo::BaseController or Avo::ApplicationController.

Manually registering resources ​

In order to have a more straightforward experience when getting started with Avo, we are eager-loading the app/avo/resources directory. That makes all those resources available to your app without you doing anything else.

If you want to manually load them use the config.resources option.

# config/initializers/avo.rb
Avo.configure do |config|
  config.resources = [
    "UserResource",
    "FishResource",
  ]
end

This tells Avo which resources you use and stops the eager-loading process on boot-time. This means that other resources that are not declared in this array will not show up in your app.

Resource Options ​

Resources have a few options available for customization.

-> self.title

class Avo::Resources::Post < Avo::BaseResource
  self.title = :slug # it will now reference @post.slug to show the title
end

# app/avo/resources/comment.rb
class Avo::Resources::Comment < Avo::BaseResource
  self.title = :tiny_name
end

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

# app/avo/resources/comment.rb
class Avo::Resources::Comment < Avo::BaseResource
  self.title = -> {
    ActionView::Base.full_sanitizer.sanitize(record.body).truncate 30
  }
end

-> self.description

You might want to display information about the current resource to your users. Then, using the description class attribute, you can add some text to the Index, Show, Edit, and New views.

There are two ways of setting the description. The quick way as a string and the more customizable way as a block.

Set the description as a string ​

ruby

class Avo::Resources::User < Avo::BaseResource
  self.title = :name
  self.description = "These are the users of the app."
end

This is the quick way to set the label, and it will be displayed on all pages. If you want to restrict the message to custom views, use a lambda function.

Set the description as a block ​

This is the more customizable method where you can access the record, resource, view, current_user, and params objects.

ruby

class Avo::Resources::User < Avo::BaseResource
  self.title = :name
  self.description = -> do
    if view == :index
    "These are the users of the app"
    else
      if current_user.is_admin?
        "You can update all properties for this user: #{record.id}"
      else
        "You can update some properties for this user: #{record.id}"
      end
    end
  end
end

-> self.includes

class Avo::Resources::Post < Avo::BaseResource
  self.includes = [:user, :tags]
end

-> default_view_type

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

ruby

class Avo::Resources::Post < Avo::BaseResource
  self.default_view_type = :grid
end

Find out more on the grid view documentation page.

-> self.model_class

class Avo::Resources::DelayedJob < Avo::BaseResource
  self.model_class = ::Delayed::Job

  def fields
    field :id, as: :id
  end
end

-> self.devise_password_optional

class Avo::Resources::User < Avo::BaseResource
  self.devise_password_optional = true
end

-> self.visible_on_sidebar

class Avo::Resources::TeamMembership < Avo::BaseResource
  self.visible_on_sidebar = false
end

-> config.buttons_on_form_footers

If you have a lot of fields on a resource, that form might get pretty tall. So it would be useful to have the Save button in the footer of that form.

You can do that by setting the buttons_on_form_footers option to true in your initializer. That will add the Back and Save buttons on the footer of that form for the New and Edit screens.

ruby

# config/initializers/avo.rb
Avo.configure do |config|
  config.buttons_on_form_footers = true
end

-> after_create_path/after_update_path

class Avo::Resources::Comment < Avo::BaseResource
  self.after_create_path = :index
  self.after_update_path = :edit
end

-> self.record_selector

You might have resources that will never be selected, and you do not need that checkbox to waste your horizontal space.

You can hide it using the record_selector class_attribute.

ruby

class Avo::Resources::Comment < Avo::BaseResource
  self.record_selector = false
end

-> self.link_to_child_resource

class Avo::Resources::Person < Avo::BaseResource
  self.link_to_child_resource = true
end

-> self.keep_filters_panel_open

Watch the demo video

There are scenarios where you wouldn't want to close the filters panel when you change the values. For that, you can use the keep_filters_panel_open resource option.

ruby

class Avo::Resources::Course < Avo::BaseResource
  self.keep_filters_panel_open = true

  def fields
    field :id, as: :id
    field :name, as: :text
  end

  def filters
    filter Avo::Filters::CourseCountryFilter
    filter Avo::Filters::CourseCityFilter
  end
end

Unscoped queries on Index ​

You might have a default_scope on your model that you don't want to be applied when you render the Index view.

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

You can unscope the query using the index_query method on that resource.

class Avo::Resources::Project < Avo::BaseResource
  self.title = :name
  self.index_query = -> { query.unscoped }
end