Active Admin

Es una gema que utilizamos como back office.
¿Por qué la usamos?
La utilizamos porque resuelve rápidamente los típicos CRUD de admin. Con ActiveAdmin en unos minutos puedes tener para un recurso (modelo ActiveRecord): el menu para acceder, las vistas para crear/editar, el listado paginado con filtros y varias cosas más.
¿Cómo la usamos?
Instalación
La gema viene instalada si el proyecto se generó usando Potassium. Si no es así, igual puedes agregarlo luego ejecutando potassium install admin.
Uso básico
Supongamos que tenemos el modelo Blog con los atributos title, body y user (owner del Blog). Si agregamos bajo /app/admin/blogs.rb el siguiente código:
ActiveAdmin.register Blog do
end
Al acceder a http://localhost:3000/admin/blogs veremos el listado de blogs:
​
​
y si hacemos clic en el link "Editar" de alguno de los blogs veremos el formulario:
​
​
Listo! Eso es todo lo que necesitas hacer para tener algo funcionando. De todos modos, en un proyecto Platanus comúnmente verás algo como esto:
ActiveAdmin.register Blog do
  permit_params :title, :body, :user_id
​
  filter :title
​
  index do
    selectable_column
    id_column
    column :title
    column :user
    actions
  end
​
  show do
    attributes_table do
      row :title
      row :body
      row :user
    end
  end
​
  form do |f|
    f.semantic_errors
​
    f.inputs do
      f.input :title
      f.input :body
      f.input :user
    end
​
    f.actions
  end
end
para tener más control de lo que se quiere mostrar. Por ejemplo, así se ve el index con la configuración custom:
​
​
I18n
Active Admin toma la configuración de locales de Rails para traducir los nombres de las columnas. Por ejemplo, para traducir los atributos de Blog deberías tener la siguiente configuración:
/config/locales/es-CL.yml
es-CL:
  activerecord:
    attributes:
      blog:
        title: Título
        body: Texto
        user: Dueño
De esta manera al entrar por ejemplo la vista de un Blog verás los atributos traducidos:
​
​
Ten en cuenta que también funciona con métodos (getters) custom. Por ejemplo, podrías tener:
/app/models/blog.rb
class Blog < ApplicationRecord
  def my_method
    "Hola!"
  end
end
/config/locales/es-CL.yml
es-CL:
  activerecord:
    attributes:
      blog:
        my_method: Mi método
/app/admin/blogs.rb
ActiveAdmin.register Blog do
  index do
    selectable_column
    id_column
    column :my_method
    actions
  end
​
  show do
    attributes_table do
      row :my_method
    end
  end
end
y funcionará.
Menú
Agrupar recursos
Para agrupar varios items dentro de un mismo menú, debes:
1.Definir el menú en el initializer de active admin:
/config/initializers/active_admin.rb
ActiveAdmin.setup do |config|
  config.namespace :admin do |admin|
    admin.build_menu do |menu|
      menu.add id: :some_menu_id, label: "Grupo"
    end
  end
end
2.Definir en el recurso su menú padre:
/app/admin/blogs.rb
ActiveAdmin.register Blog do
  menu parent: :some_menu_id
end
​
​
Ocultar menú
Se hace de la siguiente manera:
/app/admin/blogs.rb
ActiveAdmin.register Blog do
  menu false
end
A simple vista parece no tener mucha utilidad pero lo importante aquí es que aunque no exista el menú, igual existen los endpoints. Algo que puede ser conveniente si queremos usar alguna ruta del admin como una API.
​
​
Menú condicional
Puede ser útil mostrar u ocultar un menú dependiendo de una condición. El caso más típico es el de roles. Por ejemplo:
/app/admin/blogs.rb
ActiveAdmin.register Blog do
  menu if: -> { current_admin_user.super_admin? }
end
Permisos (Pundit)
En Platanus usamos Active Admin con el adapter de Pundit para autorizar recursos. Si al registrar un nuevo recurso en AA, no tienes creado el policy de ese recurso, observarás un error así:
​
​
Si esto ocurre, agrega el policy correspondiente y define los permisos para cada una de las acciones del CRUD:
class BlogPolicy < ApplicationPolicy
  def index?
    true
  end
​
  def show?
    true
  end
​
  def create?
    true
  end
​
  def new?
    create?
  end
​
  def update?
    true
  end
​
  def edit?
    update?
  end
​
  def destroy?
    true
  end
end
Si todavía no estás en la instancia del proyecto en la cual tienes que preocuparte por permisos deja todas las acciones en true.
Es importante mencionar que si una acción no tiene permisos, esta desaparecerá del menú y links, etc. Por ejemplo:
class BlogPolicy < ApplicationPolicy
  def show?
    false
  end
end
Al tratar de acceder a http://localhost:3000/admin/blogs/303
​
​
Se puede ver además como el link a "Ver" desapareció:
​
​
Action Items
Los action_items son botones que se pueden agregar a las vistas del recurso. Por ejemplo, el siguiente código mostrará un botón (link), solo en la vista index, para ir al listado de administradores.
action_item :go_to_admins, only: [:index] do
  link_to("Ver Administradores", admin_admin_users_path)
end
​
​
Ten en cuenta que puedes decidir en qué vistas aparecerá el botón usando la opción only.
Member Action
Las member_actions son acciones extra que se pueden agregar al controller del recurso. Por ejemplo, el siguiente código:
member_action :send_mail, method: :post do
  # Ejecuta algún código. Por ejemplo enviar el blog por mail a n usuarios.
​
  redirect_to admin_blogs_path
end
sumará el endpoint /admin/blogs/:id/send_mail a los endpoints del CRUD.
​
​
Ten en cuenta que se puede utilizar action_items para ejecutar estas nuevas acciones. Por ejemplo, el siguiente código agregará un botón en la vista del blog (show) desde el que se llamará a la acción send_mail.
action_item :send_mail, only: [:show] do
  link_to("Enviar a Admin Users", send_mail_admin_blog_path(resource), method: :post)
end
Una alternativa a los action_items es agregar la acción al listado del index así:
index do
  # ...
  actions do |blog|
    link_to("Enviar", send_mail_admin_blog_path(blog), method: :post)
  end
end
​
​
Collection Action
Es lo mismo que una member_action pero sin apuntar a un recurso en particular sino a la colección. Por ejemplo, la siguiente member_action:
member_action :send_mail, method: :post do
  # ...
end
creará el siguiente endpoint: POST /admin/blogs/:id/send_mail. En cambio, esta collection_action:
collection_action :send_mails, method: :post do
  # ...
end
generará este: POST /admin/blogs/send_mails
La idea entonces con esto es que las member_actions se usen junto a action_items en show, new y update y las collection_action con action_items en el index.
Ten en cuenta que dentro de una member_action podrás acceder al recurso actual (en nuestro ejemplo un Blog de id x) usando el método resource. En cambio, en una collection_action, podrás acceder al listado de recursos (lista de Blogs en el ejemplo), que está mostrando el index en ese momento, usando el método collection.
Display Name
Si prestaste atención a la imagen del formulario de la sección "Uso básico", seguro notaste que el selector de usuarios no muestra correctamente el nombre de los mismos:
​
​
esto se debe a que Active Admin espera que los recursos tengan definido el método: :display_name para que puedan ser representados como "String". Si el recurso no lo implementa, simplemente llamará a to_s mostrando como resultado lo que vemos en el selector. Entonces, para solucionar esto, podemos hacer lo siguiente:
class User < ApplicationRecord
  def display_name
    email
  end
end
​
​
Ten en cuenta que display_name (o cualquiera de las otras opciones) se utilizará en varios lugares: en el título de un recurso, en los links de las rows/columns y, como vimos, en los selectores.
Vistas custom
Hay veces que necesitamos agregar nuevos endpoints con HTML a medida. Para hacer esto hacer lo siguiente:
1.Agregar la member_action:
member_action :preview, method: :get do
  @blog = resource
end
2.Agregar el action_item:
action_item :preview, only: [:show] do
  link_to("Previsualizar", preview_admin_blog_path(resource))
end
3.Agregar la vista custom:
Agregamos el HTML para nuestra nueva member_action en /app/views/admin/blogs/preview.html.erb
<h1><%= @blog.title %></h1>
<p><%= @blog.body %></p>
​
​
Ten en cuenta que puedes agregar el archivo con extensión .arb en vez de .erb y usar la gema Arbre que es el DSL que Active Admin utiliza para dibujar sus vistas. El siguiente código:
/app/views/admin/blogs/preview.html.arb
h1 { resource.title }
para { resource.body }
sería equivalente a lo de /app/views/admin/blogs/preview.html.erb en Arbre.
Link de download para archivos
Para manejo de archivos se supone el uso de Shrine
Suponiendo que el blog tiene un archivo image:
1.Agregar la member_action:
member_action :download, method: :get do
  blog = Blog.find(params[:id])
  send_file blog.image.download
end
2.Agregar el action_item:
action_item :download, only: :show, if: -> { blog.image.present? } do
  link_to 'Download', download_admin_blog_path(blog)
end
3.Agregar link a las actions en el index
index do
  column :id
  .
  .
  .
  actions defaults: true do |blog|
    link_to 'Download Image', download_admin_blog_path(blog)
  end
end
JavaScript en una vista
Si necesitas agregar alguna pequeña inteligencia en una vista de Active Admin revisa nuestra guía sobre AlpineJS.
Active Admin Addons
Es una gema construida en Platanus sobre Active Admin y la utilizamos para facilitar algunas features comunes. Por ejemplo: inputs con select2, selector de booleanos en index/show, selector de colores, etc.
Inputs custom
Muchas veces en un formulario de Active Admin necesitamos un input custom. Por ejemplo: selectores de moneda, de colores, con búsqueda ajax, etc. Por esto, Active Admin ofrece una forma sencilla de agregar estos controles. Para mostrarte cómo funciona te mostraré en pasos como agregar un input que escribe con console.info lo que se escribió en input en el evento focus out.
1.Agregar el archivo con mi input en /app/inputs/logger_input.rb.
Ten en cuenta que el nombre del archivo debe tener la forma: [nombre_control]_input y lo mismo para el nombre de la clase, pero en CamelCase.
class LoggerInput < ActiveAdminAddons::InputBase
  def render_custom_input
    concat(label_html)
    concat(builder.text_field(method, input_html_options))
  end
end
2.Agregar el js con la lógica del focus out en /app/assets/javascripts/admin/inputs/logger_input.js
$(document).ready(function(){
  $('.logger-input').each(function(i, el) {
    $(el).on( "focusout", function(event) {
      console.info(event.currentTarget.value);
    });
  });
});
3.Incluir el js en /app/assets/javascripts/active_admin.js:
//= require active_admin/base
//= require admin/inputs/logger_input
4.Usar en el form:
ActiveAdmin.register Blog do
  form do |f|
    f.inputs do
      f.input :title, as: :logger
    end
​
    f.actions
  end
end
Filtros custom
Para manejar la búsqueda de los filtros ActiveAdmin por debajo usa Ransack. Esta gema usa distintos sufijos para indicar distintos tipos de búsqueda. Además, nos permite hacer búsquedas con respecto a atributos de asociaciones.
Por ejemplo, si queremos buscar blogs por nombre de usuario:
filter :user_name_cont
Aquí _cont indica que se entregarán los resultados que contengan el valor dado. Podríamos haber usado _eq si quisieramos un match perfecto, por ejemplo.
Utilizando Vue
Muchas veces lo que se puede hacer con AA es un poco riguroso en cuanto a las necesidades del cliente, por lo que pueden haber situaciones en las cuales necesitemos incorporar Vue.js en AA. A continuación se explica una guía paso a paso de cómo agregar este en AA.
Para esto tenemos 2 opciones:
1.Hacer una vista custom como se mencionó anteriormente y ahí usar Vue.
2.Usar directamente un componente en la vista de admin o en un vista html.arb.
Primer caso.
1.Se crea el componente vue que queremos utilizar, por ejemplo massive-edit.vue.
2.Luego debemos registrar el componente globalmente. Acá necesitamos usar un archivo diferente al application.js que utilizamos normalmente, para este caso usaremos un archivo llamado admin_application.js que se debe encontrar en la misma carpeta que el application.js, si no se encuentra debe crearlo, la convención para registrar los componentes que se usan en admin es de snake_case, siguiendo con el ejemplo anterior el archivo se vería así:
import Vue from 'vue/dist/vue.esm';
import MassiveEdit from '../views/products/massive-edit.vue';
​
Vue.component('massive_edit', MassiveEdit);
​
document.addEventListener('DOMContentLoaded', () => {
  if (document.getElementById('wrapper') !== null) {
    return new Vue({
      el: '#wrapper',
    });
  }
​
  return null;
});
3.Si queremos utilizar filtros, i18n o tailwind en los archivos Vue que utilizaremos en AA, debemos importarlos en este archivo también, tal como lo hacemos normalmente. Cabe destacar que si tenemos algo importado en application.js no va a funcionar en los componentes que se utilicen en AA, si no que debemos importarlos nuevamente en admin_application.js, acá un ejemplo del archivo completo:
import { camelizeKeys } from 'humps'; // filtro camelize
import Vue from 'vue/dist/vue.esm';
import MassiveEdit from '../views/products/massive-edit.vue';
import i18n from '../plugins/i18n'; // i18n
import '../css/application.css'; // tailwind
​
Vue.component('massive_edit', MassiveEdit);
Vue.filter('camelizeKeys', camelizeKeys);
​
document.addEventListener('DOMContentLoaded', () => {
  if (document.getElementById('wrapper') !== null) {
    return new Vue({
      el: '#wrapper',
      i18n,
    });
  }
​
  return null;
});
4.Luego podemos ir a cualquier vista dentro de app/views/admin y usar el componente como lo hacemos normalmente:
 <massive_edit :props="@props.to_json"> </massive_edit>
Segundo caso.
1.Hacer los mismos pasos anteriores.
2.Instalar la clase vue_component desde nuestra gema potassium. Esto agrega un par de inicializadores a nuestra app. Se debe escribir potassium install y escoger vue_component.
3.Luego en el archivo initializers/active_admin.rb debemos importar vue_componment y hacer build del componente registrado anteriormente:
    require "vue_component.rb"
​
    AUTO_BUILD_ELEMENTS = %i{
      massive_edit
    }
​
    component_creator(AUTO_BUILD_ELEMENTS)
La función component_creator recibe los nombres de los componentes y los convierte a html que puede procesar AA mediante la gema Arbre. Lo anterior se debe poner fuera del ActiveAdmin.setup.
4.Utilizar el componente en la vista, puede ser de las siguientes formas:
a. html.arb:
massive_edit(prop1: prop1, prop2: prop2)
b. admin
index do
  massive_edit(prop1: prop1, prop2: prop2)
end
Recursos útiles
​Active Admin Docs​
​Active Admin Addons Docs​
Observers
Shrine
Última actualización 1mo ago