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:

1. Automatic code generation
2. No DSL
3. 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: '[email protected]', 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.