Ruby-on-Rails and Avo Tutorial
2023 disclaimer : Bootrails is now a partner of AvoHQ. Learn more
Avo Overview
AvoHQ main promise is to remove boilerplate. It’s an alternative to the Rails administrate gem.
Avo’s primary purpose is to manage database records for Rails applications. To do this, it uses the concept of a resource that corresponds to a model. Once a resource is defined, the user can map the database fields so Avo knows what data to display and how to do so. In Rails, index is for showing all instances of a resource, show is for showing a single specific instance, and edit/create are to edit and create a single instance specifically. So each field declaration in Avo adds a column of data to the Index view and a row to the Show, Edit, and Create views. Amazingly, Avo doesn’t support just basic fields; they handle complex ones like trix, markdown, gravatar, boolean_group, file, etc. Once these resources have been setup with the desired fields, they can be filtered based on conditions through the use of Avo filters. it’s as simple as generating the filter, setting up options, then adding it to one or more resources. Avo also has something called actions that can do things like apply transformations to resources. All in all, it’s a pretty powerful and convenient tool. Please note that it’s not free for advanced features.
Creating a Rails application utilizing Avo
Now that you have an idea of what Avo is, it’s time to put that knowledge to action!
Create a fresh new Rails app and install Avo
1
2
3
4
5
6
$> ruby -v
ruby 3.0.1p64 # Ruby >= 2.7
$> rails -v
Rails 7.0.2.4 # Ruby-on-Rails >= 6.0
$> bundle -v
Bundler version 2.3.14 # Bundler 2.xx
Now enter your workspace and type
1
2
bin/rails new avo_test
cd avo_test
Now in the gemfile, add
1
gem "avo"
Then run this command to complete the setup!
1
2
bundle install
bin/rails generate avo:install # Generate initializer and add Avo to routes.rb
Seed the database so we have information to play with!
Run these commands to create migrations for books and authors
1
2
bin/rails generate migration createBooks
bin/rails generate migration createAuthors
1
2
3
4
5
6
7
8
9
10
11
12
# Inside of db/migrate/..._create_authors.rb
class CreateAuthors < ActiveRecord::Migration[7.0]
def change
create_table :authors do |t|
t.string :first_name, null: false
t.string :last_name, null: false
t.string :email, null: false
t.timestamps
end
add_index :authors, :email, unique: true
end
end
1
2
3
4
5
6
7
8
9
10
11
# Inside of db/migrate/..._create_books.rb
class CreateBooks < ActiveRecord::Migration[7.0]
def change
create_table :books do |t|
t.string :title, null: false
t.integer :author_id, null: false
t.timestamps
end
add_index :books, :author_id
end
end
Now run the command
1
bin/rails db:migrate
Now create the corresponding models for the tables!
1
2
3
4
5
6
# Inside of app/models/author.rb
class Author < ApplicationRecord
validates :first_name, :last_name, :email, presence: true
validates :email, uniqueness: true
has_many :books
end
1
2
3
4
5
6
# Inside of app/models/book.rb
class Book < ApplicationRecord
validates :title, :author_id, presence: true
belongs_to :author
end
Now we can finally seed the database!
1
2
3
4
5
6
7
# Inside of db/seeds.rb
author1 = Author.create(first_name: "Tom", last_name: "Pratt", email: "tp@gmail.com")
author2 = Author.create(first_name: "John", last_name: "Smith", email: "js@gmail.com")
author3 = Author.create(first_name: "Jane", last_name: "Doe", email: "jd@gmail.com")
book1 = Book.create(title: "The Great Gatsby", author_id: author1.id)
book2 = Book.create(title: "The Catcher in the Rye", author_id: author1.id)
book3 = Book.create(title: "The Grapes of Wrath", author_id: author2.id)
Then run
1
bin/rails db:seed
Setup home page to look at the admin dashboard
1
2
bin/rails g controller home # Creates a home controller
echo '<h1>Hello world!</h1>' > app/views/home/index.html.erb
And make the default route the home page that you just created!
1
2
3
4
5
6
# Inside of config/routes.rb
Rails.application.routes.draw do
mount Avo::Engine, at: Avo.configuration.root_path
root "home#index"
end
Generating your first Avo Resource
Start out by defining resources! This command will generate a resource file in the app/avo/resources directory.
1
2
bin/rails generate avo:resource Author # Creates author_resource.rb
bin/rails generate avo:resource Book # Creates book_resource.rb
Now let’s define some fields to display since only id is shown by default.
1
2
3
4
5
6
7
8
9
# Inside of author_resource.rb
class AuthorResource < Avo::BaseResource
self.title = :id
self.includes = []
field :id, as: :id
field :first_name, as: :text
field :last_name, as: :text
field :email, as: :text
end
1
2
3
4
5
6
7
8
# Inside of book_resource.rb
class BookResource < Avo::BaseResource
self.title = :id
self.includes = []
field :id, as: :id
field :title, as: :text
field :author, as: :belongs_to
end
Now that everything is setup, use the command
1
bin/rails server
And navigate to http://localhost:3000/avo in your browser to check out the admin panel!
Click on the hamburger icon in the top left corner of the page and you can see the defined resources; authors and books.
Managing database records using Avo Resources
From the sidebar, click on the desired resource to manage and you reach this clean UI.
For example, clicking on the Books resource.
Notice how it’s already filled with our seeded data!
From here, you can easily: create a new book, delete the record, edit it, and view it alone. You can also select multiple or all books to edit/delete them all at once. It’s truly an admin panel that makes managing database records for Rails applications simple and easy. This simple demonstration doesn’t really show the power of: complex types, filtering, actions, grid view, etc. Please go through the Avo documentation and experiment with its more advanced features! I suggest looking at Avo’s demo app demo app to see what the framework is capable of doing.
Conclusion
So far our choice at Bootrails is to stick with plain old Rails (along with a CSS framework and pre-made design) to build the admin part. However it’s always interesting to see how other tools handle this. Avo creates beautiful admin panels for managing database records in Rails applications quickly.