Introduction
Rails engineers, what do you do when creating an admin panel or internal tool?
One way is to use a RubyGem such as ActiveAdmin, but I’ve encountered a few problems with this approach.
- It's hard to customize with DSL.
- Sometimes I can’t achieve the required functionality.
- The design isn’t to my liking.
For these reasons, I didn’t use an existing Gem but built it from scratch. However, even though doing that every time was inefficient, it was worth the effort because many elements of the internal tool’s features can be shared.
The good news is I’ve now solved the inefficiency problem and so streamlined development by creating my own framework. And it’s improved my productivity so dramatically that I wanted to share it with you by turning the framework into a Gem and releasing it publicly.
So I’m now going to show you how to use the Gem Infold.
Demo Site
First off, take a look at the demo site.
This application is built using only functions automatically generated by the Gem.
Tool Features
The tool has the following advantages:
- Automatic code generation
- No DSL
- Modern, easy-to-use UI/UX
1. Automatic code generation
However, it is not in AI format like GitHub Copilot but an extension of Rails' Scaffold.
As you know, Rails scaffold automatically generates code such as controller, model, view, etc., and automatically create the basic functionality that enables CRUD. I’ve exploited this mechanism to develop a specialized generator for the admin panel.
In addition, the generated code is designed to be readable. My aim isn’t just to make code that works but also to make the code easy for developers to read and customize for their own needs.
2. No DSL
YAML is used instead of DSL for configuration. When the YAML loads into the generator, it automatically generates the CRUD app according to the configuration.
Although YAML doesn’t let you write DSL-like logic, it does enable general configuration. I think it’s better to automatically generate code up to a level that can be shared without difficulty. The code can then be customized just like in normal Rails development instead of using the DSL to realize all functions. So I’ve created a system that automatically generates code.
However, even with just the YAML settings, you can generate a variety of functions. For example, as implemented in the demo site, the following functionality is available:
- Bulk registration and reference of
has_many
association - Validation, Enum, Decorator, and other mechanisms
- Image file registration, CSV file output, etc.
3. Modern, easy-to-use UI/UX
Hotwire is used to let you create a SPA-like UI/UX. In addition, Tabler, which is based on Bootstrap 5, is used for the UI template. This lets you create a modern, high-usability design.
Generally, designers aren’t involved in creating admin panels—not even the UI. My aim is to enable developers who aren’t proficient in design to create usable admin panels.
Supported Rails versions
- Infold requires Rails 7.0 or later as it’s intended to work with Hotwire.
- Rails requires a JavaScript bundler such as esbuild.
Getting started
I’ll now explain the process from installation to actual customization.
Install Infold
Add infold
and the various gems used in Infold to the Gemfile and bundle install
.
# Gemfile
gem 'infold', require: false
gem 'devise' # Certification
gem 'haml-rails' # HAML
gem 'kaminari' # Pagination
gem 'view_component' # View Component
gem 'active_decorator' # Decoration
gem 'enum_help' # Enum Helpers
Next, install from the Infold generator.
$ rails g infold:install
When you do this, common files used by view_component, stimulus, and so on will be generated.
Similarly, Devise migrations will also be generated. After you’ve run the migration, set up a test account from the Rails console.
$ rails db:migrate
$ rails console
AdminUser.create(email: 'user@example.com', password: 'password')
Start Rails from bin/dev
, access http://localhost:3000/admin
with your browser, and log in to the account you set up.
The login function has now been created. Continue to build the application.
In the following tutorial, you’ll create customer, product, and order management apps.
Creating a customer management app
First, create a customer model. Here you’ll use the standard Rails generate model.
$ bin/rails g model Customer name:string address:string gender:integer
$ bin/rails db:migrate
Use Infold’s generator to create an app for this model.
$ bin/rails g infold Customer
This is all you need to generate the customer management app. Access localhost:3000/admin/customers
from your browser to run the app.
Bring up the form by clicking the orange "Create New" button. After you’ve filled the form out, click the "Create" button.
The note icon on the left of the list displays the reference view; the pencil icon on the right displays the edit view.
In just a few steps, you were able to generate a CRUD-based admin panel app.
At this point, files such as Controller and View are automatically generated. For example, app/controllers/admin/customer_controller.rb
is generated as follows:
Thus, Infold isn't like ActiveAdmin in that instead of generating the app itself, it generates the source code. Also, because the code is in standard Rails, it can be easily edited by Rails developers. Customizations that cannot be achieved with the gem alone can be flexibly handled by editing the code directly.
Customized customer management app
You can customize the app generated above by configuring it in YAML. Try it out by adding the following functions:
- Set Name as a required field.
- Gender is an enum of male, female, and other, which are selectable with radio buttons.
When you executed the generator mentioned above, customer.yml
is generated in the config/infold
directory. Change the contents of this file to the following:
# config/infold/customer.yml
model:
validate:
name: presence
enum:
gender:
male: 1
female: 2
other: 3
app:
form:
fields:
- name
- address
- gender:
kind: radio
After you’ve edited the YAML, run the following again to regenerate the customer management app.
$ bin/rails g infold Customer
Validation and radio button forms are activated.
Creating a product management app
Next, create a product management app.
Rails Model Generation
$ bin/rails g model Product title:string price:integer
$ bin/rails db:migrate
Generating apps with Infold
$ bin/rails g infold Product
Access localhost:3000/admin/products
with your browser to run the product management app. The header menu also has PRODUCTS added.
Display of product images
Infold supports ActiveStorage. So if, for example, you want to manage product images, config/infold/product.yml
should be set as follows:
# config/infold/product.yml
model:
active_storage:
photo:
kind: image
app:
index:
list:
fields:
- id
- title
- photo
- price
form:
fields:
- title
- photo:
kind: file
- price
Note that ActiveStorage must already be installed in the project.
Generate apps with Infold.
$ bin/rails g infold Product
With the above settings, images can be registered from the form and will be displayed in the list too.
Creating an order management app
The customer and product management apps above had a single table as a CRUD, but the following order management app will set up a relationship between customer and product.
Create an order model from Rails.
$ bin/rails g model Order customer:references product:references amount:integer
$ bin/rails db:migrate
The relationships are as follows:
Generate an order management app from Infold. You can generate only YAML files by using g infold:resource
.
$ bin/rails g infold:resource Order
Edit config/infold/order.yml
as follows to set associations for order and other models.
Note that the name_field in the * portion below specifies a field for the name of the record. As a result, related destination records can be displayed in that field. For example, the Order
model is associated with the Customer
model via customer_id
, but instead of customer_id
, it displays customer.name
on the view.
# config/infold/order.yml
model:
association:
customer:
kind: belongs_to
name_field: name # *
product:
kind: belongs_to
name_field: title # *
app:
form:
fields:
- customer:
kind: select
- product:
kind: select
- amount:
kind: number
After you've edited the YAML, generate the app from Infold.
$ bin/rails g infold Order
For example, from the registration form, the customer and product can be selected from a list.
Also, after you’ve registered an order, the customer and product will be displayed as links that can be clicked on for more information.
Practical usage
Bulk registration of has_many
association
The current order management app allows only one product to be registered per order because the order model is directly related to the product model ( order belongs_to product
). To register multiple products at the same time, add an OrderDetail model and change the modeling to order has_many order_details
, order_detail belongs_to product
.
Next comes modifying and adding models in Rails. First, generate the following migration to remove the association between order and product.
$ bin/rails g migration RemoveProductFromOrders product:references amount:integer
Also, remove the belongs_to :product
as it remains in the order model.
# models/order.rb
class Order < ApplicationRecord
belongs_to :customer
- # Delete the following
- belongs_to :product
end
Next, create an OrderDetail
model and migrate.
$ bin/rails g model OrderDetail order:references product:references amount:integer
$ bin/rails db:migrate
Change the order.yml in Infold.
# config/infold/order.yml
model:
...
association:
customer:
kind: belongs_to
name_field: name
- # Delete the following
- product:
- kind: belongs_to
- name_field: title
+ # Add the following
+ order_details:
+ kind: has_many
+ dependent: destroy
+ model: # Associated models (order_details) can also be set
+ validate:
+ product: presence
+ association: # Further associations to order_details (product)
+ product:
+ kind: belongs_to
+ name_field: title
app:
+ # Bulk display on detail page as well
+ show:
+ fields:
+ - id
+ - customer
+ - order_details:
+ fields:
+ - product
+ - amount
form:
fields:
- customer:
kind: select
- # Delete the following
- - product
- kind: select
- - amount
- kind: number
+ # Add the following
+ - order_details:
+ kind: association
+ fields:
+ - product:
+ kind: select
+ - amount:
+ kind: number
Regenerate the order management app from Infold.
$ bin/rails g infold Order
The form allows bulk registration. Add rows with the ADD button and delete them with the trash icon at the right end of the row.
Search and specify associated data from a child screen
In the current order management registration form, customers are in a drop-down list. As the number of customers increases, it becomes more and more difficult to specify the corresponding record in the list (for instance, if there are 100 customers, there’ll be 100 choices in the list, making it unusable).
Infold lets you search and specify associated models by belongs_to
from a child screen. Here’s how to change from order management to specifying customers on a child screen.
First, edit the YAML (customer.yml) on the customer management side to enable child screen searches for customers.
# config/infold/customer.yml
model:
...
app:
form:
...
+ # Add the following
+ association_search:
+ conditions:
+ - id:
+ sign: eq
+ - name:
+ sign: full_like
+ list:
+ fields:
+ - id
+ - name
Next, edit the YAML (order.yml) on the order management side (change kind
from select
to association_search
).
# config/infold/order.yml
model:
...
app:
form:
fields:
- customer:
- kind: select
+ kind: association_search
- order_details:
...
Regenerate apps from Infold for customer management and order management.
$ bin/rails g infold Customer
$ bin/rails g infold Order
You can see that the customer element has changed on the order management registration form screen.
Click the blue "Search" button on this form to bring up the customer search screen on the child screen.
Search on the child screen and click the check icon in the list to transfer the corresponding customer to the order management form.
Internationalization (I18n)
Infold supports internationalization (I18n). See the Rails Guide and other sources for details.
For example, to display Japanese(ja), create config/initializers/locale.rb
as follows.
# config/initializers/locale.rb
I18n.config.available_locales = [:ja, :en]
I18n.default_locale = :ja
I18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}').to_s]
Also, download ja.yml from rails-i18n and put it in config/locales
.
Create a models directory in config/locales
and create customer.ja.yml
with the following contents.
# config/locales/models/customer.ja.yml
ja:
activerecord:
attributes:
customer:
name: 氏名
address: 住所
gender: 性別
The customer management screen will be translated into Japanese.
Note: Although the buttons and message content are also translated into Japanese, Infold itself is still only in English and Japanese.
I’d appreciate your help in translating it into your own language!
When translating Enum elements, you need to plug in admin
as follows.
ja:
activerecord:
attributes:
customer:
name: 氏名
address: 住所
gender: 性別
+ enums:
+ admin: # Need to plug admin
+ customer:
+ gender:
+ male: 男性
+ female: 女性
+ other: その他
Summary
This has been a long tutorial, but I hope you now know how to use Infold.
As you can see, it’s possible to generate a reasonable level of functionality just by using YAML settings.
The next step is to customize the automatically generated source code.
Compared to starting from scratch, I think you’ll be able to speed up implementing admin panels considerably, so I hope you’ll consider using this gem!
Code used in this tutorial
The code for the app created above is in my GitHub repository.
Top comments (0)