Lists

No Nerdify, o bloco list define como uma coleção de registros do modelo será apresentada visualmente em telas como index. Ele permite configurar visualizações em diferentes formatos — como tabela, kanban, cards ou calendário — e ainda integrar com actions interativas, ordenações e seleções.

✅ Estrutura básica

list :customers_table, type: :table, size: 12, paginate: true, paginate_per: 20 do
  # definição da estrutura de cada item
end

⚙️ Opções padrão do `list`

Opção	Tipo	Descrição
`type`	Symbol	Tipo da lista: `:table`, `:cards`, `:kanban`, `:calendar`, `:timeline`, `:custom`, `:tree`
`size`	Integer	Número de colunas do layout Bootstrap (1 a 12)
`paginate`	Boolean	Se deve paginar os dados
`paginate_per`	Integer	Quantidade de itens por página
`aggregate`	Boolean	Usa agregação do MongoDB
`pipeline`	Symbol	Método que retorna o pipeline para agregação
`click_item`	Hash	Ação ao clicar no item: `{get:, post:, redirect_to:, etc}`. A definição é igual a de uma action
`sortable`	Symbol	Nome da `action` para reordenar os itens (padrão do nerdify para fazer ordenação automaticamente: `sortable: :sort`)
`selectable`	Symbol	Nome do parâmetro com os itens selecionados (ex: `:item_ids`)
`styles`	Hash	Estilo visual do componente da lista.

🔀 Integração com Actions

✅ `click_item`

Permite definir o comportamento ao clicar sobre um item da lista. Exemplo:

list :table, type: :table, click_item: { redirect_to: "/customers/:resource.id" }

Você pode usar :resource para acessar dados do item clicado. No exemplo acima, utilizamos para acessar o id do item.

⚠️ Se você usar actions com position: :inline ou :dropdown, é recomendado remover o click_item para não haver conflito com clique em duplicidade. Porque o click_item é aplicado ao item como um todo, sendo ativado quando clicar em qualquer parte do elemento da lista.

✅ `selectable`

Permite exibir checkboxes ao lado de cada item. A action pode acessar os selecionados via :resource.item_ids se o o atributo passado for selectable: :item_ids.

list :table, type: :table, selectable: :item_ids

Action para processar os selecionados:

action :delete_selected, only: %w[index], render_if: "page.selectable?.item_ids?.length > 0", click: {
  delete: "/customers", params: { ids: ":page.selectable.item_ids" }
}

↕️ `sortable`

Permite reordenar visualmente os itens com drag & drop.

list :table, type: :table, sortable: :sort do
end

Crie um campo position do tipo Integer fora dos fieldsets
Adicione escopo default ordenando pelo campo:

default_scope -> { order(asc: :position) }

A action de sort definida automaticamente pelo nerdify é chamada automaticamente ao reordenar. Ela recebe a posição de todos os itens através do parametro params[:ids] que retorna o array de ids nas posições reordenadas. E com isso pode atualizar todos os dados para a nova posição correta.

params[:ids] # => array com os ids na nova ordem

Você pode utilizar uma action com outro nome para usar um metodo personalizado no controlador e implementar uma lógica manual para tratar a ordenação a partir do params[:id] recebido.

🛠️ Alternância entre listas

Você pode usar múltiplas listas para um mesmo modelo e alternar entre elas no frontend com:

action :index, lists: %w[table kanban calendar], default_list: :table

No template padrão, isso exibe botões para o usuário alternar entre os modos de visualização da lista. Os valores passados no array de listas da action, devem ser os nomes das listas que deseja exibir.

🔍 Tipos de lista suportados

Cada tipo de lista tem suas opções e estrutura próprias. Abaixo você verá seções específicas para:

🎯 Opções específicas por tipo de lista

Alguns tipos de list no Nerdify possuem opções específicas além das comuns. Abaixo estão listadas por tipo:

📊 `:table` – Lista em formato de tabela

Opções específicas

Opção	Tipo	Descrição
`thead`	Boolean	Exibe ou oculta o cabeçalho da tabela (`<thead>`)
`panel`	Boolean	Envolve a tabela em um painel visual (borda, sombra etc.)

Exemplo

list :table_name, type: :table, thead: true, panel: true do
end

📊 `:cards` – Lista de cards

Opções específicas

Opção	Tipo	Descrição
`card_size`	Integer	Tamanho de cada card em colunas de 1 a 12

Exemplo

list :cards_name, type: :cards, card_size: 3 do
end

🌳 `:tree` – Lista em formato de árvore (hierarquia)

Opções específicas

Opção	Tipo	Descrição
`expand`	Hash ou nil	Se presente, define a rota e ação usada para expandir os nós dinamicamente. Se ausente, tenta usar o atributo `children` do resource para renderizar filhos.
`thead`	Boolean	Exibe cabeçalho
`panel`	Boolean	Envolve a lista em painel

Exemplo 1 – usando `children` no JSON

list :tree_name, type: :tree do
  add :name
end

Exemplo 2 – usando `expand` por rota

list :tree_name, type: :tree, expand: { get: "/api/v1/customers/:resource.id/addresses", update: "children" } do
end

Use update: "children" para que ao clicar em expandir e puxar os itens pela rota definida no expand, a lista atualize apenas os filhos do item clicável no frontend do Nerdify.

📅 `:calendar` – Lista em formato de calendário

Opções específicas

Opção	Tipo	Descrição
`click_empty`	Hash	Ação disparada ao clicar em uma célula vazia
`calendar_data`	Hash	Mapeia os campos do resource que serão usados como `title`, `start`, `end`
`calendar_options`	Hash	Passa opções diretamente para o FullCalendar.js (ex: `initialView`, `headerToolbar`)

Exemplo

list :calendar_name, type: :calendar,
     click_empty: { redirect_to: "new", open_in: :dialog },
     calendar_data: { title: :title, start: :date_start, end: :date_end },
     calendar_options: {
       initialView: "month",
       headerToolbar: {
         left: "prev,next today",
         center: "title",
         right: "month,day,week"
       }
     } do
end

🗃️ `:kanban` – Lista em colunas arrastáveis

Opções específicas

Opção	Tipo	Descrição
`group`	Hash	Agrupamento de cards por coluna. Ex: `{ by: :field, field: :status }`
`draggable`	Bool	Permite ou não arrastar os itens
`drop_item`	Hash	Define o comportamento ao soltar um item em outra coluna
`column_height`	Int	Altura fixa de cada coluna em unidades

Exemplo

list :kanban_name, type: :kanban,
     group: { by: :field, field: :status, columns: %w[new pending done] },
     draggable: true,
     drop_item: {
      if: {
        "resource.status == 'pending'" => {
          put: ":resource.id",
          data: { tarefa: { status: ":resource.status" } },
          success: { toast: :success, update: "resource" },
          error: { toast: :error, update: "resource" }
        }
      }
     } do
end

🕘 `:timeline` – Lista vertical com marcação temporal

Opções específicas

Opção	Tipo	Descrição
`header`	Hash	Define o que aparece como cabeçalho de cada item da linha (ex: `created_at`)
`icon`	Hash	Ícone que aparece à esquerda do item. Pode usar nomes dinâmicos (`resource.icon`)
`line`	Hash	Estilo da linha vertical: cor e espessura

Exemplo

list :timeline_name, type: :timeline,
     header: { html: "resource.created_at", size: 1 },
     icon: { name: "resource.type", background: "primary", color: "light" },
     line: { color: "default", size: 2 } do
end

🧱 Estrutura de conteúdo dentro de listas: `add` e `component`

Dentro de uma lista no Nerdify, você pode definir quais dados ou visualizações cada item irá exibir utilizando duas formas principais:

➕ `add`

O método add :field_name permite incluir um campo previamente definido no modelo (através de field :field_name). Ele reutiliza todas as configurações daquele field, como:

tipo de componente
input type
tradução
máscara
validações
estilos

⚠️ O add só funciona no primeiro nível da lista. Ou seja, não pode ser usado dentro de um component.

🧩 `component`

O método component permite adicionar qualquer componente customizado, como textos, imagens, botões, containers, ícones etc. Ele permite criar layouts ricos e totalmente personalizados para cada item da lista.

💡 Use component para montar visualizações específicas e independentes da estrutura dos fields definidos no modelo.

📌 Como funcionam nas diferentes listas

Tipo de Lista	Papel do `add` e `component`
`:table`	Cada `add` ou `component` forma uma coluna da tabela
`:tree`	Assim como na tabela, compõem colunas hierárquicas
`:kanban`	Formam o layout dos cards em cada coluna
`:custom`	Permitem montar qualquer tipo de template para o item
`:timeline`	Combinam texto, imagem, ícone e HTML para formar cada linha
`:calendar`	Não utiliza `add` nem `component` — exibição é automática via `calendar_data`

🔍 Exemplos

🟧 Tabela simples com `add`

list :custoemrs, type: :table do
  add :name
  add :email
end

🟩 Kanban com `component` customizado

list :tasks, type: :kanban, group: { by: :status, columns: %w[pending done] } do
  component :container, size: 12 do
    component :text, name: :task_name, styles: { font_weight: 6 }
    component :text, name: :user_name, styles: { font_size: 5 }
  end
end

🟦 Timeline com `component`

list :activities, type: :timeline do
  component :text, name: :title, type: :p
  component :html, name: :description
end

📚 Mais sobre componentes e templates

A flexibilidade de usar component permite criar qualquer tipo de visual ou experiência de usuário dentro das listas do Nerdify.

🔗 Para aprender a montar layouts avançados, condicional rendering, hierarquias visuais e agrupamentos, consulte a seção de Templates e Componentes da documentação.

✅ Estrutura básica​

⚙️ Opções padrão do list​

🔀 Integração com Actions​

✅ click_item​

✅ selectable​

↕️ sortable​

🛠️ Alternância entre listas​

🔍 Tipos de lista suportados​

🎯 Opções específicas por tipo de lista​

📊 :table – Lista em formato de tabela​

Opções específicas​

Exemplo​

📊 :cards – Lista de cards​

Opções específicas​

Exemplo​

🌳 :tree – Lista em formato de árvore (hierarquia)​

Opções específicas​

Exemplo 1 – usando children no JSON​

Exemplo 2 – usando expand por rota​

📅 :calendar – Lista em formato de calendário​

Opções específicas​

Exemplo​

🗃️ :kanban – Lista em colunas arrastáveis​

Opções específicas​

Exemplo​

🕘 :timeline – Lista vertical com marcação temporal​

Opções específicas​

Exemplo​

🧱 Estrutura de conteúdo dentro de listas: add e component​

➕ add​

🧩 component​

📌 Como funcionam nas diferentes listas​

🔍 Exemplos​

🟧 Tabela simples com add​

🟩 Kanban com component customizado​

🟦 Timeline com component​

📚 Mais sobre componentes e templates​

✅ Estrutura básica

⚙️ Opções padrão do `list`

🔀 Integração com Actions

✅ `click_item`

✅ `selectable`

↕️ `sortable`

🛠️ Alternância entre listas

🔍 Tipos de lista suportados

🎯 Opções específicas por tipo de lista

📊 `:table` – Lista em formato de tabela

Opções específicas

Exemplo

📊 `:cards` – Lista de cards

Opções específicas

Exemplo

🌳 `:tree` – Lista em formato de árvore (hierarquia)

Opções específicas

Exemplo 1 – usando `children` no JSON

Exemplo 2 – usando `expand` por rota

📅 `:calendar` – Lista em formato de calendário

Opções específicas

Exemplo

🗃️ `:kanban` – Lista em colunas arrastáveis

Opções específicas

Exemplo

🕘 `:timeline` – Lista vertical com marcação temporal

Opções específicas

Exemplo

🧱 Estrutura de conteúdo dentro de listas: `add` e `component`

➕ `add`

🧩 `component`

📌 Como funcionam nas diferentes listas

🔍 Exemplos

🟧 Tabela simples com `add`

🟩 Kanban com `component` customizado

🟦 Timeline com `component`

📚 Mais sobre componentes e templates